@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcforge/kernel",
3
- "version": "2.0.114",
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/cognet": "2.0.114",
19
- "@arcforge/engines": "2.0.114",
20
- "@arcforge/err": "2.0.114",
21
- "@arcforge/session": "2.0.114",
22
- "@arcforge/types": "2.0.114",
23
- "@arclabs/cloud": "2.0.114",
24
- "@axon/capsule": "2.0.114"
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/cognet/air"
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
- const air = Air()
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
- async function* stream(req: AxonEngineRequest, context: EngineContext): AsyncGenerator<AxonEngineEvent> {
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
- for (const block of parser.feed(raw.content)) {
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
- yield { type: "engine:done", response }
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: AxonEngineRequest, context: EngineContext): Promise<AxonEngineResponse> {
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, and its rendering as TypeScript
17
- // declarations — the kernel reports executable reality, callers decide how it
18
- // enters model context.
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
- const value = await capsule.current.run(code, { onConsole, signal: opts?.signal, id: opts?.id })
90
- return { ok: true, value, stdout }
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) => engine.stream(req, scheduler.active()),
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
- // capsule surface — self-committing (see runAndCommit above)
220
- run: ((code: string | string[], runOpts?: { signal?: AbortSignal }) => {
221
- if (Array.isArray(code)) return Promise.all(code.map(c => runAndCommit(c, runOpts)))
222
- return runAndCommit(code, runOpts)
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(input: KernelInput = {}) {
315
- return scheduler.stream(input)
316
- },
471
+ stream: streamWithContract,
317
472
 
318
- /** Collect a full wake: every durable entry, in commit order. */
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 scheduler.stream(input).stream) {
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
- * No clock to stop: a continuous cognet is ticked by the body (a
378
- * plugin driving `axon.tick()`), which tears its own interval down on
379
- * `shutdown:before` — before this runs.
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
- const run = { runId: wake.runId }
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
- }