@arcforge/kernel 2.0.150 → 2.0.151
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/package.json +8 -8
- package/src/engine.ts +175 -23
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.151",
|
|
4
4
|
"description": "The Axon kernel — ring 0. Owns resources and execution, enforces policy, and is the only constructor of the unprivileged capsule.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"private": false,
|
|
@@ -15,13 +15,13 @@
|
|
|
15
15
|
"deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
|
|
16
16
|
},
|
|
17
17
|
"dependencies": {
|
|
18
|
-
"@arcforge/air": "2.0.
|
|
19
|
-
"@arcforge/engines": "2.0.
|
|
20
|
-
"@arcforge/err": "2.0.
|
|
21
|
-
"@arcforge/session": "2.0.
|
|
22
|
-
"@arcforge/types": "2.0.
|
|
23
|
-
"@arclabs/cloud": "2.0.
|
|
24
|
-
"@axon/capsule": "2.0.
|
|
18
|
+
"@arcforge/air": "2.0.151",
|
|
19
|
+
"@arcforge/engines": "2.0.151",
|
|
20
|
+
"@arcforge/err": "2.0.151",
|
|
21
|
+
"@arcforge/session": "2.0.151",
|
|
22
|
+
"@arcforge/types": "2.0.151",
|
|
23
|
+
"@arclabs/cloud": "2.0.151",
|
|
24
|
+
"@axon/capsule": "2.0.151"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@types/bun": "latest",
|
package/src/engine.ts
CHANGED
|
@@ -5,10 +5,13 @@ import type {
|
|
|
5
5
|
AxonEngineCall,
|
|
6
6
|
AxonEngineDriver,
|
|
7
7
|
AxonEngineEvent,
|
|
8
|
+
AxonEngineFault,
|
|
9
|
+
AxonEngineFaultCode,
|
|
8
10
|
AxonEngineResponse,
|
|
9
11
|
EngineCloud,
|
|
10
12
|
} from "@arcforge/types"
|
|
11
13
|
import { asEngineFault, EngineFailure } from "@arcforge/engines"
|
|
14
|
+
import type { AxonErrorCode } from "@arcforge/err"
|
|
12
15
|
import type { EnginesT } from "@arcforge/engines/catalogue"
|
|
13
16
|
import { Air, type AirBlockEvent, type AirT } from "@arcforge/air"
|
|
14
17
|
import type { OutputDiagnostic } from "@arcforge/air/output"
|
|
@@ -671,28 +674,13 @@ export function Engine(opts: EngineOpts) {
|
|
|
671
674
|
|
|
672
675
|
const abortFault = asEngineFault(delayError, correlation)
|
|
673
676
|
await opts.session.commit("kernel:engine:failed", { attempts: attempt, fault: abortFault, durationMs: Date.now() - callStarted }, span)
|
|
674
|
-
throw
|
|
675
|
-
detail: abortFault.message,
|
|
676
|
-
context: { code: abortFault.code, provider: abortFault.provider, model: abortFault.model, retryable: abortFault.retryable, attempts: attempt },
|
|
677
|
-
cause: delayError,
|
|
678
|
-
})
|
|
677
|
+
throw engineError(abortFault, attempt, delayError)
|
|
679
678
|
}
|
|
680
679
|
continue
|
|
681
680
|
}
|
|
682
681
|
|
|
683
682
|
await opts.session.commit("kernel:engine:failed", { attempts: attempt, fault, durationMs: Date.now() - callStarted }, span)
|
|
684
|
-
|
|
685
|
-
throw err("CODEX_NOT_CONNECTED", {
|
|
686
|
-
detail: fault.message,
|
|
687
|
-
context: { provider: fault.provider, model: fault.model, attempts: attempt },
|
|
688
|
-
cause: error,
|
|
689
|
-
})
|
|
690
|
-
}
|
|
691
|
-
throw err("ENGINE_STREAM_FAILED", {
|
|
692
|
-
detail: fault.message,
|
|
693
|
-
context: { code: fault.code, provider: fault.provider, model: fault.model, retryable: fault.retryable, attempts: attempt },
|
|
694
|
-
cause: error,
|
|
695
|
-
})
|
|
683
|
+
throw engineError(fault, attempt, error)
|
|
696
684
|
}
|
|
697
685
|
}
|
|
698
686
|
|
|
@@ -791,13 +779,82 @@ export function Engine(opts: EngineOpts) {
|
|
|
791
779
|
let group: string | null = null
|
|
792
780
|
let pending: string | null = null
|
|
793
781
|
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
782
|
+
/**
|
|
783
|
+
* Text this attempt has ALREADY streamed to the caller.
|
|
784
|
+
*
|
|
785
|
+
* Emitted as it parses rather than accumulated — see `drain()`
|
|
786
|
+
* below for why that is safe, and what it fixes.
|
|
787
|
+
*/
|
|
788
|
+
let streamedOut = 0
|
|
789
|
+
|
|
790
|
+
/**
|
|
791
|
+
* Blocks produced by this attempt, in order.
|
|
792
|
+
*
|
|
793
|
+
* Still a list, because emission is not immediate for everything:
|
|
794
|
+
* a chunk is held exactly one step (the parser reports each block's
|
|
795
|
+
* `done` in arrears, so the LAST chunk is only knowable then —
|
|
796
|
+
* emitting eagerly would force an empty terminal chunk to close the
|
|
797
|
+
* group, turning a one-line reply into two entries on the record),
|
|
798
|
+
* and SCRIPTS are held until the reply is complete.
|
|
799
|
+
*
|
|
800
|
+
* Scripts wait because they are the only block a shape violation
|
|
801
|
+
* can reject (`output.check` runs on `script:done`), and a rejected
|
|
802
|
+
* attempt must reach the caller as nothing at all rather than as a
|
|
803
|
+
* partial answer it would act on.
|
|
804
|
+
*/
|
|
799
805
|
const events: AxonEngineEvent[] = []
|
|
800
806
|
|
|
807
|
+
/**
|
|
808
|
+
* Hand the caller every text block parsed so far that is now
|
|
809
|
+
* un-retryable, and report whether anything crossed.
|
|
810
|
+
*
|
|
811
|
+
* ── Why this can emit before the reply is complete ──────────────
|
|
812
|
+
*
|
|
813
|
+
* Holding EVERY event until the attempt finished is what made a
|
|
814
|
+
* streamed reply arrive as one burst: the model wrote for twenty
|
|
815
|
+
* seconds and the whole answer appeared at once, at a token rate
|
|
816
|
+
* far above what the provider could produce. The buffer existed so
|
|
817
|
+
* a shape violation could discard the attempt and retry having
|
|
818
|
+
* shown the user nothing — a real requirement, but a much narrower
|
|
819
|
+
* one than the implementation.
|
|
820
|
+
*
|
|
821
|
+
* Every way this attempt can retry was checked against what it
|
|
822
|
+
* reads:
|
|
823
|
+
*
|
|
824
|
+
* output.check violations `script:done` only — never text
|
|
825
|
+
* texts > 1 / scripts > 1 a SECOND block closing
|
|
826
|
+
* truncated / empty reply end of reply, and both require that
|
|
827
|
+
* nothing was spoken or acted
|
|
828
|
+
*
|
|
829
|
+
* So the FIRST text block is safe the moment it closes: no retry
|
|
830
|
+
* path can fire while `texts <= 1 && scripts === 0`, and the
|
|
831
|
+
* runtime already treats closed text as un-retryable output
|
|
832
|
+
* (`blocks()` sets `emitted` on any `:done` and refuses transport
|
|
833
|
+
* retries after it — see engine-retry.test.ts, "does not retry
|
|
834
|
+
* after semantic output has crossed the engine boundary"). This
|
|
835
|
+
* makes `stream()` obey the rule its own inner loop already
|
|
836
|
+
* follows, rather than inventing a weaker one.
|
|
837
|
+
*
|
|
838
|
+
* Scripts are never streamed here: they are exactly what a
|
|
839
|
+
* violation rejects, so they wait for the reply to be complete.
|
|
840
|
+
*/
|
|
841
|
+
function drain(): AxonEngineEvent[] {
|
|
842
|
+
// A second block means a shape retry is now possible, and the
|
|
843
|
+
// whole attempt may be discarded — stop streaming and let the
|
|
844
|
+
// post-loop checks decide. Anything already sent has crossed;
|
|
845
|
+
// that is what `spoke` reports to those checks.
|
|
846
|
+
if (texts > 1 || scripts > 0) return []
|
|
847
|
+
|
|
848
|
+
const ready: AxonEngineEvent[] = []
|
|
849
|
+
while (streamedOut < events.length) {
|
|
850
|
+
const event = events[streamedOut]!
|
|
851
|
+
if (event.type !== "engine:text") break
|
|
852
|
+
ready.push(event)
|
|
853
|
+
streamedOut++
|
|
854
|
+
}
|
|
855
|
+
return ready
|
|
856
|
+
}
|
|
857
|
+
|
|
801
858
|
let step = await raw.next()
|
|
802
859
|
while (!step.done) {
|
|
803
860
|
const block = step.value
|
|
@@ -873,6 +930,12 @@ export function Engine(opts: EngineOpts) {
|
|
|
873
930
|
case "thinking:done":
|
|
874
931
|
break
|
|
875
932
|
}
|
|
933
|
+
|
|
934
|
+
// Stream whatever is now safe to send. This is what makes a
|
|
935
|
+
// reply appear as the model writes it instead of all at once
|
|
936
|
+
// when it finishes.
|
|
937
|
+
for (const event of drain()) yield event
|
|
938
|
+
|
|
876
939
|
step = await raw.next()
|
|
877
940
|
}
|
|
878
941
|
|
|
@@ -889,6 +952,31 @@ export function Engine(opts: EngineOpts) {
|
|
|
889
952
|
// Reported as a violation rather than truncated: the extra blocks
|
|
890
953
|
// are work the model intended, and silently dropping them would
|
|
891
954
|
// leave it believing they ran.
|
|
955
|
+
// ── Retry paths, and what streaming means for them ─────────────
|
|
956
|
+
//
|
|
957
|
+
// A retry rewrites the attempt and tries again. That is only
|
|
958
|
+
// honest while the caller has been shown NOTHING: re-answering
|
|
959
|
+
// after a block already reached the session would leave the
|
|
960
|
+
// discarded text on screen with the replacement underneath it.
|
|
961
|
+
//
|
|
962
|
+
// `drain()` guarantees this cannot happen — it stops streaming the
|
|
963
|
+
// moment a second block closes, and every check below requires
|
|
964
|
+
// either a second block or a reply that spoke and acted nothing.
|
|
965
|
+
// The assertion states that invariant where it matters rather than
|
|
966
|
+
// trusting the reader to re-derive it, and fails loudly if a future
|
|
967
|
+
// change to `drain()` breaks it.
|
|
968
|
+
if (violations.length > 0 || texts > 1 || scripts > 1 || (!spoke && !acted)) {
|
|
969
|
+
if (streamedOut > 0) {
|
|
970
|
+
// Not an EngineFailure: no provider did anything wrong.
|
|
971
|
+
// This is an internal invariant of this loop, and it must
|
|
972
|
+
// be unmissable rather than degrade into a duplicated reply.
|
|
973
|
+
throw new Error(
|
|
974
|
+
`AXON_INTERNAL: retry reached after ${streamedOut} block(s) already streamed to the caller — `
|
|
975
|
+
+ "drain() emitted something a retry path can still discard",
|
|
976
|
+
)
|
|
977
|
+
}
|
|
978
|
+
}
|
|
979
|
+
|
|
892
980
|
if (violations.length === 0 && (texts > 1 || scripts > 1)) {
|
|
893
981
|
lastFault = describeTooManyBlocks(texts, scripts)
|
|
894
982
|
lastFailure = "shape"
|
|
@@ -958,7 +1046,10 @@ export function Engine(opts: EngineOpts) {
|
|
|
958
1046
|
}
|
|
959
1047
|
|
|
960
1048
|
if (violations.length === 0) {
|
|
961
|
-
|
|
1049
|
+
// Only what has NOT already crossed. Re-yielding the streamed
|
|
1050
|
+
// prefix would commit every chunk twice — the reply rendering
|
|
1051
|
+
// once as it streamed and again, whole, underneath it.
|
|
1052
|
+
for (const event of events.slice(streamedOut)) yield event
|
|
962
1053
|
yield { type: "engine:done", response: step.value, spoke, acted, yielded }
|
|
963
1054
|
return
|
|
964
1055
|
}
|
|
@@ -1038,6 +1129,67 @@ function extendsStreamedText(streamed: string, final: string): boolean {
|
|
|
1038
1129
|
return final.length > streamed.length && final.startsWith(streamed)
|
|
1039
1130
|
}
|
|
1040
1131
|
|
|
1132
|
+
/**
|
|
1133
|
+
* Which user-facing error a provider fault becomes.
|
|
1134
|
+
*
|
|
1135
|
+
* ── Why this table exists ───────────────────────────────────────────────────
|
|
1136
|
+
*
|
|
1137
|
+
* Drivers classify failures precisely (`AxonEngineFaultCode`) and write a
|
|
1138
|
+
* provider-specific sentence for each — "Codex: usage limit reached. Check your
|
|
1139
|
+
* ChatGPT subscription.", "OpenRouter: insufficient credits — top up at
|
|
1140
|
+
* openrouter.ai". All of that was being collapsed into one internal
|
|
1141
|
+
* `ENGINE_STREAM_FAILED`, so a spent subscription reached the user as
|
|
1142
|
+
* `AX-KERNEL-008` plus a stack trace through code they did not write.
|
|
1143
|
+
*
|
|
1144
|
+
* The split is one question: CAN THE USER FIX IT?
|
|
1145
|
+
*
|
|
1146
|
+
* Mapped codes are `expected` — headline, the driver's own sentence, and what
|
|
1147
|
+
* to do about it, with no frames. What is NOT in this table (EMPTY_RESPONSE,
|
|
1148
|
+
* PROTOCOL, UNKNOWN) is a model or driver misbehaving, which is ours to debug
|
|
1149
|
+
* and keeps the full report.
|
|
1150
|
+
*
|
|
1151
|
+
* A table rather than a chain of `if`s because this used to be exactly one
|
|
1152
|
+
* hardcoded special case (`AUTH_NOT_CONNECTED` + provider === "codex"), and
|
|
1153
|
+
* every provider that grew the same condition would have added another branch.
|
|
1154
|
+
* Adding a fault code to the union now produces an unmapped fault that falls
|
|
1155
|
+
* through to the honest generic error rather than a silently miscategorised
|
|
1156
|
+
* one.
|
|
1157
|
+
*/
|
|
1158
|
+
const FAULT_ERRORS: Partial<Record<AxonEngineFaultCode, AxonErrorCode>> = {
|
|
1159
|
+
AUTH_NOT_CONNECTED: "ENGINE_NOT_CONNECTED",
|
|
1160
|
+
AUTH: "ENGINE_AUTH_FAILED",
|
|
1161
|
+
RATE_LIMIT: "ENGINE_RATE_LIMITED",
|
|
1162
|
+
QUOTA: "ENGINE_QUOTA_EXHAUSTED",
|
|
1163
|
+
INVALID_REQUEST: "ENGINE_REQUEST_REJECTED",
|
|
1164
|
+
TRANSPORT: "ENGINE_UNREACHABLE",
|
|
1165
|
+
}
|
|
1166
|
+
|
|
1167
|
+
/**
|
|
1168
|
+
* Turn a provider fault into the error the user sees.
|
|
1169
|
+
*
|
|
1170
|
+
* The driver's own message is always carried as `detail` — it is the most
|
|
1171
|
+
* specific thing available and names the provider, the condition and usually
|
|
1172
|
+
* the fix. `context` keeps the full fault for anyone reading the session log,
|
|
1173
|
+
* whichever error was chosen.
|
|
1174
|
+
*/
|
|
1175
|
+
function engineError(fault: AxonEngineFault, attempts: number, cause: unknown): Error {
|
|
1176
|
+
const context = {
|
|
1177
|
+
code: fault.code,
|
|
1178
|
+
provider: fault.provider,
|
|
1179
|
+
...(fault.model !== undefined ? { model: fault.model } : {}),
|
|
1180
|
+
retryable: fault.retryable,
|
|
1181
|
+
attempts,
|
|
1182
|
+
...(fault.status !== undefined ? { status: fault.status } : {}),
|
|
1183
|
+
...(fault.retryAfterMs !== undefined ? { retryAfterMs: fault.retryAfterMs } : {}),
|
|
1184
|
+
}
|
|
1185
|
+
|
|
1186
|
+
return err(FAULT_ERRORS[fault.code] ?? "ENGINE_STREAM_FAILED", {
|
|
1187
|
+
detail: fault.message,
|
|
1188
|
+
context,
|
|
1189
|
+
cause,
|
|
1190
|
+
})
|
|
1191
|
+
}
|
|
1192
|
+
|
|
1041
1193
|
function protocolFailure(provider: string, model: string | undefined, message: string): EngineFailure {
|
|
1042
1194
|
return new EngineFailure({
|
|
1043
1195
|
code: "PROTOCOL",
|