@arcforge/kernel 2.0.114 → 2.0.116
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 +201 -59
- package/src/index.ts +4 -4
- package/src/kernel.ts +193 -20
- package/src/scheduler/scheduler.ts +6 -2
- package/src/scope-dts.ts +0 -82
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.116",
|
|
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/
|
|
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.116",
|
|
19
|
+
"@arcforge/engines": "2.0.116",
|
|
20
|
+
"@arcforge/err": "2.0.116",
|
|
21
|
+
"@arcforge/session": "2.0.116",
|
|
22
|
+
"@arcforge/types": "2.0.116",
|
|
23
|
+
"@arclabs/cloud": "2.0.116",
|
|
24
|
+
"@axon/capsule": "2.0.116"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@types/bun": "latest",
|
package/src/engine.ts
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
import { err } from "@arcforge/err"
|
|
2
2
|
import type {
|
|
3
|
+
AirProtocolName,
|
|
3
4
|
AxonBlueprint,
|
|
5
|
+
AxonEngineCall,
|
|
4
6
|
AxonEngineDriver,
|
|
5
7
|
AxonEngineEvent,
|
|
6
|
-
AxonEngineRequest,
|
|
7
8
|
AxonEngineResponse,
|
|
8
9
|
EngineCloud,
|
|
9
10
|
} from "@arcforge/types"
|
|
10
11
|
import { asEngineFault, EngineFailure, resolveEngine } from "@arcforge/engines"
|
|
11
|
-
import { Air, type AirBlockEvent } from "@arcforge/
|
|
12
|
+
import { Air, type AirBlockEvent, type AirT, type OutputDiagnostic } from "@arcforge/air"
|
|
12
13
|
import type { AxonSessionT } from "@arcforge/session"
|
|
13
14
|
|
|
14
15
|
type EngineOpts = {
|
|
@@ -16,6 +17,8 @@ type EngineOpts = {
|
|
|
16
17
|
session: AxonSessionT
|
|
17
18
|
/** The runtime's cloud client — handed to drivers at create(); engines call what they need. */
|
|
18
19
|
cloud: EngineCloud
|
|
20
|
+
/** Commit a format violation the model must read and correct. */
|
|
21
|
+
fault(input: { code: string; message: string; excerpt?: string }): Promise<void>
|
|
19
22
|
}
|
|
20
23
|
|
|
21
24
|
type EngineContext = {
|
|
@@ -25,6 +28,25 @@ type EngineContext = {
|
|
|
25
28
|
const MAX_ATTEMPTS = 3
|
|
26
29
|
const RETRY_DELAYS_MS = [100, 300] as const
|
|
27
30
|
|
|
31
|
+
/**
|
|
32
|
+
* Attempts allowed after a response fails its declared output shape.
|
|
33
|
+
*
|
|
34
|
+
* Three model calls total is enough for a model to read a type error and fix
|
|
35
|
+
* it — a shape it cannot correct twice is usually one it cannot satisfy at
|
|
36
|
+
* all, and burning more calls on it just costs the caller money.
|
|
37
|
+
*/
|
|
38
|
+
const DEFAULT_OUTPUT_RETRIES = 2
|
|
39
|
+
|
|
40
|
+
/** Type errors as the model reads them — its own line numbers, its own code. */
|
|
41
|
+
function describeViolations(problems: readonly OutputDiagnostic[]): string {
|
|
42
|
+
const lines = problems.map(p => (p.line ? `line ${p.line}: ${p.message}` : p.message))
|
|
43
|
+
return [
|
|
44
|
+
"Your <script> does not produce the required `result` shape:",
|
|
45
|
+
...lines.map(l => ` ${l}`),
|
|
46
|
+
"Fix the script so `result` matches the declared type, then reply again.",
|
|
47
|
+
].join("\n")
|
|
48
|
+
}
|
|
49
|
+
|
|
28
50
|
/**
|
|
29
51
|
* Engine — the inference layer of the runtime. Drivers are raw token pipes;
|
|
30
52
|
* this manager owns AIR parsing, bounded pre-output retries, and the durable
|
|
@@ -35,7 +57,24 @@ const RETRY_DELAYS_MS = [100, 300] as const
|
|
|
35
57
|
* retrying could duplicate semantic output, so that failure is terminal.
|
|
36
58
|
*/
|
|
37
59
|
export function Engine(opts: EngineOpts) {
|
|
38
|
-
|
|
60
|
+
/**
|
|
61
|
+
* One Air per protocol, built on first use and reused.
|
|
62
|
+
*
|
|
63
|
+
* The grammar is resolved from the CALLER's protocol, not the runtime's:
|
|
64
|
+
* the cognet that rendered the context is the only thing that knows which
|
|
65
|
+
* contract the model was shown, and a parser accepting different tags
|
|
66
|
+
* than the contract declared would silently discard every block.
|
|
67
|
+
*/
|
|
68
|
+
const airs = new Map<AirProtocolName, AirT>()
|
|
69
|
+
const airFor = (protocol: AirProtocolName = "classic"): AirT => {
|
|
70
|
+
let air = airs.get(protocol)
|
|
71
|
+
if (!air) {
|
|
72
|
+
air = Air({ protocol })
|
|
73
|
+
airs.set(protocol, air)
|
|
74
|
+
}
|
|
75
|
+
return air
|
|
76
|
+
}
|
|
77
|
+
|
|
39
78
|
let blueprint = opts.blueprint
|
|
40
79
|
let current = build(blueprint)
|
|
41
80
|
|
|
@@ -45,7 +84,25 @@ export function Engine(opts: EngineOpts) {
|
|
|
45
84
|
return { driver: def.create({ env: blueprint.env, cloud: opts.cloud }), name: def.name }
|
|
46
85
|
}
|
|
47
86
|
|
|
48
|
-
|
|
87
|
+
/**
|
|
88
|
+
* One logical call, as AIR BLOCKS — the raw half.
|
|
89
|
+
*
|
|
90
|
+
* Owns everything about talking to a driver: transport retries,
|
|
91
|
+
* reconciling the authoritative final text against what actually
|
|
92
|
+
* streamed, and the durable accounting span. It knows the grammar only
|
|
93
|
+
* well enough to parse it, and nothing about what the blocks MEAN.
|
|
94
|
+
*
|
|
95
|
+
* The response half (running scripts, rendering templates, enforcing an
|
|
96
|
+
* output shape) wraps this — see stream() below.
|
|
97
|
+
*/
|
|
98
|
+
async function* blocks(
|
|
99
|
+
call: AxonEngineCall,
|
|
100
|
+
context: EngineContext,
|
|
101
|
+
): AsyncGenerator<AirBlockEvent, AxonEngineResponse> {
|
|
102
|
+
// Protocol is the manager's concern, never the driver's — drivers are
|
|
103
|
+
// token pipes and must not receive a field they'd have to ignore.
|
|
104
|
+
const { protocol, output: _output, retries: _retries, ...req } = call
|
|
105
|
+
const air = airFor(protocol)
|
|
49
106
|
const span = { ...context, spanId: Bun.randomUUIDv7() }
|
|
50
107
|
// The whole logical call, retries and AIR parsing included — distinct
|
|
51
108
|
// from meta.durationMs, which is one attempt's provider latency. A
|
|
@@ -109,10 +166,7 @@ export function Engine(opts: EngineOpts) {
|
|
|
109
166
|
// (extend) from a full re-feed (which would
|
|
110
167
|
// double-fire every already-streamed block).
|
|
111
168
|
streamedText += raw.content
|
|
112
|
-
|
|
113
|
-
const event = toBlockEvent(block)
|
|
114
|
-
if (event) yield event
|
|
115
|
-
}
|
|
169
|
+
yield* parser.feed(raw.content)
|
|
116
170
|
break
|
|
117
171
|
|
|
118
172
|
case "thinking:delta":
|
|
@@ -147,17 +201,9 @@ export function Engine(opts: EngineOpts) {
|
|
|
147
201
|
// than risk reconciling against the wrong content.
|
|
148
202
|
if (extendsStreamedText(streamedText, raw.response.text)) {
|
|
149
203
|
const missing = raw.response.text.slice(streamedText.length)
|
|
150
|
-
if (missing.length > 0)
|
|
151
|
-
for (const block of parser.feed(missing)) {
|
|
152
|
-
const event = toBlockEvent(block)
|
|
153
|
-
if (event) yield event
|
|
154
|
-
}
|
|
155
|
-
}
|
|
156
|
-
}
|
|
157
|
-
for (const block of parser.flush()) {
|
|
158
|
-
const event = toBlockEvent(block)
|
|
159
|
-
if (event) yield event
|
|
204
|
+
if (missing.length > 0) yield* parser.feed(missing)
|
|
160
205
|
}
|
|
206
|
+
yield* parser.flush()
|
|
161
207
|
|
|
162
208
|
const meta = {
|
|
163
209
|
...raw.response.meta,
|
|
@@ -175,8 +221,7 @@ export function Engine(opts: EngineOpts) {
|
|
|
175
221
|
meta,
|
|
176
222
|
durationMs: Date.now() - callStarted,
|
|
177
223
|
}, span)
|
|
178
|
-
|
|
179
|
-
return
|
|
224
|
+
return response
|
|
180
225
|
}
|
|
181
226
|
}
|
|
182
227
|
}
|
|
@@ -240,6 +285,138 @@ export function Engine(opts: EngineOpts) {
|
|
|
240
285
|
})
|
|
241
286
|
}
|
|
242
287
|
}
|
|
288
|
+
|
|
289
|
+
// The loop either returns on `done` or throws; exhausting every
|
|
290
|
+
// attempt without either is unreachable, but TS needs the return type
|
|
291
|
+
// satisfied on this path.
|
|
292
|
+
throw err("ENGINE_NO_DONE")
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* One logical call, as engine events.
|
|
297
|
+
*
|
|
298
|
+
* Maps parsed blocks onto the wire vocabulary and enforces a declared
|
|
299
|
+
* output shape, retrying a response that misses it. What it does NOT do
|
|
300
|
+
* is act: a script is reported, never run. Running code is an act, and
|
|
301
|
+
* acts belong to the brain — the kernel is the authority on HOW code
|
|
302
|
+
* runs (policy, capsule, commit), never on WHETHER this particular reply
|
|
303
|
+
* should have run any.
|
|
304
|
+
*
|
|
305
|
+
* That line is what keeps the service general. A cognet may call a model
|
|
306
|
+
* to classify a stimulus, rank an inference, or plan; if the kernel ran
|
|
307
|
+
* whatever came back, every one of those would touch the world unasked.
|
|
308
|
+
*/
|
|
309
|
+
async function* stream(call: AxonEngineCall, context: EngineContext): AsyncGenerator<AxonEngineEvent> {
|
|
310
|
+
const output = call.output
|
|
311
|
+
// Attempts AFTER the first, so `retries: 0` means one shot. Only a
|
|
312
|
+
// declared output contract can fail this way; without one there is
|
|
313
|
+
// nothing for a response to violate.
|
|
314
|
+
const budget = output ? (call.retries ?? DEFAULT_OUTPUT_RETRIES) : 0
|
|
315
|
+
let lastFault: string | undefined
|
|
316
|
+
|
|
317
|
+
yield { type: "engine:start" }
|
|
318
|
+
|
|
319
|
+
for (let attempt = 0; attempt <= budget; attempt++) {
|
|
320
|
+
const raw = blocks(call, context)
|
|
321
|
+
let violations: readonly OutputDiagnostic[] = []
|
|
322
|
+
let spoke = false
|
|
323
|
+
let acted = false
|
|
324
|
+
let yielded = false
|
|
325
|
+
let lang: "md" | "json" = "md"
|
|
326
|
+
let group: string | null = null
|
|
327
|
+
let pending: string | null = null
|
|
328
|
+
|
|
329
|
+
// Held rather than emitted: the parser follows every delta with a
|
|
330
|
+
// `done` carrying the whole block, so the LAST chunk is only
|
|
331
|
+
// knowable in arrears. Emitting eagerly would force an empty
|
|
332
|
+
// terminal chunk to close the group, turning a one-line reply
|
|
333
|
+
// into two entries on the record.
|
|
334
|
+
const events: AxonEngineEvent[] = []
|
|
335
|
+
|
|
336
|
+
let step = await raw.next()
|
|
337
|
+
while (!step.done) {
|
|
338
|
+
const block = step.value
|
|
339
|
+
switch (block.type) {
|
|
340
|
+
case "template:open":
|
|
341
|
+
lang = block.lang
|
|
342
|
+
break
|
|
343
|
+
|
|
344
|
+
case "template:delta":
|
|
345
|
+
if (pending !== null) {
|
|
346
|
+
group ??= crypto.randomUUID()
|
|
347
|
+
spoke = true
|
|
348
|
+
events.push({ type: "engine:text", content: pending, lang, chunk: { of: group } })
|
|
349
|
+
}
|
|
350
|
+
pending = block.content
|
|
351
|
+
break
|
|
352
|
+
|
|
353
|
+
case "template:done": {
|
|
354
|
+
if (block.incomplete) break
|
|
355
|
+
const last = pending ?? block.content
|
|
356
|
+
pending = null
|
|
357
|
+
if (!last) break
|
|
358
|
+
spoke = true
|
|
359
|
+
events.push(group
|
|
360
|
+
? { type: "engine:text", content: last, lang, chunk: { of: group, final: true } }
|
|
361
|
+
: { type: "engine:text", content: last, lang })
|
|
362
|
+
group = null
|
|
363
|
+
break
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
case "script:done": {
|
|
367
|
+
if (block.incomplete) break
|
|
368
|
+
// Checked BEFORE it is reported, so a script that
|
|
369
|
+
// cannot satisfy the contract is never handed to a
|
|
370
|
+
// cognet that would run it.
|
|
371
|
+
if (output) {
|
|
372
|
+
const problems = output.check(block.content)
|
|
373
|
+
if (problems.length > 0) {
|
|
374
|
+
violations = problems
|
|
375
|
+
break
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
acted = true
|
|
379
|
+
events.push({ type: "engine:script", id: crypto.randomUUID(), content: block.content })
|
|
380
|
+
break
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
case "done":
|
|
384
|
+
yielded = true
|
|
385
|
+
break
|
|
386
|
+
|
|
387
|
+
// Thinking never crosses the boundary.
|
|
388
|
+
case "thinking:delta":
|
|
389
|
+
case "thinking:done":
|
|
390
|
+
break
|
|
391
|
+
}
|
|
392
|
+
step = await raw.next()
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
if (violations.length === 0) {
|
|
396
|
+
for (const event of events) yield event
|
|
397
|
+
yield { type: "engine:done", response: step.value, spoke, acted, yielded }
|
|
398
|
+
return
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
// Nothing this attempt produced is emitted: a response that
|
|
402
|
+
// failed its contract is not a partial answer, it is a discarded
|
|
403
|
+
// one. The diagnostic is committed so the next attempt's context
|
|
404
|
+
// carries it, and the model rewrites against its own error.
|
|
405
|
+
lastFault = describeViolations(violations)
|
|
406
|
+
await opts.fault({ code: "OUTPUT_TYPE_ERROR", message: lastFault })
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
// Budget exhausted. Loud, never a degraded return: a caller that
|
|
410
|
+
// asked for a shape gets that shape or an error explaining why it
|
|
411
|
+
// could not be produced, never an unchecked value it would treat as
|
|
412
|
+
// validated.
|
|
413
|
+
yield {
|
|
414
|
+
type: "engine:failure",
|
|
415
|
+
error: err("OUTPUT_UNSATISFIED", {
|
|
416
|
+
detail: `the model could not produce the required output shape after ${budget + 1} attempts. `
|
|
417
|
+
+ `Last errors: ${lastFault ?? "(none recorded)"}`,
|
|
418
|
+
}),
|
|
419
|
+
}
|
|
243
420
|
}
|
|
244
421
|
|
|
245
422
|
return {
|
|
@@ -249,9 +426,10 @@ export function Engine(opts: EngineOpts) {
|
|
|
249
426
|
|
|
250
427
|
stream: stream,
|
|
251
428
|
|
|
252
|
-
async request(req:
|
|
429
|
+
async request(req: AxonEngineCall, context: EngineContext): Promise<AxonEngineResponse> {
|
|
253
430
|
for await (const event of stream(req, context)) {
|
|
254
431
|
if (event.type === "engine:done") return event.response
|
|
432
|
+
if (event.type === "engine:failure") throw event.error
|
|
255
433
|
}
|
|
256
434
|
throw err("ENGINE_NO_DONE")
|
|
257
435
|
},
|
|
@@ -268,6 +446,8 @@ export function Engine(opts: EngineOpts) {
|
|
|
268
446
|
|
|
269
447
|
export type AxonEngineT = ReturnType<typeof Engine>
|
|
270
448
|
|
|
449
|
+
|
|
450
|
+
|
|
271
451
|
/** 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. */
|
|
272
452
|
function extendsStreamedText(streamed: string, final: string): boolean {
|
|
273
453
|
return final.length > streamed.length && final.startsWith(streamed)
|
|
@@ -302,41 +482,3 @@ function delay(ms: number, signal?: AbortSignal): Promise<void> {
|
|
|
302
482
|
function abortError(signal?: AbortSignal): DOMException {
|
|
303
483
|
return new DOMException(signal?.reason ? String(signal.reason) : "engine request aborted", "AbortError")
|
|
304
484
|
}
|
|
305
|
-
|
|
306
|
-
function toBlockEvent(block: AirBlockEvent): AxonEngineEvent | null {
|
|
307
|
-
switch (block.type) {
|
|
308
|
-
case "text:delta":
|
|
309
|
-
return { type: "engine:text:delta", content: block.content }
|
|
310
|
-
case "thinking:delta":
|
|
311
|
-
return null // dropped — thinking never crosses the wire
|
|
312
|
-
|
|
313
|
-
case "text:done":
|
|
314
|
-
if (block.incomplete) return incomplete("text", block.content)
|
|
315
|
-
return { type: "engine:text", content: block.content }
|
|
316
|
-
case "thinking:done":
|
|
317
|
-
return null // dropped — thinking never crosses the wire
|
|
318
|
-
case "typescript:done":
|
|
319
|
-
if (block.incomplete) return incomplete("typescript", block.content)
|
|
320
|
-
return { type: "engine:typescript", id: Bun.randomUUIDv7(), content: block.content }
|
|
321
|
-
|
|
322
|
-
case "shell:done":
|
|
323
|
-
return {
|
|
324
|
-
type: "engine:output:error",
|
|
325
|
-
code: "UNSUPPORTED_BLOCK",
|
|
326
|
-
message: "shell blocks are not executable in this runtime",
|
|
327
|
-
excerpt: block.content.slice(0, 200),
|
|
328
|
-
}
|
|
329
|
-
|
|
330
|
-
case "done":
|
|
331
|
-
return { type: "engine:stop" }
|
|
332
|
-
}
|
|
333
|
-
}
|
|
334
|
-
|
|
335
|
-
function incomplete(tag: string, content: string): AxonEngineEvent {
|
|
336
|
-
return {
|
|
337
|
-
type: "engine:output:error",
|
|
338
|
-
code: "INCOMPLETE_BLOCK",
|
|
339
|
-
message: `stream ended inside an unclosed <${tag}> block`,
|
|
340
|
-
excerpt: content.slice(0, 200),
|
|
341
|
-
}
|
|
342
|
-
}
|
package/src/index.ts
CHANGED
|
@@ -13,8 +13,8 @@
|
|
|
13
13
|
export { Kernel, type AxonKernelT } from "./kernel"
|
|
14
14
|
export type { KernelBus, KernelCognet } from "./contracts"
|
|
15
15
|
|
|
16
|
-
// The capsule's executable surface
|
|
17
|
-
//
|
|
18
|
-
//
|
|
16
|
+
// The capsule's executable surface — the kernel reports executable reality,
|
|
17
|
+
// callers decide how it enters model context. How that surface is SPELLED
|
|
18
|
+
// (for a model, for tsc, as an output contract) belongs to @arcforge/air:
|
|
19
|
+
// the kernel owns what is callable, never how it is written down.
|
|
19
20
|
export { toScope, toScopeModule, isLoadable } from "./scope"
|
|
20
|
-
export { scopeToDts, scopeMemberCount } from "./scope-dts"
|
package/src/kernel.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { err } from "@arcforge/err"
|
|
2
|
-
import type { AxonBlueprint, AxonEntry, AxonEntryEvent, AxonEventMap, AxonRunResult, KernelAbi } from "@arcforge/types"
|
|
2
|
+
import type { AxonBlueprint, AxonEngineCall, AxonEngineEvent, AxonEntry, AxonEntryEvent, AxonEventMap, AxonRunResult, KernelAbi } from "@arcforge/types"
|
|
3
|
+
import { EMPTY_CAPSULE_SCOPE } from "@arcforge/types"
|
|
3
4
|
import type { AxonCloudClient } from "@arclabs/cloud"
|
|
4
5
|
import type { KernelBus } from "./contracts"
|
|
5
6
|
import { Engine } from "./engine"
|
|
@@ -50,6 +51,15 @@ type KernelOpts = {
|
|
|
50
51
|
type KernelInput = {
|
|
51
52
|
/** User message committed before the wake starts. */
|
|
52
53
|
content?: string | string[]
|
|
54
|
+
/**
|
|
55
|
+
* The structured shape this invocation must produce, already compiled by
|
|
56
|
+
* the caller (Axon's handle) so a bad type throws at the call site,
|
|
57
|
+
* before a wake is ever scheduled. Enforced by the engine; invisible to
|
|
58
|
+
* the cognet.
|
|
59
|
+
*/
|
|
60
|
+
output?: AxonEngineCall["output"]
|
|
61
|
+
/** Attempts after a response fails `output`. Ignored without one. */
|
|
62
|
+
retries?: number
|
|
53
63
|
}
|
|
54
64
|
|
|
55
65
|
const COGNET_EVENT_PREFIX = "cognet:"
|
|
@@ -86,14 +96,21 @@ async function runOne(capsule: AxonCapsuleT, code: string, opts?: { signal?: Abo
|
|
|
86
96
|
}
|
|
87
97
|
|
|
88
98
|
try {
|
|
89
|
-
|
|
90
|
-
|
|
99
|
+
// exec() rather than run(): the bindings come back alongside the
|
|
100
|
+
// value, so a cognet rendering a template from the same turn has
|
|
101
|
+
// something to interpolate against.
|
|
102
|
+
const { value, scope } = await capsule.current.exec(code, { onConsole, signal: opts?.signal, id: opts?.id })
|
|
103
|
+
return { ok: true, value, stdout, scope }
|
|
91
104
|
} catch (cause) {
|
|
92
105
|
const interrupted = opts?.signal?.aborted || (cause instanceof Error && cause.name === "AbortError")
|
|
93
106
|
const timedOut = cause instanceof Error && /timed out/.test(cause.message)
|
|
94
107
|
return {
|
|
95
108
|
ok: false,
|
|
96
109
|
stdout,
|
|
110
|
+
// A block that threw declared nothing usable — an empty scope is
|
|
111
|
+
// the honest value, and keeps callers from having to test for
|
|
112
|
+
// absence before every interpolation.
|
|
113
|
+
scope: EMPTY_CAPSULE_SCOPE,
|
|
97
114
|
error: {
|
|
98
115
|
kind: interrupted ? "interrupt" : timedOut ? "timeout" : "exception",
|
|
99
116
|
message: cause instanceof Error ? cause.message : String(cause),
|
|
@@ -156,6 +173,11 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
156
173
|
blueprint: opts.blueprint,
|
|
157
174
|
session,
|
|
158
175
|
cloud: opts.cloud,
|
|
176
|
+
// Reporting a format violation is the kernel's to commit — the
|
|
177
|
+
// engine describes the fault, the session records it. Injected
|
|
178
|
+
// rather than reached for, so the engine never learns what a session
|
|
179
|
+
// is. Hoisted declaration; live before the first call.
|
|
180
|
+
fault: input => recordFault(input, scheduler.active()).then(() => {}),
|
|
159
181
|
})
|
|
160
182
|
|
|
161
183
|
const store = Store({
|
|
@@ -196,6 +218,115 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
196
218
|
return result
|
|
197
219
|
}
|
|
198
220
|
|
|
221
|
+
/**
|
|
222
|
+
* The engine stream, with format violations recorded as system facts.
|
|
223
|
+
*
|
|
224
|
+
* A violation is the KERNEL's observation, not the cognet's speech: the
|
|
225
|
+
* AIR parser detected it, and a cognet paraphrasing it through output()
|
|
226
|
+
* would put runtime diagnostics in the agent's own voice — indistinguishable
|
|
227
|
+
* from something the agent said, both to a reader and to the next render.
|
|
228
|
+
* Committing it here as axon:system:message keeps the provenance honest,
|
|
229
|
+
* renders it dimmed rather than as a message, and still puts it in front of
|
|
230
|
+
* the model next tick (AIR renders <system>), which is what makes the
|
|
231
|
+
* self-correction loop work.
|
|
232
|
+
*
|
|
233
|
+
* The event still reaches the cognet — a loop may want to react — but it
|
|
234
|
+
* no longer has to launder it to make it visible.
|
|
235
|
+
*/
|
|
236
|
+
/**
|
|
237
|
+
* Record one format violation as a system fact.
|
|
238
|
+
*
|
|
239
|
+
* The single writer for both sources — the parser's own detections
|
|
240
|
+
* (an unclosed block) and a cognet's via fault() (an interpolation
|
|
241
|
+
* naming a binding that was never declared). One shape, one entry type,
|
|
242
|
+
* one thing for a host to recognise and hide.
|
|
243
|
+
*/
|
|
244
|
+
function recordFault(
|
|
245
|
+
fault: { code: string; message: string; excerpt?: string },
|
|
246
|
+
run: { runId: string } | undefined,
|
|
247
|
+
): Promise<unknown> {
|
|
248
|
+
return session.commitEntry("axon:system:message", {
|
|
249
|
+
type: "format-violation",
|
|
250
|
+
lang: "txt",
|
|
251
|
+
content: `${fault.code}: ${fault.message}`,
|
|
252
|
+
...(fault.excerpt ? { attributes: { excerpt: fault.excerpt } } : {}),
|
|
253
|
+
}, run)
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* The cognet's engine calls, with the invocation's output contract folded
|
|
258
|
+
* in.
|
|
259
|
+
*
|
|
260
|
+
* A caller that declared `output` on request() demanded a shape of THIS
|
|
261
|
+
* invocation, and the engine is what enforces it — so the contract is
|
|
262
|
+
* attached here rather than passed through cognition, which has no
|
|
263
|
+
* business knowing a shape was asked for. A cognet renders context and
|
|
264
|
+
* reads facts; it never carries the caller's requirements.
|
|
265
|
+
*/
|
|
266
|
+
async function* streamAndRecord(req: Parameters<typeof engine.stream>[0]): AsyncGenerator<AxonEngineEvent> {
|
|
267
|
+
const run = scheduler.active()
|
|
268
|
+
// The wake's cancellation is applied here, not passed in: an
|
|
269
|
+
// inference call is a mediated resource like the capsule, and a
|
|
270
|
+
// program that forgot to thread a signal made one unkillable.
|
|
271
|
+
const call = { ...req, ...activeContract, signal: run.signal }
|
|
272
|
+
|
|
273
|
+
for await (const event of engine.stream(call, run)) {
|
|
274
|
+
// A call that could not produce a usable response THROWS rather
|
|
275
|
+
// than arriving as an event a cognet might ignore. Yielding it
|
|
276
|
+
// and trusting every loop to check would make "the model never
|
|
277
|
+
// satisfied its contract" look identical to a completed wake —
|
|
278
|
+
// exactly the silent degradation the caller asked for a shape to
|
|
279
|
+
// avoid. The event is still yielded first so a consumer watching
|
|
280
|
+
// the stream sees the cause before the throw.
|
|
281
|
+
if (event.type === "engine:failure") {
|
|
282
|
+
yield event
|
|
283
|
+
throw event.error
|
|
284
|
+
}
|
|
285
|
+
yield event
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* The output contract for the wake currently running, if any.
|
|
291
|
+
*
|
|
292
|
+
* Wake-scoped, not kernel-scoped: it belongs to ONE invocation, and a
|
|
293
|
+
* value that outlived its wake would silently impose the previous
|
|
294
|
+
* caller's shape on the next request. Never reaches the ABI — the cognet
|
|
295
|
+
* has no idea a shape was demanded, which is the whole point.
|
|
296
|
+
*/
|
|
297
|
+
let activeContract: { output: NonNullable<KernelInput["output"]>; retries?: number } | null = null
|
|
298
|
+
|
|
299
|
+
/**
|
|
300
|
+
* One wake, with its output contract live for exactly the wire's
|
|
301
|
+
* lifetime.
|
|
302
|
+
*
|
|
303
|
+
* Both public verbs route through here — `request()` is `stream()`
|
|
304
|
+
* drained — so a contract can never be installed for one and skipped for
|
|
305
|
+
* the other. Wrapping the wire rather than setting the contract beside
|
|
306
|
+
* the call makes teardown total: a normal end, a throw, an interrupt, or
|
|
307
|
+
* a consumer that abandons the stream all run the generator's finally.
|
|
308
|
+
*/
|
|
309
|
+
function streamWithContract(input: KernelInput = {}) {
|
|
310
|
+
const run = scheduler.stream(input)
|
|
311
|
+
if (!input.output) return run
|
|
312
|
+
|
|
313
|
+
activeContract = {
|
|
314
|
+
output: input.output,
|
|
315
|
+
...(input.retries === undefined ? {} : { retries: input.retries }),
|
|
316
|
+
}
|
|
317
|
+
const inner = run.stream
|
|
318
|
+
return {
|
|
319
|
+
...run,
|
|
320
|
+
stream: (async function* () {
|
|
321
|
+
try {
|
|
322
|
+
yield* inner
|
|
323
|
+
} finally {
|
|
324
|
+
activeContract = null
|
|
325
|
+
}
|
|
326
|
+
})(),
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
|
|
199
330
|
// ── the ABI — the syscall table, bound once to the kernel's organs ──────
|
|
200
331
|
// Process-lifetime object: nothing on it carries per-wake state beyond
|
|
201
332
|
// what scheduler.active() resolves internally. This is the only thing
|
|
@@ -214,15 +345,30 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
214
345
|
},
|
|
215
346
|
|
|
216
347
|
// llm surface
|
|
217
|
-
stream: (req) =>
|
|
348
|
+
stream: (req) => streamAndRecord(req),
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* A format violation the COGNET detected while rendering the model's
|
|
352
|
+
* output — the kernel writes the system fact the cognet may not forge.
|
|
353
|
+
*/
|
|
354
|
+
fault: (input) => recordFault(input, scheduler.active()).then(() => {}),
|
|
218
355
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
356
|
+
/**
|
|
357
|
+
* capsule surface — self-committing (see runAndCommit above).
|
|
358
|
+
*
|
|
359
|
+
* The wake's cancellation is applied HERE, resolved from the run this
|
|
360
|
+
* syscall belongs to. A program never passes a signal and so can
|
|
361
|
+
* never omit one: a kill is authoritative, not something cognition
|
|
362
|
+
* opts into per call.
|
|
363
|
+
*/
|
|
364
|
+
run: ((code: string | string[]) => {
|
|
365
|
+
const { signal } = scheduler.active() // throws SYSCALL_OUTSIDE_RUN if no wake is running
|
|
366
|
+
if (Array.isArray(code)) return Promise.all(code.map(c => runAndCommit(c, { signal })))
|
|
367
|
+
return runAndCommit(code, { signal })
|
|
223
368
|
}) as KernelAbi["run"],
|
|
224
369
|
scope: () => capsule.current.scope,
|
|
225
370
|
|
|
371
|
+
|
|
226
372
|
// environment surface
|
|
227
373
|
base: opts.base,
|
|
228
374
|
|
|
@@ -310,15 +456,31 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
310
456
|
return scheduler.loaded
|
|
311
457
|
},
|
|
312
458
|
|
|
459
|
+
/**
|
|
460
|
+
* The capsule's executable scope, as the ABI reports it to a cognet.
|
|
461
|
+
*
|
|
462
|
+
* On the public surface because an output type is typechecked
|
|
463
|
+
* against it: a caller declaring `{ files: FileEntry[] }` may name a
|
|
464
|
+
* type the agent's own tools declare, and checking against anything
|
|
465
|
+
* other than the scope the MODEL is shown would accept types the
|
|
466
|
+
* model cannot see or reject ones it can.
|
|
467
|
+
*/
|
|
468
|
+
scope: () => capsule.current.scope,
|
|
469
|
+
|
|
313
470
|
/** Invoke on a stimulus arrival — invocation-mode cognets only; throws for continuous-mode. */
|
|
314
|
-
stream
|
|
315
|
-
return scheduler.stream(input)
|
|
316
|
-
},
|
|
471
|
+
stream: streamWithContract,
|
|
317
472
|
|
|
318
|
-
/**
|
|
473
|
+
/**
|
|
474
|
+
* Collect a full wake: every durable entry, in commit order.
|
|
475
|
+
*
|
|
476
|
+
* Goes through THIS handle's stream(), not the scheduler's, so an
|
|
477
|
+
* output contract is installed and torn down identically for both
|
|
478
|
+
* verbs — reaching past it would have made `request({ contract })`
|
|
479
|
+
* silently unenforced.
|
|
480
|
+
*/
|
|
319
481
|
async request(input: KernelInput = {}): Promise<{ ok: true; entries: AxonEntry[] }> {
|
|
320
482
|
const entries: AxonEntry[] = []
|
|
321
|
-
for await (const entry of
|
|
483
|
+
for await (const entry of streamWithContract(input).stream) {
|
|
322
484
|
entries.push(entry) // the wire carries entries, full stop — chunks included
|
|
323
485
|
}
|
|
324
486
|
return { ok: true, entries }
|
|
@@ -374,9 +536,20 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
374
536
|
* ends it after this resolves, so a failure here never skips flushing
|
|
375
537
|
* the log.
|
|
376
538
|
*
|
|
377
|
-
*
|
|
378
|
-
*
|
|
379
|
-
*
|
|
539
|
+
* THE BRAIN STOPS ITS OWN CLOCK, AND IT MUST STILL HAVE A KERNEL WHEN
|
|
540
|
+
* IT DOES. A continuous cognet is ticked by one of its own plugins
|
|
541
|
+
* driving kernel.wake() on an interval, and that interval is cleared
|
|
542
|
+
* by the plugin's own "shutdown" hook — which runs inside
|
|
543
|
+
* cognet.unload(). So unload() has to complete BEFORE anything the
|
|
544
|
+
* clock touches is torn down.
|
|
545
|
+
*
|
|
546
|
+
* This used to call scheduler.detach() first, on the reasoning that a
|
|
547
|
+
* brain being torn down can no longer wake. True, but it made wake()
|
|
548
|
+
* throw NO_COGNET_LOADED while a 30Hz interval was still firing into
|
|
549
|
+
* it — an unhandled rejection every ~33ms of teardown, from a plugin
|
|
550
|
+
* doing exactly what the authoring surface tells it to. Detaching
|
|
551
|
+
* after unload closes that window without weakening the guard: the
|
|
552
|
+
* clock is already stopped by then, so nothing is left to wake.
|
|
380
553
|
*/
|
|
381
554
|
async shutdown() {
|
|
382
555
|
scheduler.interrupt("shutdown")
|
|
@@ -387,10 +560,6 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
387
560
|
// rethrown after the box is definitely gone.
|
|
388
561
|
const unloadStarted = Date.now()
|
|
389
562
|
await session.commit("cognet:unload:start", { name: cognet.name })
|
|
390
|
-
// Before the unload, not after: whether it succeeds or throws, a
|
|
391
|
-
// brain being torn down can no longer wake, and readiness must
|
|
392
|
-
// stop claiming otherwise the moment that becomes true.
|
|
393
|
-
scheduler.detach()
|
|
394
563
|
let failure: ReturnType<typeof err> | null = null
|
|
395
564
|
try {
|
|
396
565
|
await cognet.unload()
|
|
@@ -399,6 +568,10 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
399
568
|
failure = err(cause)
|
|
400
569
|
await session.commit("cognet:unload:failed", { name: cognet.name, error: failure, durationMs: Date.now() - unloadStarted })
|
|
401
570
|
}
|
|
571
|
+
// After the unload, whether it succeeded or threw: readiness must
|
|
572
|
+
// stop claiming a brain that is gone, and a cognet whose unload
|
|
573
|
+
// failed is no more wakeable than one whose unload worked.
|
|
574
|
+
scheduler.detach()
|
|
402
575
|
|
|
403
576
|
await capsule.shutdown()
|
|
404
577
|
if (failure) throw failure
|
|
@@ -54,7 +54,7 @@ type InvokeInput = {
|
|
|
54
54
|
* AsyncLocalStorage binds it to the wake that started the work, so a syscall
|
|
55
55
|
* resolves correctly no matter how the awaits interleave.
|
|
56
56
|
*/
|
|
57
|
-
const runStorage = new AsyncLocalStorage<{ runId: string }>()
|
|
57
|
+
const runStorage = new AsyncLocalStorage<{ runId: string; signal: AbortSignal }>()
|
|
58
58
|
|
|
59
59
|
export function Scheduler(opts: SchedulerOpts) {
|
|
60
60
|
let cognet: KernelCognet | null = null
|
|
@@ -117,7 +117,11 @@ export function Scheduler(opts: SchedulerOpts) {
|
|
|
117
117
|
session: opts.session,
|
|
118
118
|
abort: reserved.abort,
|
|
119
119
|
})
|
|
120
|
-
|
|
120
|
+
// The signal rides WITH the run, so a mediated syscall resolves its
|
|
121
|
+
// own wake's cancellation rather than being handed one. A cognet
|
|
122
|
+
// that forgot to thread it used to make an operation unkillable;
|
|
123
|
+
// there is now nothing to forget.
|
|
124
|
+
const run = { runId: wake.runId, signal: reserved.abort.signal }
|
|
121
125
|
|
|
122
126
|
return (async function* () {
|
|
123
127
|
try {
|
package/src/scope-dts.ts
DELETED
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
import type { AxonScope } from "@arcforge/types"
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* scopeToDts — the agent's executable scope, spelled as TypeScript.
|
|
5
|
-
*
|
|
6
|
-
* The sibling spelling of renderScope(): same AxonScope in, same members
|
|
7
|
-
* out, different audience. renderScope() writes the <scope> block the model
|
|
8
|
-
* reads; this writes the ambient declarations an editor reads, so tool
|
|
9
|
-
* calls in the author's own src/tools, src/scripts, hooks, and routes
|
|
10
|
-
* typecheck against exactly what the capsule will provide.
|
|
11
|
-
*
|
|
12
|
-
* These globals are real in host-side code, not only inside the capsule:
|
|
13
|
-
* Inject().runtime() binds each one to the matching axon.tools.* proxy when
|
|
14
|
-
* the runtime comes up (see core/src/platform/inject.ts). That is what makes
|
|
15
|
-
* this file honest — for a while it declared globals a script could not
|
|
16
|
-
* actually call, so `kanban.list()` typechecked and then threw at runtime.
|
|
17
|
-
*
|
|
18
|
-
* These two must never disagree about WHAT is in scope. They cannot,
|
|
19
|
-
* because neither decides it — toScope() does, once, and both render its
|
|
20
|
-
* result. This file only chooses how to spell it for `tsc`:
|
|
21
|
-
*
|
|
22
|
-
* flat module → each member declared directly (a top-level global)
|
|
23
|
-
* namespaced module → `namespace <name> { ... }`
|
|
24
|
-
*
|
|
25
|
-
* No `declare` prefix on members: everything inside `declare global { }` is
|
|
26
|
-
* already ambient, and TS1038 rejects a nested `declare` there.
|
|
27
|
-
*/
|
|
28
|
-
export function scopeToDts(scope: AxonScope): string {
|
|
29
|
-
const modules = scope.modules.filter(module => module.members.length > 0)
|
|
30
|
-
|
|
31
|
-
const lines: string[] = [
|
|
32
|
-
"// tool-globals.d.ts — generated by axon prepare, do not edit",
|
|
33
|
-
"// Every tool the capsule can call, declared as it is callable.",
|
|
34
|
-
"// Mirrors the <scope> block the model receives — same source, same members.",
|
|
35
|
-
"",
|
|
36
|
-
"declare global {",
|
|
37
|
-
]
|
|
38
|
-
|
|
39
|
-
// Ambient types first and deduped by exact text: a member declaration
|
|
40
|
-
// referencing Promise<DeployStatus> is unresolvable without it, in an
|
|
41
|
-
// editor exactly as in the model's context.
|
|
42
|
-
for (const ambient of new Set(modules.flatMap(module => module.ambientTypes ?? []))) {
|
|
43
|
-
lines.push(indent(ambient), "")
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
for (const module of modules) {
|
|
47
|
-
if (module.description) lines.push(indent(jsdocBlock(module.description)))
|
|
48
|
-
|
|
49
|
-
if (module.flat) {
|
|
50
|
-
for (const member of module.members) {
|
|
51
|
-
if (member.jsdoc) lines.push(indent(jsdocBlock(member.jsdoc)))
|
|
52
|
-
lines.push(indent(member.declaration))
|
|
53
|
-
}
|
|
54
|
-
continue
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
const body: string[] = []
|
|
58
|
-
for (const member of module.members) {
|
|
59
|
-
if (member.jsdoc) body.push(jsdocBlock(member.jsdoc))
|
|
60
|
-
body.push(member.declaration)
|
|
61
|
-
}
|
|
62
|
-
lines.push(indent(`namespace ${module.name} {\n${indent(body.join("\n"))}\n}`))
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
lines.push("}", "", "export {}", "")
|
|
66
|
-
return lines.join("\n")
|
|
67
|
-
}
|
|
68
|
-
|
|
69
|
-
/** How many callable members this scope declares — the caller's "did anything land" signal. */
|
|
70
|
-
export function scopeMemberCount(scope: AxonScope): number {
|
|
71
|
-
return scope.modules.reduce((total, module) => total + module.members.length, 0)
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
function indent(text: string): string {
|
|
75
|
-
return text.split("\n").map(line => (line ? ` ${line}` : line)).join("\n")
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
function jsdocBlock(text: string): string {
|
|
79
|
-
const lines = text.split("\n")
|
|
80
|
-
if (lines.length === 1) return `/** ${text} */`
|
|
81
|
-
return `/**\n${lines.map(l => ` * ${l}`.trimEnd()).join("\n")}\n */`
|
|
82
|
-
}
|