@independo/inderun-contracts 0.2.2 → 0.3.0-dev.10
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/generated/index.d.ts +3 -0
- package/dist/generated/index.d.ts.map +1 -1
- package/dist/generated/route-plan.d.ts +13 -1
- package/dist/generated/route-plan.d.ts.map +1 -1
- package/dist/generated/route-planner-input.d.ts +43 -1
- package/dist/generated/route-planner-input.d.ts.map +1 -1
- package/dist/generated/schemas.d.ts +575 -3
- package/dist/generated/schemas.d.ts.map +1 -1
- package/dist/generated/schemas.js +734 -2
- package/dist/generated/stream-event.d.ts +141 -0
- package/dist/generated/stream-event.d.ts.map +1 -0
- package/dist/generated/stream-event.js +2 -0
- package/dist/generated/stream-run.d.ts +31 -0
- package/dist/generated/stream-run.d.ts.map +1 -0
- package/dist/generated/stream-run.js +2 -0
- package/dist/generated/stream-terminal-outcome.d.ts +181 -0
- package/dist/generated/stream-terminal-outcome.d.ts.map +1 -0
- package/dist/generated/stream-terminal-outcome.js +2 -0
- package/dist/generated/telemetry-event.d.ts +1 -1
- package/dist/generated/telemetry-event.d.ts.map +1 -1
- package/dist/host.d.ts +84 -0
- package/dist/host.d.ts.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/validators.d.ts +9 -0
- package/dist/validators.d.ts.map +1 -1
- package/dist/validators.js +26 -1
- package/package.json +2 -2
|
@@ -463,7 +463,13 @@ export const telemetryEventSchema = {
|
|
|
463
463
|
"enum": [
|
|
464
464
|
"route_decided",
|
|
465
465
|
"attempt_succeeded",
|
|
466
|
-
"attempt_failed"
|
|
466
|
+
"attempt_failed",
|
|
467
|
+
"stream_attempt_started",
|
|
468
|
+
"stream_attempt_succeeded",
|
|
469
|
+
"stream_attempt_failed",
|
|
470
|
+
"stream_completed",
|
|
471
|
+
"stream_failed",
|
|
472
|
+
"stream_cancelled"
|
|
467
473
|
]
|
|
468
474
|
},
|
|
469
475
|
"runId": {
|
|
@@ -487,7 +493,7 @@ export const routePlannerInputSchema = {
|
|
|
487
493
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
488
494
|
"$id": "https://schemas.inderun.dev/1.0/route-planner-input.schema.json",
|
|
489
495
|
"title": "RoutePlannerInput",
|
|
490
|
-
"description": "Pure data input contract for deterministic shared-core
|
|
496
|
+
"description": "Pure data input contract for deterministic shared-core route planning.",
|
|
491
497
|
"type": "object",
|
|
492
498
|
"additionalProperties": true,
|
|
493
499
|
"required": [
|
|
@@ -511,6 +517,13 @@ export const routePlannerInputSchema = {
|
|
|
511
517
|
}
|
|
512
518
|
}
|
|
513
519
|
},
|
|
520
|
+
"interactionMode": {
|
|
521
|
+
"description": "Interaction mode the caller is requesting. Absent means 'run' (Mode 1), so planner inputs produced before this field existed keep their exact Mode-1 semantics. The mode filters eligible providers; it never changes candidate ordering.",
|
|
522
|
+
"enum": [
|
|
523
|
+
"run",
|
|
524
|
+
"stream"
|
|
525
|
+
]
|
|
526
|
+
},
|
|
514
527
|
"constraints": {
|
|
515
528
|
"description": "Hard routing constraints evaluated before provider selection.",
|
|
516
529
|
"type": "object",
|
|
@@ -596,9 +609,21 @@ export const routePlannerInputSchema = {
|
|
|
596
609
|
"properties": {
|
|
597
610
|
"run": {
|
|
598
611
|
"type": "boolean"
|
|
612
|
+
},
|
|
613
|
+
"streaming": {
|
|
614
|
+
"description": "Whether the provider statically declares Mode-2 streaming. Absent is treated as false: a descriptor that predates this field cannot be assumed to stream.",
|
|
615
|
+
"type": "boolean"
|
|
599
616
|
}
|
|
600
617
|
}
|
|
601
618
|
},
|
|
619
|
+
"cancel": {
|
|
620
|
+
"description": "Cancellation guarantee the provider offers. Carried for route explanations and telemetry; the planner does not filter on it.",
|
|
621
|
+
"enum": [
|
|
622
|
+
"hard",
|
|
623
|
+
"soft",
|
|
624
|
+
"none"
|
|
625
|
+
]
|
|
626
|
+
},
|
|
602
627
|
"tasks": {
|
|
603
628
|
"type": "array",
|
|
604
629
|
"items": {
|
|
@@ -641,6 +666,19 @@ export const routePlannerInputSchema = {
|
|
|
641
666
|
"reason": {
|
|
642
667
|
"type": "string",
|
|
643
668
|
"minLength": 1
|
|
669
|
+
},
|
|
670
|
+
"streamingAvailable": {
|
|
671
|
+
"description": "Whether the provider can stream right now in this host environment. Absent inherits the static descriptor.supports.streaming value.",
|
|
672
|
+
"type": "boolean"
|
|
673
|
+
},
|
|
674
|
+
"streamingUnavailableReason": {
|
|
675
|
+
"description": "Human-readable explanation used when streamingAvailable is false. Absent lets the planner synthesize a default message.",
|
|
676
|
+
"type": "string",
|
|
677
|
+
"minLength": 1
|
|
678
|
+
},
|
|
679
|
+
"cancellationAvailable": {
|
|
680
|
+
"description": "Whether cancellation is honored right now in this host environment. Absent inherits the static descriptor.cancel value (any value other than 'none' means available).",
|
|
681
|
+
"type": "boolean"
|
|
644
682
|
}
|
|
645
683
|
}
|
|
646
684
|
}
|
|
@@ -724,9 +762,12 @@ export const routePlanSchema = {
|
|
|
724
762
|
],
|
|
725
763
|
"properties": {
|
|
726
764
|
"code": {
|
|
765
|
+
"description": "Normalized rejection reason. 'streaming_not_supported' means the descriptor does not statically declare Mode-2 streaming; 'streaming_unavailable' means it declares streaming but the dynamic capability snapshot reports it cannot stream in the current host environment.",
|
|
727
766
|
"enum": [
|
|
728
767
|
"task_not_supported",
|
|
729
768
|
"run_not_supported",
|
|
769
|
+
"streaming_not_supported",
|
|
770
|
+
"streaming_unavailable",
|
|
730
771
|
"privacy_constraint",
|
|
731
772
|
"cloud_constraint",
|
|
732
773
|
"offline",
|
|
@@ -945,3 +986,694 @@ export const modelPackageSchema = {
|
|
|
945
986
|
}
|
|
946
987
|
}
|
|
947
988
|
};
|
|
989
|
+
export const streamRunSchema = {
|
|
990
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
991
|
+
"$id": "https://schemas.inderun.dev/1.0/stream-run.schema.json",
|
|
992
|
+
"title": "StreamRunHandle",
|
|
993
|
+
"description": "The serializable acknowledgment returned when a Mode 2 stream is opened, before any StreamEvent has arrived. This is the identity/correlation contract only: the live, consumable stream itself is a platform-idiomatic construct (an AsyncIterable<StreamEvent> in TypeScript, a Flow<StreamEvent> in Kotlin, an AsyncThrowingStream<StreamEvent, Error> in Swift) that is never serialized and is out of scope for this schema. Design seam only; no engine or provider implementation exists yet (see docs/architecture/architecture.md).",
|
|
994
|
+
"type": "object",
|
|
995
|
+
"additionalProperties": true,
|
|
996
|
+
"required": [
|
|
997
|
+
"schemaVersion",
|
|
998
|
+
"runId",
|
|
999
|
+
"startedAt"
|
|
1000
|
+
],
|
|
1001
|
+
"properties": {
|
|
1002
|
+
"schemaVersion": {
|
|
1003
|
+
"description": "Contract schema version used to interpret this handle payload.",
|
|
1004
|
+
"const": "1.0"
|
|
1005
|
+
},
|
|
1006
|
+
"runId": {
|
|
1007
|
+
"description": "A unique, opaque identifier assigned by the engine for this stream run. Every StreamEvent and the terminal StreamTerminalOutcome for this run carry the same runId, matching the identity convention used by TaskResult.runId and IndeRunError.runId.",
|
|
1008
|
+
"type": "string",
|
|
1009
|
+
"minLength": 1
|
|
1010
|
+
},
|
|
1011
|
+
"startedAt": {
|
|
1012
|
+
"description": "Wall-clock time the stream run was opened, in Unix epoch milliseconds.",
|
|
1013
|
+
"type": "number",
|
|
1014
|
+
"minimum": 0
|
|
1015
|
+
},
|
|
1016
|
+
"providerId": {
|
|
1017
|
+
"description": "Identifier of the provider selected to service this stream, if routing has completed by the time the handle is returned. Absent while route selection is still pending.",
|
|
1018
|
+
"type": "string",
|
|
1019
|
+
"minLength": 1
|
|
1020
|
+
}
|
|
1021
|
+
}
|
|
1022
|
+
};
|
|
1023
|
+
export const streamEventSchema = {
|
|
1024
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
1025
|
+
"$id": "https://schemas.inderun.dev/1.0/stream-event.schema.json",
|
|
1026
|
+
"title": "StreamEvent",
|
|
1027
|
+
"description": "The canonical Mode 2 streaming event union, discriminated by 'type'. Every variant shares an envelope of schemaVersion, runId, sequence, timestamp, and type. 'sequence' is the ordering authority for events within a run (a monotonically increasing integer starting at 0 per runId) — consumers must order by 'sequence', not by arrival order, since a bridge hop (e.g. a future Capacitor bridge) could reorder delivery. Known event types are split into user-visible content ('content_delta', 'content_snapshot') and mechanical/diagnostic types ('lifecycle', 'diagnostic', 'terminal') so SDKs can distinguish what belongs in a chat UI from what is orchestration detail. Forward compatibility: this union closes with an open 'unknown_event' branch so a consumer built against an older revision of this schema does not hard-fail when a newer, additive minor revision introduces a new known type; per contracts/README.md's schema evolution policy, SDKs must treat an unrecognized 'type' as ignore-or-pass-through-for-diagnostics, never as a hard error. Design seam only; no engine or provider implementation exists yet (see docs/architecture/architecture.md).",
|
|
1028
|
+
"oneOf": [
|
|
1029
|
+
{
|
|
1030
|
+
"type": "object",
|
|
1031
|
+
"additionalProperties": true,
|
|
1032
|
+
"required": [
|
|
1033
|
+
"schemaVersion",
|
|
1034
|
+
"runId",
|
|
1035
|
+
"sequence",
|
|
1036
|
+
"timestamp",
|
|
1037
|
+
"type",
|
|
1038
|
+
"payload"
|
|
1039
|
+
],
|
|
1040
|
+
"properties": {
|
|
1041
|
+
"schemaVersion": {
|
|
1042
|
+
"description": "Contract schema version used to interpret this event payload.",
|
|
1043
|
+
"const": "1.0"
|
|
1044
|
+
},
|
|
1045
|
+
"runId": {
|
|
1046
|
+
"description": "Opaque run identifier this event belongs to, matching StreamRunHandle.runId.",
|
|
1047
|
+
"type": "string",
|
|
1048
|
+
"minLength": 1
|
|
1049
|
+
},
|
|
1050
|
+
"sequence": {
|
|
1051
|
+
"description": "Zero-based, monotonically increasing event index within this run. The ordering authority; do not rely on delivery/arrival order.",
|
|
1052
|
+
"type": "integer",
|
|
1053
|
+
"minimum": 0
|
|
1054
|
+
},
|
|
1055
|
+
"timestamp": {
|
|
1056
|
+
"description": "Wall-clock event timestamp in Unix epoch milliseconds.",
|
|
1057
|
+
"type": "number",
|
|
1058
|
+
"minimum": 0
|
|
1059
|
+
},
|
|
1060
|
+
"type": {
|
|
1061
|
+
"description": "User-visible content: an incremental text increment since the previous content_delta or content_snapshot event. Mirrors ProviderDescriptor.streamingStyle 'tokens'/'chunks' (packages/inderun-web/src/core/provider.ts) — providers reporting either style normalize to content_delta.",
|
|
1062
|
+
"const": "content_delta"
|
|
1063
|
+
},
|
|
1064
|
+
"payload": {
|
|
1065
|
+
"type": "object",
|
|
1066
|
+
"additionalProperties": true,
|
|
1067
|
+
"required": [
|
|
1068
|
+
"text"
|
|
1069
|
+
],
|
|
1070
|
+
"properties": {
|
|
1071
|
+
"text": {
|
|
1072
|
+
"description": "The incremental text produced since the previous content event.",
|
|
1073
|
+
"type": "string"
|
|
1074
|
+
}
|
|
1075
|
+
}
|
|
1076
|
+
}
|
|
1077
|
+
}
|
|
1078
|
+
},
|
|
1079
|
+
{
|
|
1080
|
+
"type": "object",
|
|
1081
|
+
"additionalProperties": true,
|
|
1082
|
+
"required": [
|
|
1083
|
+
"schemaVersion",
|
|
1084
|
+
"runId",
|
|
1085
|
+
"sequence",
|
|
1086
|
+
"timestamp",
|
|
1087
|
+
"type",
|
|
1088
|
+
"payload"
|
|
1089
|
+
],
|
|
1090
|
+
"properties": {
|
|
1091
|
+
"schemaVersion": {
|
|
1092
|
+
"description": "Contract schema version used to interpret this event payload.",
|
|
1093
|
+
"const": "1.0"
|
|
1094
|
+
},
|
|
1095
|
+
"runId": {
|
|
1096
|
+
"description": "Opaque run identifier this event belongs to, matching StreamRunHandle.runId.",
|
|
1097
|
+
"type": "string",
|
|
1098
|
+
"minLength": 1
|
|
1099
|
+
},
|
|
1100
|
+
"sequence": {
|
|
1101
|
+
"description": "Zero-based, monotonically increasing event index within this run. The ordering authority; do not rely on delivery/arrival order.",
|
|
1102
|
+
"type": "integer",
|
|
1103
|
+
"minimum": 0
|
|
1104
|
+
},
|
|
1105
|
+
"timestamp": {
|
|
1106
|
+
"description": "Wall-clock event timestamp in Unix epoch milliseconds.",
|
|
1107
|
+
"type": "number",
|
|
1108
|
+
"minimum": 0
|
|
1109
|
+
},
|
|
1110
|
+
"type": {
|
|
1111
|
+
"description": "User-visible content: the full cumulative text produced so far. Mirrors ProviderDescriptor.streamingStyle 'snapshots' (packages/inderun-web/src/core/provider.ts) — providers reporting that style normalize to content_snapshot rather than content_delta.",
|
|
1112
|
+
"const": "content_snapshot"
|
|
1113
|
+
},
|
|
1114
|
+
"payload": {
|
|
1115
|
+
"type": "object",
|
|
1116
|
+
"additionalProperties": true,
|
|
1117
|
+
"required": [
|
|
1118
|
+
"text"
|
|
1119
|
+
],
|
|
1120
|
+
"properties": {
|
|
1121
|
+
"text": {
|
|
1122
|
+
"description": "The full cumulative text produced by the run so far.",
|
|
1123
|
+
"type": "string"
|
|
1124
|
+
}
|
|
1125
|
+
}
|
|
1126
|
+
}
|
|
1127
|
+
}
|
|
1128
|
+
},
|
|
1129
|
+
{
|
|
1130
|
+
"type": "object",
|
|
1131
|
+
"additionalProperties": true,
|
|
1132
|
+
"required": [
|
|
1133
|
+
"schemaVersion",
|
|
1134
|
+
"runId",
|
|
1135
|
+
"sequence",
|
|
1136
|
+
"timestamp",
|
|
1137
|
+
"type",
|
|
1138
|
+
"payload"
|
|
1139
|
+
],
|
|
1140
|
+
"properties": {
|
|
1141
|
+
"schemaVersion": {
|
|
1142
|
+
"description": "Contract schema version used to interpret this event payload.",
|
|
1143
|
+
"const": "1.0"
|
|
1144
|
+
},
|
|
1145
|
+
"runId": {
|
|
1146
|
+
"description": "Opaque run identifier this event belongs to, matching StreamRunHandle.runId.",
|
|
1147
|
+
"type": "string",
|
|
1148
|
+
"minLength": 1
|
|
1149
|
+
},
|
|
1150
|
+
"sequence": {
|
|
1151
|
+
"description": "Zero-based, monotonically increasing event index within this run. The ordering authority; do not rely on delivery/arrival order.",
|
|
1152
|
+
"type": "integer",
|
|
1153
|
+
"minimum": 0
|
|
1154
|
+
},
|
|
1155
|
+
"timestamp": {
|
|
1156
|
+
"description": "Wall-clock event timestamp in Unix epoch milliseconds.",
|
|
1157
|
+
"type": "number",
|
|
1158
|
+
"minimum": 0
|
|
1159
|
+
},
|
|
1160
|
+
"type": {
|
|
1161
|
+
"description": "Mechanical/diagnostic: a run lifecycle transition (e.g. provider selection, execution start). Not user-visible content; not part of the generated text.",
|
|
1162
|
+
"const": "lifecycle"
|
|
1163
|
+
},
|
|
1164
|
+
"payload": {
|
|
1165
|
+
"type": "object",
|
|
1166
|
+
"additionalProperties": true,
|
|
1167
|
+
"required": [
|
|
1168
|
+
"phase"
|
|
1169
|
+
],
|
|
1170
|
+
"properties": {
|
|
1171
|
+
"phase": {
|
|
1172
|
+
"description": "The lifecycle phase reached.",
|
|
1173
|
+
"enum": [
|
|
1174
|
+
"provider_selected",
|
|
1175
|
+
"started"
|
|
1176
|
+
]
|
|
1177
|
+
}
|
|
1178
|
+
}
|
|
1179
|
+
}
|
|
1180
|
+
}
|
|
1181
|
+
},
|
|
1182
|
+
{
|
|
1183
|
+
"type": "object",
|
|
1184
|
+
"additionalProperties": true,
|
|
1185
|
+
"required": [
|
|
1186
|
+
"schemaVersion",
|
|
1187
|
+
"runId",
|
|
1188
|
+
"sequence",
|
|
1189
|
+
"timestamp",
|
|
1190
|
+
"type",
|
|
1191
|
+
"payload"
|
|
1192
|
+
],
|
|
1193
|
+
"properties": {
|
|
1194
|
+
"schemaVersion": {
|
|
1195
|
+
"description": "Contract schema version used to interpret this event payload.",
|
|
1196
|
+
"const": "1.0"
|
|
1197
|
+
},
|
|
1198
|
+
"runId": {
|
|
1199
|
+
"description": "Opaque run identifier this event belongs to, matching StreamRunHandle.runId.",
|
|
1200
|
+
"type": "string",
|
|
1201
|
+
"minLength": 1
|
|
1202
|
+
},
|
|
1203
|
+
"sequence": {
|
|
1204
|
+
"description": "Zero-based, monotonically increasing event index within this run. The ordering authority; do not rely on delivery/arrival order.",
|
|
1205
|
+
"type": "integer",
|
|
1206
|
+
"minimum": 0
|
|
1207
|
+
},
|
|
1208
|
+
"timestamp": {
|
|
1209
|
+
"description": "Wall-clock event timestamp in Unix epoch milliseconds.",
|
|
1210
|
+
"type": "number",
|
|
1211
|
+
"minimum": 0
|
|
1212
|
+
},
|
|
1213
|
+
"type": {
|
|
1214
|
+
"description": "Mechanical/diagnostic: free-form orchestration or provider diagnostic detail. Not user-visible content.",
|
|
1215
|
+
"const": "diagnostic"
|
|
1216
|
+
},
|
|
1217
|
+
"payload": {
|
|
1218
|
+
"description": "Event-specific diagnostic metadata. It must not contain prompt payloads or raw secrets, matching the same guardrail as TelemetryEvent.payload.",
|
|
1219
|
+
"type": "object",
|
|
1220
|
+
"additionalProperties": true
|
|
1221
|
+
}
|
|
1222
|
+
}
|
|
1223
|
+
},
|
|
1224
|
+
{
|
|
1225
|
+
"type": "object",
|
|
1226
|
+
"additionalProperties": true,
|
|
1227
|
+
"required": [
|
|
1228
|
+
"schemaVersion",
|
|
1229
|
+
"runId",
|
|
1230
|
+
"sequence",
|
|
1231
|
+
"timestamp",
|
|
1232
|
+
"type",
|
|
1233
|
+
"payload"
|
|
1234
|
+
],
|
|
1235
|
+
"properties": {
|
|
1236
|
+
"schemaVersion": {
|
|
1237
|
+
"description": "Contract schema version used to interpret this event payload.",
|
|
1238
|
+
"const": "1.0"
|
|
1239
|
+
},
|
|
1240
|
+
"runId": {
|
|
1241
|
+
"description": "Opaque run identifier this event belongs to, matching StreamRunHandle.runId.",
|
|
1242
|
+
"type": "string",
|
|
1243
|
+
"minLength": 1
|
|
1244
|
+
},
|
|
1245
|
+
"sequence": {
|
|
1246
|
+
"description": "Zero-based, monotonically increasing event index within this run. This is always the highest sequence number for the run: the terminal event.",
|
|
1247
|
+
"type": "integer",
|
|
1248
|
+
"minimum": 0
|
|
1249
|
+
},
|
|
1250
|
+
"timestamp": {
|
|
1251
|
+
"description": "Wall-clock event timestamp in Unix epoch milliseconds.",
|
|
1252
|
+
"type": "number",
|
|
1253
|
+
"minimum": 0
|
|
1254
|
+
},
|
|
1255
|
+
"type": {
|
|
1256
|
+
"description": "Terminal: the last event of the run, carrying the mutually-exclusive completion/error/cancellation outcome. No further StreamEvent is delivered for this runId after this event.",
|
|
1257
|
+
"const": "terminal"
|
|
1258
|
+
},
|
|
1259
|
+
"payload": {
|
|
1260
|
+
"description": "Structurally identical to StreamTerminalOutcome (contracts/schemas/stream-terminal-outcome.schema.json), duplicated by value here rather than by $ref, matching this repo's schema convention of no cross-file references. Keep both shapes in sync; a cross-check test asserts a shared fixture validates against both schemas.",
|
|
1261
|
+
"oneOf": [
|
|
1262
|
+
{
|
|
1263
|
+
"type": "object",
|
|
1264
|
+
"additionalProperties": true,
|
|
1265
|
+
"required": [
|
|
1266
|
+
"schemaVersion",
|
|
1267
|
+
"runId",
|
|
1268
|
+
"outcome",
|
|
1269
|
+
"finalText"
|
|
1270
|
+
],
|
|
1271
|
+
"properties": {
|
|
1272
|
+
"schemaVersion": {
|
|
1273
|
+
"const": "1.0"
|
|
1274
|
+
},
|
|
1275
|
+
"runId": {
|
|
1276
|
+
"type": "string",
|
|
1277
|
+
"minLength": 1
|
|
1278
|
+
},
|
|
1279
|
+
"outcome": {
|
|
1280
|
+
"const": "completed"
|
|
1281
|
+
},
|
|
1282
|
+
"finalText": {
|
|
1283
|
+
"type": "string"
|
|
1284
|
+
},
|
|
1285
|
+
"finishReason": {
|
|
1286
|
+
"enum": [
|
|
1287
|
+
"stop",
|
|
1288
|
+
"length",
|
|
1289
|
+
"cancelled",
|
|
1290
|
+
"error"
|
|
1291
|
+
]
|
|
1292
|
+
},
|
|
1293
|
+
"usage": {
|
|
1294
|
+
"type": "object",
|
|
1295
|
+
"additionalProperties": true,
|
|
1296
|
+
"properties": {
|
|
1297
|
+
"inputTokens": {
|
|
1298
|
+
"type": "integer",
|
|
1299
|
+
"minimum": 0
|
|
1300
|
+
},
|
|
1301
|
+
"outputTokens": {
|
|
1302
|
+
"type": "integer",
|
|
1303
|
+
"minimum": 0
|
|
1304
|
+
},
|
|
1305
|
+
"totalTokens": {
|
|
1306
|
+
"type": "integer",
|
|
1307
|
+
"minimum": 0
|
|
1308
|
+
}
|
|
1309
|
+
}
|
|
1310
|
+
},
|
|
1311
|
+
"telemetry": {
|
|
1312
|
+
"type": "object",
|
|
1313
|
+
"additionalProperties": true,
|
|
1314
|
+
"required": [
|
|
1315
|
+
"providerUsed",
|
|
1316
|
+
"totalMs"
|
|
1317
|
+
],
|
|
1318
|
+
"properties": {
|
|
1319
|
+
"providerUsed": {
|
|
1320
|
+
"type": "string",
|
|
1321
|
+
"minLength": 1
|
|
1322
|
+
},
|
|
1323
|
+
"totalMs": {
|
|
1324
|
+
"type": "number",
|
|
1325
|
+
"minimum": 0
|
|
1326
|
+
}
|
|
1327
|
+
}
|
|
1328
|
+
}
|
|
1329
|
+
}
|
|
1330
|
+
},
|
|
1331
|
+
{
|
|
1332
|
+
"type": "object",
|
|
1333
|
+
"additionalProperties": true,
|
|
1334
|
+
"required": [
|
|
1335
|
+
"schemaVersion",
|
|
1336
|
+
"runId",
|
|
1337
|
+
"outcome",
|
|
1338
|
+
"error"
|
|
1339
|
+
],
|
|
1340
|
+
"properties": {
|
|
1341
|
+
"schemaVersion": {
|
|
1342
|
+
"const": "1.0"
|
|
1343
|
+
},
|
|
1344
|
+
"runId": {
|
|
1345
|
+
"type": "string",
|
|
1346
|
+
"minLength": 1
|
|
1347
|
+
},
|
|
1348
|
+
"outcome": {
|
|
1349
|
+
"const": "error"
|
|
1350
|
+
},
|
|
1351
|
+
"error": {
|
|
1352
|
+
"type": "object",
|
|
1353
|
+
"additionalProperties": true,
|
|
1354
|
+
"required": [
|
|
1355
|
+
"schemaVersion",
|
|
1356
|
+
"errorClass",
|
|
1357
|
+
"message"
|
|
1358
|
+
],
|
|
1359
|
+
"properties": {
|
|
1360
|
+
"schemaVersion": {
|
|
1361
|
+
"const": "1.0"
|
|
1362
|
+
},
|
|
1363
|
+
"errorClass": {
|
|
1364
|
+
"enum": [
|
|
1365
|
+
"CapabilityMismatch",
|
|
1366
|
+
"Offline",
|
|
1367
|
+
"AuthError",
|
|
1368
|
+
"RateLimited",
|
|
1369
|
+
"Timeout",
|
|
1370
|
+
"Unavailable",
|
|
1371
|
+
"Internal"
|
|
1372
|
+
]
|
|
1373
|
+
},
|
|
1374
|
+
"message": {
|
|
1375
|
+
"type": "string",
|
|
1376
|
+
"minLength": 1
|
|
1377
|
+
},
|
|
1378
|
+
"providerId": {
|
|
1379
|
+
"type": "string",
|
|
1380
|
+
"minLength": 1
|
|
1381
|
+
},
|
|
1382
|
+
"retryable": {
|
|
1383
|
+
"type": "boolean"
|
|
1384
|
+
},
|
|
1385
|
+
"retryAfterMs": {
|
|
1386
|
+
"type": "integer",
|
|
1387
|
+
"minimum": 0
|
|
1388
|
+
},
|
|
1389
|
+
"details": {
|
|
1390
|
+
"type": "object",
|
|
1391
|
+
"additionalProperties": true
|
|
1392
|
+
}
|
|
1393
|
+
}
|
|
1394
|
+
}
|
|
1395
|
+
}
|
|
1396
|
+
},
|
|
1397
|
+
{
|
|
1398
|
+
"type": "object",
|
|
1399
|
+
"additionalProperties": true,
|
|
1400
|
+
"required": [
|
|
1401
|
+
"schemaVersion",
|
|
1402
|
+
"runId",
|
|
1403
|
+
"outcome",
|
|
1404
|
+
"partialText"
|
|
1405
|
+
],
|
|
1406
|
+
"properties": {
|
|
1407
|
+
"schemaVersion": {
|
|
1408
|
+
"const": "1.0"
|
|
1409
|
+
},
|
|
1410
|
+
"runId": {
|
|
1411
|
+
"type": "string",
|
|
1412
|
+
"minLength": 1
|
|
1413
|
+
},
|
|
1414
|
+
"outcome": {
|
|
1415
|
+
"const": "cancelled"
|
|
1416
|
+
},
|
|
1417
|
+
"partialText": {
|
|
1418
|
+
"type": "string"
|
|
1419
|
+
},
|
|
1420
|
+
"reason": {
|
|
1421
|
+
"type": "string"
|
|
1422
|
+
}
|
|
1423
|
+
}
|
|
1424
|
+
}
|
|
1425
|
+
]
|
|
1426
|
+
}
|
|
1427
|
+
}
|
|
1428
|
+
},
|
|
1429
|
+
{
|
|
1430
|
+
"type": "object",
|
|
1431
|
+
"additionalProperties": true,
|
|
1432
|
+
"required": [
|
|
1433
|
+
"schemaVersion",
|
|
1434
|
+
"runId",
|
|
1435
|
+
"sequence",
|
|
1436
|
+
"timestamp",
|
|
1437
|
+
"type"
|
|
1438
|
+
],
|
|
1439
|
+
"properties": {
|
|
1440
|
+
"schemaVersion": {
|
|
1441
|
+
"description": "Contract schema version used to interpret this event payload.",
|
|
1442
|
+
"const": "1.0"
|
|
1443
|
+
},
|
|
1444
|
+
"runId": {
|
|
1445
|
+
"description": "Opaque run identifier this event belongs to, matching StreamRunHandle.runId.",
|
|
1446
|
+
"type": "string",
|
|
1447
|
+
"minLength": 1
|
|
1448
|
+
},
|
|
1449
|
+
"sequence": {
|
|
1450
|
+
"description": "Zero-based, monotonically increasing event index within this run. The ordering authority; do not rely on delivery/arrival order.",
|
|
1451
|
+
"type": "integer",
|
|
1452
|
+
"minimum": 0
|
|
1453
|
+
},
|
|
1454
|
+
"timestamp": {
|
|
1455
|
+
"description": "Wall-clock event timestamp in Unix epoch milliseconds.",
|
|
1456
|
+
"type": "number",
|
|
1457
|
+
"minimum": 0
|
|
1458
|
+
},
|
|
1459
|
+
"type": {
|
|
1460
|
+
"description": "Forward-compatibility catch-all: any event type not among the known constants above. Exists so a consumer validating against this revision of the schema does not hard-fail when a future additive revision introduces a new known event type; SDKs must ignore or pass through such events for diagnostics rather than treating them as an error.",
|
|
1461
|
+
"type": "string",
|
|
1462
|
+
"not": {
|
|
1463
|
+
"enum": [
|
|
1464
|
+
"content_delta",
|
|
1465
|
+
"content_snapshot",
|
|
1466
|
+
"lifecycle",
|
|
1467
|
+
"diagnostic",
|
|
1468
|
+
"terminal"
|
|
1469
|
+
]
|
|
1470
|
+
}
|
|
1471
|
+
},
|
|
1472
|
+
"payload": {
|
|
1473
|
+
"description": "Optional event-specific payload for the unrecognized type. It must not contain prompt payloads or raw secrets.",
|
|
1474
|
+
"type": "object",
|
|
1475
|
+
"additionalProperties": true
|
|
1476
|
+
}
|
|
1477
|
+
}
|
|
1478
|
+
}
|
|
1479
|
+
]
|
|
1480
|
+
};
|
|
1481
|
+
export const streamTerminalOutcomeSchema = {
|
|
1482
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
1483
|
+
"$id": "https://schemas.inderun.dev/1.0/stream-terminal-outcome.schema.json",
|
|
1484
|
+
"title": "StreamTerminalOutcome",
|
|
1485
|
+
"description": "How a Mode 2 stream run ended. Completion, error, and cancellation are mutually exclusive terminal outcomes, enforced here as a closed set of three oneOf branches discriminated by 'outcome' (unlike StreamEvent.type, this set is not open-ended: the three-way terminal outcome is a fixed architectural guarantee, not something new outcome kinds get added to). Exactly one StreamTerminalOutcome is produced per run, and no further StreamEvent is delivered after it (see docs/architecture/architecture.md, 'Cancellation And Fallback'). This shape is also embedded by value as the payload of the terminal StreamEvent (stream-event.schema.json) so it can additionally be exposed standalone, e.g. as a completion future/promise a stream handle resolves independently of consuming the full event sequence; the two copies must stay structurally identical. Note on additionalProperties: per this repo's forward-compatible convention every branch permits unknown extra fields, so mutual exclusivity is enforced via the required 'outcome' discriminator plus each branch's own required peer field (finalText/error/partialText) being present, not by forbidding a payload from also carrying an unrelated stray field from another branch's vocabulary.",
|
|
1486
|
+
"oneOf": [
|
|
1487
|
+
{
|
|
1488
|
+
"type": "object",
|
|
1489
|
+
"additionalProperties": true,
|
|
1490
|
+
"required": [
|
|
1491
|
+
"schemaVersion",
|
|
1492
|
+
"runId",
|
|
1493
|
+
"outcome",
|
|
1494
|
+
"finalText"
|
|
1495
|
+
],
|
|
1496
|
+
"properties": {
|
|
1497
|
+
"schemaVersion": {
|
|
1498
|
+
"description": "Contract schema version used to interpret this outcome payload.",
|
|
1499
|
+
"const": "1.0"
|
|
1500
|
+
},
|
|
1501
|
+
"runId": {
|
|
1502
|
+
"description": "The stream run this outcome terminates, matching StreamRunHandle.runId and every StreamEvent.runId for the run.",
|
|
1503
|
+
"type": "string",
|
|
1504
|
+
"minLength": 1
|
|
1505
|
+
},
|
|
1506
|
+
"outcome": {
|
|
1507
|
+
"description": "The stream completed normally: every provider-generated event was delivered before this outcome was produced.",
|
|
1508
|
+
"const": "completed"
|
|
1509
|
+
},
|
|
1510
|
+
"finalText": {
|
|
1511
|
+
"description": "The full, cumulative text produced by the run. Equivalent in role to TaskResult.output.text for Mode 1.",
|
|
1512
|
+
"type": "string"
|
|
1513
|
+
},
|
|
1514
|
+
"finishReason": {
|
|
1515
|
+
"description": "How generation ended, mirroring TaskResult.finishReason for Mode 1: 'stop' (natural end), 'length' (hit maxOutputTokens), 'error' (provider reported a non-fatal issue on an otherwise completed run). 'cancelled' is included so this enum stays identical to TaskResult.finishReason, but it is unreachable here: cancellation is its own terminal outcome branch. Optional: providers that do not report a finish reason omit it.",
|
|
1516
|
+
"enum": [
|
|
1517
|
+
"stop",
|
|
1518
|
+
"length",
|
|
1519
|
+
"cancelled",
|
|
1520
|
+
"error"
|
|
1521
|
+
]
|
|
1522
|
+
},
|
|
1523
|
+
"usage": {
|
|
1524
|
+
"description": "Optional metadata regarding the quantity of tokens processed by the provider. Same shape as TaskResult.usage.",
|
|
1525
|
+
"type": "object",
|
|
1526
|
+
"additionalProperties": true,
|
|
1527
|
+
"properties": {
|
|
1528
|
+
"inputTokens": {
|
|
1529
|
+
"description": "Number of input tokens consumed, as reported by the provider.",
|
|
1530
|
+
"type": "integer",
|
|
1531
|
+
"minimum": 0
|
|
1532
|
+
},
|
|
1533
|
+
"outputTokens": {
|
|
1534
|
+
"description": "Number of output tokens generated, as reported by the provider.",
|
|
1535
|
+
"type": "integer",
|
|
1536
|
+
"minimum": 0
|
|
1537
|
+
},
|
|
1538
|
+
"totalTokens": {
|
|
1539
|
+
"description": "Aggregated token count for this request, as reported by the provider.",
|
|
1540
|
+
"type": "integer",
|
|
1541
|
+
"minimum": 0
|
|
1542
|
+
}
|
|
1543
|
+
}
|
|
1544
|
+
},
|
|
1545
|
+
"telemetry": {
|
|
1546
|
+
"description": "Required metadata providing an overview of the execution result and performance metrics. Same shape as TaskResult.telemetry.",
|
|
1547
|
+
"type": "object",
|
|
1548
|
+
"additionalProperties": true,
|
|
1549
|
+
"required": [
|
|
1550
|
+
"providerUsed",
|
|
1551
|
+
"totalMs"
|
|
1552
|
+
],
|
|
1553
|
+
"properties": {
|
|
1554
|
+
"providerUsed": {
|
|
1555
|
+
"description": "The identifier for the specific provider that handled the request (e.g., 'openai_compatible_cloud').",
|
|
1556
|
+
"type": "string",
|
|
1557
|
+
"minLength": 1
|
|
1558
|
+
},
|
|
1559
|
+
"totalMs": {
|
|
1560
|
+
"description": "Measured execution duration in milliseconds, including route selection and result processing.",
|
|
1561
|
+
"type": "number",
|
|
1562
|
+
"minimum": 0
|
|
1563
|
+
}
|
|
1564
|
+
}
|
|
1565
|
+
}
|
|
1566
|
+
}
|
|
1567
|
+
},
|
|
1568
|
+
{
|
|
1569
|
+
"type": "object",
|
|
1570
|
+
"additionalProperties": true,
|
|
1571
|
+
"required": [
|
|
1572
|
+
"schemaVersion",
|
|
1573
|
+
"runId",
|
|
1574
|
+
"outcome",
|
|
1575
|
+
"error"
|
|
1576
|
+
],
|
|
1577
|
+
"properties": {
|
|
1578
|
+
"schemaVersion": {
|
|
1579
|
+
"description": "Contract schema version used to interpret this outcome payload.",
|
|
1580
|
+
"const": "1.0"
|
|
1581
|
+
},
|
|
1582
|
+
"runId": {
|
|
1583
|
+
"description": "The stream run this outcome terminates, matching StreamRunHandle.runId and every StreamEvent.runId for the run.",
|
|
1584
|
+
"type": "string",
|
|
1585
|
+
"minLength": 1
|
|
1586
|
+
},
|
|
1587
|
+
"outcome": {
|
|
1588
|
+
"description": "The stream ended in failure: validation, routing (no eligible provider), or every attempted provider failing.",
|
|
1589
|
+
"const": "error"
|
|
1590
|
+
},
|
|
1591
|
+
"error": {
|
|
1592
|
+
"description": "The normalized error for this failure. Structurally identical to IndeRunError (contracts/schemas/inderun-error.schema.json), duplicated by value here rather than by $ref, matching this repo's schema convention of no cross-file references. Keep both shapes in sync; a cross-check test asserts a shared fixture validates against both schemas.",
|
|
1593
|
+
"type": "object",
|
|
1594
|
+
"additionalProperties": true,
|
|
1595
|
+
"required": [
|
|
1596
|
+
"schemaVersion",
|
|
1597
|
+
"errorClass",
|
|
1598
|
+
"message"
|
|
1599
|
+
],
|
|
1600
|
+
"properties": {
|
|
1601
|
+
"schemaVersion": {
|
|
1602
|
+
"description": "Contract schema version used to interpret the error payload.",
|
|
1603
|
+
"const": "1.0"
|
|
1604
|
+
},
|
|
1605
|
+
"errorClass": {
|
|
1606
|
+
"description": "Normalized error taxonomy, identical to IndeRunError.errorClass: CapabilityMismatch (request needs something no eligible provider supports), Offline/Unavailable (provider unreachable or not ready), AuthError (credential/auth failure), RateLimited (provider throttled the request), Timeout (provider exceeded its execution budget), Internal (unexpected engine-side failure).",
|
|
1607
|
+
"enum": [
|
|
1608
|
+
"CapabilityMismatch",
|
|
1609
|
+
"Offline",
|
|
1610
|
+
"AuthError",
|
|
1611
|
+
"RateLimited",
|
|
1612
|
+
"Timeout",
|
|
1613
|
+
"Unavailable",
|
|
1614
|
+
"Internal"
|
|
1615
|
+
]
|
|
1616
|
+
},
|
|
1617
|
+
"message": {
|
|
1618
|
+
"description": "Human-readable error message suitable for logs and developer diagnostics.",
|
|
1619
|
+
"type": "string",
|
|
1620
|
+
"minLength": 1
|
|
1621
|
+
},
|
|
1622
|
+
"providerId": {
|
|
1623
|
+
"description": "Identifier of the provider associated with the failure, if execution reached a provider.",
|
|
1624
|
+
"type": "string",
|
|
1625
|
+
"minLength": 1
|
|
1626
|
+
},
|
|
1627
|
+
"retryable": {
|
|
1628
|
+
"description": "Whether retrying the same request may succeed.",
|
|
1629
|
+
"type": "boolean"
|
|
1630
|
+
},
|
|
1631
|
+
"retryAfterMs": {
|
|
1632
|
+
"description": "Optional suggested delay before retrying, in milliseconds.",
|
|
1633
|
+
"type": "integer",
|
|
1634
|
+
"minimum": 0
|
|
1635
|
+
},
|
|
1636
|
+
"details": {
|
|
1637
|
+
"description": "Optional structured diagnostic details. It must not contain raw secrets.",
|
|
1638
|
+
"type": "object",
|
|
1639
|
+
"additionalProperties": true
|
|
1640
|
+
}
|
|
1641
|
+
}
|
|
1642
|
+
}
|
|
1643
|
+
}
|
|
1644
|
+
},
|
|
1645
|
+
{
|
|
1646
|
+
"type": "object",
|
|
1647
|
+
"additionalProperties": true,
|
|
1648
|
+
"required": [
|
|
1649
|
+
"schemaVersion",
|
|
1650
|
+
"runId",
|
|
1651
|
+
"outcome",
|
|
1652
|
+
"partialText"
|
|
1653
|
+
],
|
|
1654
|
+
"properties": {
|
|
1655
|
+
"schemaVersion": {
|
|
1656
|
+
"description": "Contract schema version used to interpret this outcome payload.",
|
|
1657
|
+
"const": "1.0"
|
|
1658
|
+
},
|
|
1659
|
+
"runId": {
|
|
1660
|
+
"description": "The stream run this outcome terminates, matching StreamRunHandle.runId and every StreamEvent.runId for the run.",
|
|
1661
|
+
"type": "string",
|
|
1662
|
+
"minLength": 1
|
|
1663
|
+
},
|
|
1664
|
+
"outcome": {
|
|
1665
|
+
"description": "The stream was cancelled. No further StreamEvent is delivered after this outcome, and no further fallback attempt is made, per the engine's cancellation guarantee.",
|
|
1666
|
+
"const": "cancelled"
|
|
1667
|
+
},
|
|
1668
|
+
"partialText": {
|
|
1669
|
+
"description": "Whatever cumulative text had already been delivered via content_delta/content_snapshot StreamEvents before the cancellation point. May be empty if cancellation occurred before any content was produced.",
|
|
1670
|
+
"type": "string"
|
|
1671
|
+
},
|
|
1672
|
+
"reason": {
|
|
1673
|
+
"description": "Optional human-readable reason the run was cancelled (e.g. caller-initiated abort). Not a machine-taxonomy field; use errorClass on the 'error' outcome branch for failure classification.",
|
|
1674
|
+
"type": "string"
|
|
1675
|
+
}
|
|
1676
|
+
}
|
|
1677
|
+
}
|
|
1678
|
+
]
|
|
1679
|
+
};
|