@arcforge/kernel 2.0.100

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 ADDED
@@ -0,0 +1,31 @@
1
+ {
2
+ "name": "@arcforge/kernel",
3
+ "version": "2.0.100",
4
+ "description": "The Axon kernel — ring 0. Owns resources and execution, enforces policy, and is the only constructor of the unprivileged capsule.",
5
+ "type": "module",
6
+ "private": false,
7
+ "main": "./src/index.ts",
8
+ "exports": {
9
+ ".": "./src/index.ts"
10
+ },
11
+ "files": [
12
+ "src"
13
+ ],
14
+ "scripts": {
15
+ "test": "bun test",
16
+ "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"
17
+ },
18
+ "dependencies": {
19
+ "@arcforge/cognet": "2.0.100",
20
+ "@arcforge/engines": "2.0.100",
21
+ "@arcforge/err": "2.0.100",
22
+ "@arcforge/session": "2.0.100",
23
+ "@arcforge/types": "2.0.100",
24
+ "@arclabs/cloud": "2.0.100",
25
+ "@axon/capsule": "2.0.100"
26
+ },
27
+ "devDependencies": {
28
+ "@types/bun": "latest",
29
+ "typescript": "^5"
30
+ }
31
+ }
package/src/capsule.ts ADDED
@@ -0,0 +1,241 @@
1
+ import { isAbsolute, resolve } from "node:path"
2
+ import { Capsule, CapsuleT } from "@axon/capsule"
3
+ import type { CapsulePartialConfig, CapsuleTool } from "@axon/capsule"
4
+ import { err } from "@arcforge/err"
5
+ import { CAPSULE_TRANSIENT_EVENTS } from "@arcforge/types"
6
+ import type { AxonBlueprint, AxonEventMap, CapsulePolicy } from "@arcforge/types"
7
+ import type { AxonHost } from "@arcforge/types"
8
+ import type { KernelBus } from "./contracts"
9
+ import type { AxonSessionT } from "@arcforge/session"
10
+ import { isLoadable, toScopeModule } from "./scope"
11
+
12
+ /**
13
+ * Project-scanned tools carry self-contained bundled source (produced at scan
14
+ * time, with the tool's own imports inlined). The capsule materializes that
15
+ * source inside the sandbox and imports it there, so NO tool file — and none of
16
+ * the project around it — is ever mounted into the box. This is what keeps the
17
+ * sandbox filesystem exactly what the fs policy declares and nothing more. A
18
+ * raw entryPath is a fallback only for programmatic blueprints that never went
19
+ * through scan/bundling.
20
+ *
21
+ * Membership is isLoadable()/toScopeModule() from ./scope — the same
22
+ * decision that produces the model's <scope> and the editor's ambient
23
+ * declarations. What the capsule can run, what the model is told it can
24
+ * call, and what an editor typechecks against are one list by construction.
25
+ */
26
+ function toCapsuleTools(blueprint: AxonBlueprint): CapsuleTool[] {
27
+ return blueprint.tools
28
+ .filter(isLoadable)
29
+ .map(tool => ({
30
+ namespace: tool.name,
31
+ scope: toScopeModule(tool),
32
+ // Bundled source is authoritative: the capsule materializes it inside
33
+ // the sandbox, so no tool file (and none of the project around it) is
34
+ // mounted into the box. entryPath is a fallback only for tools that
35
+ // were never bundled (programmatic blueprints); scanned tools always
36
+ // carry source now.
37
+ ...(tool.source ? { source: tool.source } : { path: tool.entryPath! }),
38
+ }))
39
+ }
40
+
41
+ /**
42
+ * The capsule's own defaults are deny-by-default — correct for a sandbox
43
+ * that must never silently grant an undeclared capability to arbitrary
44
+ * loaded code. Axon is a different trust boundary: it is wiring up a
45
+ * capsule for its OWN declared blueprint, not sandboxing foreign code, so
46
+ * its default posture is the opposite — allow everything the blueprint's
47
+ * own policy doesn't explicitly restrict. Every tool namespace actually
48
+ * installed in the capsule gets an allow rule unless the blueprint's policy
49
+ * says otherwise; the user's own policy always wins (spread last).
50
+ *
51
+ * Scoped to loadable tools for the same reason toCapsuleTools() is: a rule
52
+ * naming a namespace the capsule never installs grants nothing and only
53
+ * makes the policy surface read as larger than it is.
54
+ */
55
+ function defaultPolicy(blueprint: AxonBlueprint): CapsulePartialConfig["policy"] {
56
+ const tools: Record<string, true> = {}
57
+ for (const tool of blueprint.tools.filter(isLoadable)) tools[tool.name] = true
58
+
59
+ const userPolicy = blueprint.config.policy ?? {}
60
+
61
+ // The invariant: not setting a security policy means "I don't care" — the
62
+ // agent gets full access to the machine, no hassle, no dependencies. Setting
63
+ // ANY containment intent (fs/network/limits) opts into rootless confinement,
64
+ // which needs no privilege and just works. A user can always name isolation
65
+ // explicitly to force a tier (e.g. "hardened", or "none" despite having fs).
66
+ const wantsContainment =
67
+ userPolicy.fs !== undefined || userPolicy.network !== undefined || userPolicy.limits !== undefined
68
+ const isolation = userPolicy.isolation ?? (wantsContainment ? "auto" : "none")
69
+
70
+ return {
71
+ ...userPolicy,
72
+ isolation,
73
+ // fs paths are authored relative to the AGENT PROJECT, not the directory
74
+ // the user happened to launch from. `fs: { read: ["./workspace"] }` in
75
+ // agents/foo/axon.config.ts means agents/foo/workspace, wherever axon
76
+ // was run. Resolve against paths.root here, at the seam that knows it —
77
+ // the capsule only ever sees absolute paths.
78
+ ...(userPolicy.fs ? { fs: resolveFsPaths(userPolicy.fs, blueprint.paths.root) } : {}),
79
+ process: { spawn: true, run: true, ...userPolicy.process },
80
+ tools: { ...tools, ...userPolicy.tools },
81
+ }
82
+ }
83
+
84
+ /** Resolve an fs policy's relative paths against the agent project root. */
85
+ function resolveFsPaths(fs: NonNullable<CapsulePolicy["fs"]>, root: string): CapsulePolicy["fs"] {
86
+ const abs = (p: string) => (isAbsolute(p) ? p : resolve(root, p))
87
+ return {
88
+ ...(fs.read ? { read: fs.read.map(abs) } : {}),
89
+ ...(fs.write ? { write: fs.write.map(abs) } : {}),
90
+ }
91
+ }
92
+
93
+ type AxonCapsuleOpts = {
94
+ blueprint: AxonBlueprint
95
+ /** Host invocation directory; deliberately independent of the agent project root. */
96
+ cwd: string
97
+ bus: KernelBus
98
+ session: AxonSessionT
99
+ /** The active wake's correlation, or null outside one — capsule spans caused by a run() stamp its runId. */
100
+ run?: () => { runId: string } | null
101
+ boot: boolean
102
+ host?: AxonHost
103
+ }
104
+
105
+ /**
106
+ * Owns the current capsule instance — ring 3, the unprivileged userland the
107
+ * kernel spawns agent-emitted effects into. Single entry point: callers
108
+ * always go through `current`, never hold the handle directly, so a reload
109
+ * can swap the underlying process without anyone needing to know.
110
+ *
111
+ * Capsule events commit to the session's log (telemetry view) —
112
+ * untranslated, the capsule's own vocabulary, stamped with the active
113
+ * wake's runId so cmd/fn spans attribute to the run that caused them; the
114
+ * commit pipeline forwards to the bus after each append lands. The one
115
+ * exception is the byte streams (CAPSULE_TRANSIENT_EVENTS: cmd/proc
116
+ * stdout, console) — live wire material that never enters the log; a
117
+ * command's output already reaches the durable record folded into
118
+ * cognet:action:result. capsule:attach/detach — "is a capsule live
119
+ * right now" — is the runtime's own continuity fact, committed here at
120
+ * the lifecycle seams alongside boot/shutdown.
121
+ */
122
+ export async function AxonCapsule(opts: AxonCapsuleOpts) {
123
+ let blueprint = opts.blueprint
124
+ let current: CapsuleT | undefined
125
+ let currentId: string | undefined
126
+ // The agent's live working directory, as last observed inside the
127
+ // sandbox — distinct from opts.cwd (the fixed host invocation dir).
128
+ // Starts unset: the very first boot has no prior capsule to inherit
129
+ // from, so it correctly falls back to opts.cwd below.
130
+ let liveCwd: string | undefined
131
+
132
+ function config(): CapsulePartialConfig {
133
+ return {
134
+ name: blueprint.agent.name,
135
+ cwd: liveCwd ?? opts.cwd,
136
+ env: blueprint.env,
137
+ tools: toCapsuleTools(blueprint),
138
+ policy: defaultPolicy(blueprint),
139
+ ...(opts.host ? {
140
+ host: {
141
+ call: request => opts.host!.call({
142
+ callerSessionId: opts.session.id,
143
+ ...request,
144
+ }),
145
+ },
146
+ } : {}),
147
+ }
148
+ }
149
+
150
+ async function boot(): Promise<CapsuleT> {
151
+ const capsule = Capsule(config())
152
+ capsule.onAny((event) => {
153
+ const { type, ...data } = event
154
+ if (CAPSULE_TRANSIENT_EVENTS.has(type)) {
155
+ void opts.bus.forward(event)
156
+ return
157
+ }
158
+ void opts.session.commit(type, data as AxonEventMap[typeof type], opts.run?.() ?? undefined)
159
+ })
160
+ await capsule.boot()
161
+
162
+ currentId = crypto.randomUUID()
163
+ await opts.session.commit("capsule:attach", { capsuleId: currentId, cwd: liveCwd ?? opts.cwd })
164
+
165
+ return capsule
166
+ }
167
+
168
+ /**
169
+ * The declared contract (see scope/declarations.ts) is "cwd changes
170
+ * persist across blocks" — true within one capsule's lifetime, silently
171
+ * false across a reload unless the incoming capsule inherits where the
172
+ * outgoing one actually was. Best-effort: a query that fails (dead
173
+ * incarnation, mid-crash) falls back to the last known liveCwd, not a
174
+ * hard failure — reload must not abort because the outgoing capsule
175
+ * can't answer one last question.
176
+ */
177
+ async function captureLiveCwd(capsule: CapsuleT): Promise<void> {
178
+ try {
179
+ const result = await capsule.run("process.cwd()", { timeout: 5_000 })
180
+ if (typeof result === "string" && result.length > 0) liveCwd = result
181
+ } catch {
182
+ // Outgoing capsule couldn't answer — keep whatever liveCwd already holds.
183
+ }
184
+ }
185
+
186
+ /**
187
+ * Commit a detach for whatever capsule id is passed in — always the
188
+ * OUTGOING one, captured by the caller before boot() overwrites
189
+ * currentId with the new capsule's id. Never reads currentId itself:
190
+ * during reload() the new capsule is already live (and currentId
191
+ * already reassigned) by the time the old one's detach is recorded.
192
+ */
193
+ async function detach(capsuleId: string, reason: "shutdown" | "crash" | "reload"): Promise<void> {
194
+ await opts.session.commit("capsule:detach", { capsuleId, reason })
195
+ }
196
+
197
+ async function reload() {
198
+ const previous = current
199
+ const previousId = currentId
200
+ if (previous) await captureLiveCwd(previous)
201
+ current = await boot()
202
+ await previous?.shutdown()
203
+ if (previousId) await detach(previousId, "reload")
204
+ }
205
+
206
+ if (opts.boot) current = await boot()
207
+
208
+ return {
209
+ get current(): CapsuleT {
210
+ if (!current) throw err("CAPSULE_ACCESSED_BEFORE_BOOT")
211
+ return current
212
+ },
213
+
214
+ async boot() {
215
+ current = await boot()
216
+ },
217
+
218
+ /**
219
+ * Receives the full re-normalized blueprint from the kernel.
220
+ * The capsule process is rebuilt against it — new one goes live
221
+ * before the old one drops.
222
+ */
223
+ async update(next: AxonBlueprint) {
224
+ blueprint = next
225
+ await reload()
226
+ },
227
+
228
+ reload,
229
+
230
+ async shutdown() {
231
+ await current?.shutdown()
232
+ current = undefined
233
+ if (currentId) {
234
+ await detach(currentId, "shutdown")
235
+ currentId = undefined
236
+ }
237
+ },
238
+ }
239
+ }
240
+
241
+ export type AxonCapsuleT = Awaited<ReturnType<typeof AxonCapsule>>
@@ -0,0 +1,33 @@
1
+ import type { AxonBlueprint, CognetSchedule, CognetWake, KernelAbi } from "@arcforge/types"
2
+
3
+ /**
4
+ * What ring 0 requires of its injected collaborators — declared structurally,
5
+ * not imported.
6
+ *
7
+ * The kernel is constructed by a composition root it must never depend on:
8
+ * @axon/core builds the bus and loads the cognet artifact, then hands both in.
9
+ * Importing their implementation types would invert the rings and make a
10
+ * published kernel depend on a private package.
11
+ *
12
+ * These are narrow on purpose. Each lists only what the kernel actually
13
+ * touches, so the surface a future host has to satisfy is small and honest.
14
+ */
15
+
16
+ /** Announce a committed event. The kernel forwards capsule and wake activity through this. */
17
+ export type KernelBus = {
18
+ forward(event: { type: string }): Promise<void>
19
+ onAny(handler: (event: string, payload: unknown) => void): () => void
20
+ }
21
+
22
+ /**
23
+ * The loaded brain. The kernel exec's it once, wakes it, and unloads it — it
24
+ * never learns how the artifact was resolved or what the cognition does.
25
+ */
26
+ export type KernelCognet = {
27
+ readonly name: string
28
+ readonly mode: CognetSchedule
29
+ load(abi: KernelAbi): Promise<void>
30
+ wake(wake: CognetWake): Promise<void>
31
+ update(blueprint: AxonBlueprint): Promise<void> | void
32
+ unload(): Promise<void> | void
33
+ }
package/src/engine.ts ADDED
@@ -0,0 +1,337 @@
1
+ import { err } from "@arcforge/err"
2
+ import type {
3
+ AxonBlueprint,
4
+ AxonEngineDriver,
5
+ AxonEngineEvent,
6
+ AxonEngineRequest,
7
+ AxonEngineResponse,
8
+ EngineCloud,
9
+ } from "@arcforge/types"
10
+ import { asEngineFault, EngineFailure, resolveEngine } from "@arcforge/engines"
11
+ import { Air, type AirBlockEvent } from "@arcforge/cognet/air"
12
+ import type { AxonSessionT } from "@arcforge/session"
13
+
14
+ type EngineOpts = {
15
+ blueprint: AxonBlueprint
16
+ session: AxonSessionT
17
+ /** The runtime's cloud client — handed to drivers at create(); engines call what they need. */
18
+ cloud: EngineCloud
19
+ }
20
+
21
+ type EngineContext = {
22
+ runId: string
23
+ }
24
+
25
+ const MAX_ATTEMPTS = 3
26
+ const RETRY_DELAYS_MS = [100, 300] as const
27
+
28
+ /**
29
+ * Engine — the inference layer of the runtime. Drivers are raw token pipes;
30
+ * this manager owns AIR parsing, bounded pre-output retries, and the durable
31
+ * accounting span around every logical call.
32
+ *
33
+ * A retry is deliberately invisible to cognition only while an attempt has
34
+ * produced no raw delta. Once any text or thinking has crossed the boundary,
35
+ * retrying could duplicate semantic output, so that failure is terminal.
36
+ */
37
+ export function Engine(opts: EngineOpts) {
38
+ const air = Air()
39
+ let blueprint = opts.blueprint
40
+ let current = build(blueprint)
41
+
42
+ function build(blueprint: AxonBlueprint): { driver: AxonEngineDriver; name: string } | null {
43
+ if (!blueprint.config.engine) return null
44
+ const def = resolveEngine(blueprint.config.engine)
45
+ return { driver: def.create({ env: blueprint.env, cloud: opts.cloud }), name: def.name }
46
+ }
47
+
48
+ async function* stream(req: AxonEngineRequest, context: EngineContext): AsyncGenerator<AxonEngineEvent> {
49
+ const span = { ...context, spanId: Bun.randomUUIDv7() }
50
+ if (!current) {
51
+ const fault = {
52
+ code: "INVALID_REQUEST" as const,
53
+ message: "NO_ENGINE: blueprint.config.engine is not configured",
54
+ retryable: false,
55
+ provider: "unconfigured",
56
+ }
57
+ await opts.session.commit("kernel:engine:start", { provider: fault.provider }, span)
58
+ await opts.session.commit("kernel:engine:input", {
59
+ messages: req.messages,
60
+ bytes: new TextEncoder().encode(JSON.stringify(req.messages)).byteLength,
61
+ }, span)
62
+ await opts.session.commit("kernel:engine:failed", { attempts: 0, fault }, span)
63
+ throw err("ENGINE_MISSING")
64
+ }
65
+
66
+ const selected = current
67
+ const configuredEngine = blueprint.config.engine
68
+ const model = req.model ?? (configuredEngine && "model" in configuredEngine ? configuredEngine.model : undefined)
69
+ const correlation = model ? { provider: selected.name, model } : { provider: selected.name }
70
+
71
+ await opts.session.commit("kernel:engine:start", correlation, span)
72
+ await opts.session.commit("kernel:engine:input", {
73
+ messages: req.messages,
74
+ bytes: new TextEncoder().encode(JSON.stringify(req.messages)).byteLength,
75
+ }, span)
76
+
77
+ for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
78
+ const parser = air.parser()
79
+ let semanticOutputSeen = false
80
+ let doneSeen = false
81
+ const started = Date.now()
82
+ let firstTokenAt: number | undefined
83
+ // What the parser actually saw, streamed. Some drivers (Codex)
84
+ // additionally emit an authoritative text:final that silently
85
+ // overwrites the response text without ever re-crossing the
86
+ // parser (see Collect()) — if that final text disagrees with
87
+ // what was streamed, the parser's incompleteness judgment was
88
+ // made against data that was never the real, final output. On
89
+ // `done`, reconcile: re-parse the authoritative text fresh
90
+ // rather than trust a parser that only ever saw a divergent
91
+ // stream.
92
+ let streamedText = ""
93
+
94
+ try {
95
+ for await (const raw of selected.driver.stream(req)) {
96
+ if (raw.type !== "done") {
97
+ firstTokenAt ??= Date.now()
98
+ }
99
+ if (raw.type === "text:delta" && raw.content.trim()) semanticOutputSeen = true
100
+
101
+ switch (raw.type) {
102
+ case "text:delta":
103
+ // Track exactly what crossed as deltas so the
104
+ // `done` reconciliation can tell a missing tail
105
+ // (extend) from a full re-feed (which would
106
+ // double-fire every already-streamed block).
107
+ streamedText += raw.content
108
+ for (const block of parser.feed(raw.content)) {
109
+ const event = toBlockEvent(block)
110
+ if (event) yield event
111
+ }
112
+ break
113
+
114
+ case "thinking:delta":
115
+ // dropped at the boundary — thinking never crosses the wire
116
+ break
117
+
118
+ case "done": {
119
+ if (doneSeen) {
120
+ throw protocolFailure(selected.name, model, "driver emitted more than one done event")
121
+ }
122
+ doneSeen = true
123
+ if (!semanticOutputSeen && raw.response.text.trim().length === 0) {
124
+ throw new EngineFailure({
125
+ code: "EMPTY_RESPONSE",
126
+ message: `empty response from model \"${raw.response.meta.model}\"`,
127
+ retryable: true,
128
+ provider: selected.name,
129
+ model: raw.response.meta.model,
130
+ })
131
+ }
132
+ // Some drivers report an authoritative final text
133
+ // that carries more than what actually crossed as
134
+ // deltas (e.g. Codex's output_text.done can trail
135
+ // the last output_text.delta). Feed the missing
136
+ // suffix into the SAME parser before flush() — it
137
+ // already emitted blocks from streamedText, so
138
+ // this must extend, never restart, or already-
139
+ // committed blocks would double-fire. Only safe
140
+ // when response.text is a strict extension of
141
+ // what was streamed; a genuine mismatch (not just
142
+ // a missing tail) is left to fail honestly rather
143
+ // than risk reconciling against the wrong content.
144
+ if (extendsStreamedText(streamedText, raw.response.text)) {
145
+ const missing = raw.response.text.slice(streamedText.length)
146
+ if (missing.length > 0) {
147
+ for (const block of parser.feed(missing)) {
148
+ const event = toBlockEvent(block)
149
+ if (event) yield event
150
+ }
151
+ }
152
+ }
153
+ for (const block of parser.flush()) {
154
+ const event = toBlockEvent(block)
155
+ if (event) yield event
156
+ }
157
+
158
+ const meta = {
159
+ ...raw.response.meta,
160
+ durationMs: raw.response.meta.durationMs || Date.now() - started,
161
+ ...(raw.response.meta.firstTokenMs === undefined && firstTokenAt !== undefined
162
+ ? { firstTokenMs: firstTokenAt - started }
163
+ : {}),
164
+ }
165
+ const response = { ...raw.response, meta }
166
+ await opts.session.commit("kernel:engine:complete", {
167
+ attempts: attempt,
168
+ text: response.text,
169
+ ...(response.thinking ? { thinking: response.thinking } : {}),
170
+ stopReason: response.stopReason,
171
+ meta,
172
+ }, span)
173
+ yield { type: "engine:done", response }
174
+ return
175
+ }
176
+ }
177
+ }
178
+
179
+ if (!doneSeen) {
180
+ throw protocolFailure(selected.name, model, "driver stream ended without a done event")
181
+ }
182
+ } catch (error) {
183
+ // Cancellation is control flow, not an engine fault. Drivers
184
+ // vary in what they throw on abort (DOMException, plain Error,
185
+ // or a transport wrapper), so the request signal is the one
186
+ // authoritative source. Wake() records kernel:run:interrupted
187
+ // and closes the wire; emitting engine:failed here would turn
188
+ // an intentional Escape/Ctrl+C into AX-KERNEL-008.
189
+ if (req.signal?.aborted) throw abortError(req.signal)
190
+
191
+ const fault = asEngineFault(error, correlation)
192
+ const canRetry = fault.retryable && !semanticOutputSeen && !req.signal?.aborted && attempt < MAX_ATTEMPTS
193
+
194
+ if (canRetry) {
195
+ const suggestedDelay = fault.retryAfterMs ?? RETRY_DELAYS_MS[attempt - 1] ?? RETRY_DELAYS_MS.at(-1)!
196
+ const delayMs = Math.min(suggestedDelay, 5_000)
197
+ await opts.session.commit("kernel:engine:retry", {
198
+ attempt,
199
+ nextAttempt: attempt + 1,
200
+ delayMs,
201
+ fault,
202
+ }, span)
203
+ try {
204
+ await delay(delayMs, req.signal)
205
+ } catch (delayError) {
206
+ // Same rule as the outer catch above: an interrupt
207
+ // landing during retry backoff is cancellation, not
208
+ // an engine fault — the signal is authoritative, not
209
+ // whatever delay() happened to throw.
210
+ if (req.signal?.aborted) throw abortError(req.signal)
211
+
212
+ const abortFault = asEngineFault(delayError, correlation)
213
+ await opts.session.commit("kernel:engine:failed", { attempts: attempt, fault: abortFault }, span)
214
+ throw err("ENGINE_STREAM_FAILED", {
215
+ detail: abortFault.message,
216
+ context: { code: abortFault.code, provider: abortFault.provider, model: abortFault.model, retryable: abortFault.retryable, attempts: attempt },
217
+ cause: delayError,
218
+ })
219
+ }
220
+ continue
221
+ }
222
+
223
+ await opts.session.commit("kernel:engine:failed", { attempts: attempt, fault }, span)
224
+ if (fault.code === "AUTH_NOT_CONNECTED" && fault.provider === "codex") {
225
+ throw err("CODEX_NOT_CONNECTED", {
226
+ detail: fault.message,
227
+ context: { provider: fault.provider, model: fault.model, attempts: attempt },
228
+ cause: error,
229
+ })
230
+ }
231
+ throw err("ENGINE_STREAM_FAILED", {
232
+ detail: fault.message,
233
+ context: { code: fault.code, provider: fault.provider, model: fault.model, retryable: fault.retryable, attempts: attempt },
234
+ cause: error,
235
+ })
236
+ }
237
+ }
238
+ }
239
+
240
+ return {
241
+ get configured() {
242
+ return current !== null
243
+ },
244
+
245
+ stream: stream,
246
+
247
+ async request(req: AxonEngineRequest, context: EngineContext): Promise<AxonEngineResponse> {
248
+ for await (const event of stream(req, context)) {
249
+ if (event.type === "engine:done") return event.response
250
+ }
251
+ throw err("ENGINE_NO_DONE")
252
+ },
253
+
254
+ update(next: AxonBlueprint) {
255
+ const nextCurrent = build(next)
256
+ // Assign after build succeeds: a bad engine ref never corrupts
257
+ // either the known-good driver or its metadata source.
258
+ current = nextCurrent
259
+ blueprint = next
260
+ },
261
+ }
262
+ }
263
+
264
+ export type AxonEngineT = ReturnType<typeof Engine>
265
+
266
+ /** True when `final` is `streamed` plus a non-empty trailing suffix — never a divergence, only a possibly-truncated stream catching up to the provider's authoritative text. */
267
+ function extendsStreamedText(streamed: string, final: string): boolean {
268
+ return final.length > streamed.length && final.startsWith(streamed)
269
+ }
270
+
271
+ function protocolFailure(provider: string, model: string | undefined, message: string): EngineFailure {
272
+ return new EngineFailure({
273
+ code: "PROTOCOL",
274
+ message,
275
+ retryable: true,
276
+ provider,
277
+ ...(model ? { model } : {}),
278
+ })
279
+ }
280
+
281
+ function delay(ms: number, signal?: AbortSignal): Promise<void> {
282
+ if (signal?.aborted) return Promise.reject(abortError(signal))
283
+ return new Promise((resolve, reject) => {
284
+ const timer = setTimeout(done, ms)
285
+ function done() {
286
+ signal?.removeEventListener("abort", aborted)
287
+ resolve()
288
+ }
289
+ function aborted() {
290
+ clearTimeout(timer)
291
+ reject(abortError(signal))
292
+ }
293
+ signal?.addEventListener("abort", aborted, { once: true })
294
+ })
295
+ }
296
+
297
+ function abortError(signal?: AbortSignal): DOMException {
298
+ return new DOMException(signal?.reason ? String(signal.reason) : "engine request aborted", "AbortError")
299
+ }
300
+
301
+ function toBlockEvent(block: AirBlockEvent): AxonEngineEvent | null {
302
+ switch (block.type) {
303
+ case "text:delta":
304
+ return { type: "engine:text:delta", content: block.content }
305
+ case "thinking:delta":
306
+ return null // dropped — thinking never crosses the wire
307
+
308
+ case "text:done":
309
+ if (block.incomplete) return incomplete("text", block.content)
310
+ return { type: "engine:text", content: block.content }
311
+ case "thinking:done":
312
+ return null // dropped — thinking never crosses the wire
313
+ case "typescript:done":
314
+ if (block.incomplete) return incomplete("typescript", block.content)
315
+ return { type: "engine:typescript", id: Bun.randomUUIDv7(), content: block.content }
316
+
317
+ case "shell:done":
318
+ return {
319
+ type: "engine:output:error",
320
+ code: "UNSUPPORTED_BLOCK",
321
+ message: "shell blocks are not executable in this runtime",
322
+ excerpt: block.content.slice(0, 200),
323
+ }
324
+
325
+ case "done":
326
+ return { type: "engine:stop" }
327
+ }
328
+ }
329
+
330
+ function incomplete(tag: string, content: string): AxonEngineEvent {
331
+ return {
332
+ type: "engine:output:error",
333
+ code: "INCOMPLETE_BLOCK",
334
+ message: `stream ended inside an unclosed <${tag}> block`,
335
+ excerpt: content.slice(0, 200),
336
+ }
337
+ }
package/src/index.ts ADDED
@@ -0,0 +1,20 @@
1
+ // @arcforge/kernel — ring 0.
2
+ //
3
+ // Owns the machine's resources and the execution of everything an agent asks
4
+ // for. The ONLY constructor of the unprivileged capsule, and the one place
5
+ // policy is enforced. Knows nothing about cognition: it hands the cognet a
6
+ // syscall table (KernelAbi, in @arcforge/types) and never learns what the
7
+ // model sees or how the brain thinks.
8
+ //
9
+ // Its collaborators — the event bus and the loaded cognet — arrive through
10
+ // opts as structural contracts (./contracts), never as imports from the
11
+ // composition root that builds them. That is what keeps ring 0 free of any
12
+ // dependency on the layer above it.
13
+ export { Kernel, type AxonKernelT } from "./kernel"
14
+ export type { KernelBus, KernelCognet } from "./contracts"
15
+
16
+ // The capsule's executable surface, and its rendering as TypeScript
17
+ // declarations — the kernel reports executable reality, callers decide how it
18
+ // enters model context.
19
+ export { toScope, toScopeModule, isLoadable } from "./scope"
20
+ export { scopeToDts, scopeMemberCount } from "./scope-dts"