@arcforge/kernel 2.0.150 → 2.0.152

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.
Files changed (2) hide show
  1. package/package.json +8 -8
  2. 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.150",
3
+ "version": "2.0.152",
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.150",
19
- "@arcforge/engines": "2.0.150",
20
- "@arcforge/err": "2.0.150",
21
- "@arcforge/session": "2.0.150",
22
- "@arcforge/types": "2.0.150",
23
- "@arclabs/cloud": "2.0.150",
24
- "@axon/capsule": "2.0.150"
18
+ "@arcforge/air": "2.0.152",
19
+ "@arcforge/engines": "2.0.152",
20
+ "@arcforge/err": "2.0.152",
21
+ "@arcforge/session": "2.0.152",
22
+ "@arcforge/types": "2.0.152",
23
+ "@arclabs/cloud": "2.0.152",
24
+ "@axon/capsule": "2.0.152"
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 err("ENGINE_STREAM_FAILED", {
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
- if (fault.code === "AUTH_NOT_CONNECTED" && fault.provider === "codex") {
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
- // Held rather than emitted: the parser follows every delta with a
795
- // `done` carrying the whole block, so the LAST chunk is only
796
- // knowable in arrears. Emitting eagerly would force an empty
797
- // terminal chunk to close the group, turning a one-line reply
798
- // into two entries on the record.
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
- for (const event of events) yield event
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",