@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 +31 -0
- package/src/capsule.ts +241 -0
- package/src/contracts.ts +33 -0
- package/src/engine.ts +337 -0
- package/src/index.ts +20 -0
- package/src/kernel.ts +330 -0
- package/src/scheduler/continuous.ts +44 -0
- package/src/scheduler/index.ts +2 -0
- package/src/scheduler/invocation.ts +59 -0
- package/src/scheduler/scheduler.ts +153 -0
- package/src/scheduler/wake.ts +164 -0
- package/src/scope-dts.ts +76 -0
- package/src/scope.ts +53 -0
- package/src/store/index.ts +1 -0
- package/src/store/store.ts +54 -0
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>>
|
package/src/contracts.ts
ADDED
|
@@ -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"
|