@arcforge/kernel 2.0.142 → 2.0.144
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/contracts.ts +8 -0
- package/src/engine.ts +12 -2
- package/src/kernel.ts +92 -6
- package/src/scheduler/scheduler.ts +76 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.144",
|
|
4
4
|
"description": "The Axon kernel — ring 0. Owns resources and execution, enforces policy, and is the only constructor of the unprivileged capsule.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"private": false,
|
|
@@ -15,13 +15,13 @@
|
|
|
15
15
|
"deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
|
|
16
16
|
},
|
|
17
17
|
"dependencies": {
|
|
18
|
-
"@arcforge/air": "2.0.
|
|
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.144",
|
|
19
|
+
"@arcforge/engines": "2.0.144",
|
|
20
|
+
"@arcforge/err": "2.0.144",
|
|
21
|
+
"@arcforge/session": "2.0.144",
|
|
22
|
+
"@arcforge/types": "2.0.144",
|
|
23
|
+
"@arclabs/cloud": "2.0.144",
|
|
24
|
+
"@axon/capsule": "2.0.144"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@types/bun": "latest",
|
package/src/contracts.ts
CHANGED
|
@@ -26,6 +26,14 @@ export type KernelBus = {
|
|
|
26
26
|
export type KernelCognet = {
|
|
27
27
|
readonly name: string
|
|
28
28
|
readonly mode: CognetSchedule
|
|
29
|
+
/**
|
|
30
|
+
* Which entry types wake this brain. Absent = everything.
|
|
31
|
+
*
|
|
32
|
+
* Read by the scheduler's stimulus trigger. A conversational cognet
|
|
33
|
+
* declares nothing and hears all of it; one attached to a firehose
|
|
34
|
+
* sensor names the few kinds worth a thought.
|
|
35
|
+
*/
|
|
36
|
+
readonly wakeOn?: readonly string[]
|
|
29
37
|
load(abi: KernelAbi): Promise<void>
|
|
30
38
|
wake(wake: CognetWake): Promise<void>
|
|
31
39
|
update(blueprint: AxonBlueprint): Promise<void> | void
|
package/src/engine.ts
CHANGED
|
@@ -184,8 +184,18 @@ export function Engine(opts: EngineOpts) {
|
|
|
184
184
|
|
|
185
185
|
try {
|
|
186
186
|
for await (const raw of selected.driver.stream(req)) {
|
|
187
|
-
if (raw.type !== "done") {
|
|
188
|
-
firstTokenAt
|
|
187
|
+
if (raw.type !== "done" && firstTokenAt === undefined) {
|
|
188
|
+
firstTokenAt = Date.now()
|
|
189
|
+
// Committed as it happens rather than folded into
|
|
190
|
+
// :complete's meta, so the latency/generation split is
|
|
191
|
+
// visible on a live bar and survives a call that never
|
|
192
|
+
// completes. Awaited like every other commit in this
|
|
193
|
+
// span — the writer serializes, and ordering before the
|
|
194
|
+
// first parsed block is what makes containment honest.
|
|
195
|
+
await opts.session.commit("kernel:engine:firstToken", {
|
|
196
|
+
attempt,
|
|
197
|
+
elapsedMs: firstTokenAt - started,
|
|
198
|
+
}, span)
|
|
189
199
|
}
|
|
190
200
|
if (raw.type === "text:delta" && raw.content.trim()) semanticOutputSeen = true
|
|
191
201
|
|
package/src/kernel.ts
CHANGED
|
@@ -85,6 +85,32 @@ function formatValue(value: unknown): string {
|
|
|
85
85
|
*/
|
|
86
86
|
export type RunOptions = { signal?: AbortSignal; origin?: CapsuleCommandOrigin }
|
|
87
87
|
|
|
88
|
+
/** Thrown by a script that was cancelled before it started — see runAndCommit. */
|
|
89
|
+
function interruptedError(signal: AbortSignal): DOMException {
|
|
90
|
+
return new DOMException(String(signal.reason ?? "user"), "AbortError")
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The result shape for a script the wake cancelled before it ran.
|
|
95
|
+
*
|
|
96
|
+
* A settled `AxonRunResult` rather than a rejection, because the batch's other
|
|
97
|
+
* blocks DID run and a caller reading `results[i]` must still get block i. The
|
|
98
|
+
* `interrupt` kind already exists on the ABI for exactly this outcome, so a
|
|
99
|
+
* consumer that handles a timed-out or interrupted block handles this with no
|
|
100
|
+
* new case.
|
|
101
|
+
*/
|
|
102
|
+
function interruptedResult(reason: unknown): AxonRunResult {
|
|
103
|
+
return {
|
|
104
|
+
ok: false,
|
|
105
|
+
stdout: [],
|
|
106
|
+
scope: EMPTY_CAPSULE_SCOPE,
|
|
107
|
+
error: {
|
|
108
|
+
kind: "interrupt",
|
|
109
|
+
message: reason instanceof Error ? reason.message : String(reason),
|
|
110
|
+
},
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
88
114
|
/**
|
|
89
115
|
* Run one block against the capsule and normalize the outcome — the ABI
|
|
90
116
|
* boundary this seam exists for. Exec() below (capsule's own contract)
|
|
@@ -208,10 +234,17 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
208
234
|
*
|
|
209
235
|
* Mutations commit through the kernel, never the cognet: same rule as
|
|
210
236
|
* run()'s action/result pair — the brain requests, the kernel records.
|
|
211
|
-
*
|
|
212
|
-
*
|
|
213
|
-
*
|
|
214
|
-
* down the runtime it
|
|
237
|
+
*
|
|
238
|
+
* Fire-and-forget, because the write already succeeded and resolved to the
|
|
239
|
+
* caller — there is no honest way to fail it after the fact, and telemetry
|
|
240
|
+
* must never take down the runtime it observes.
|
|
241
|
+
*
|
|
242
|
+
* But NOT silent. This is the audit record for "the agent rewrote its own
|
|
243
|
+
* long-term memory", which is exactly the fact you want when behaviour
|
|
244
|
+
* drifts weeks later; a bare catch would let the ledger disagree with the
|
|
245
|
+
* filesystem with nothing anywhere to say so. Routing the rejection
|
|
246
|
+
* through err() delivers it to the runtime's error sink — the record
|
|
247
|
+
* still shows something went wrong, without the append becoming fatal.
|
|
215
248
|
*/
|
|
216
249
|
const knowledge = Knowledge({
|
|
217
250
|
root: opts.blueprint.paths.root,
|
|
@@ -219,7 +252,13 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
219
252
|
onMutate: (event, name) => {
|
|
220
253
|
void session
|
|
221
254
|
.commit(`cognet:knowledge:${event}`, { name }, scheduler.current() ?? undefined)
|
|
222
|
-
.catch(() => {
|
|
255
|
+
.catch((cause) => {
|
|
256
|
+
err("KNOWLEDGE_RECORD_FAILED", {
|
|
257
|
+
detail: `knowledge ${event} of "${name}" succeeded but its record could not be committed`,
|
|
258
|
+
context: { event, name },
|
|
259
|
+
cause,
|
|
260
|
+
})
|
|
261
|
+
})
|
|
223
262
|
},
|
|
224
263
|
})
|
|
225
264
|
|
|
@@ -246,8 +285,50 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
246
285
|
* the two-verb rule — the cognet never calls session.commit itself; it
|
|
247
286
|
* just reads the returned result for its own control flow.
|
|
248
287
|
*/
|
|
288
|
+
/**
|
|
289
|
+
* A batch of blocks from one turn — concurrent, as it has always been.
|
|
290
|
+
*
|
|
291
|
+
* Concurrency is deliberate (see `run` on the capsule surface and zero's
|
|
292
|
+
* own comment): the kernel commits each action and its result in order
|
|
293
|
+
* regardless of the order the work finishes in, so running them together
|
|
294
|
+
* is safe and much faster than a queue.
|
|
295
|
+
*
|
|
296
|
+
* What changes under cancellation is only WHETHER a script starts. Each
|
|
297
|
+
* `runAndCommit` re-checks the signal, so a batch interrupted partway
|
|
298
|
+
* commits the blocks that had already begun and skips the rest, instead of
|
|
299
|
+
* executing all of them because they were all dispatched in one tick.
|
|
300
|
+
*
|
|
301
|
+
* `allSettled`, not `all`: a skipped script rejects, and one rejection must
|
|
302
|
+
* not discard the results of siblings that genuinely ran. The results keep
|
|
303
|
+
* their positions so a caller reading `results[i]` still gets block `i`.
|
|
304
|
+
*/
|
|
305
|
+
async function runBatch(code: string[], signal: AbortSignal): Promise<AxonRunResult[]> {
|
|
306
|
+
const settled = await Promise.allSettled(code.map(c => runAndCommit(c, { signal })))
|
|
307
|
+
return settled.map(outcome => outcome.status === "fulfilled"
|
|
308
|
+
? outcome.value
|
|
309
|
+
: interruptedResult(outcome.reason))
|
|
310
|
+
}
|
|
311
|
+
|
|
249
312
|
async function runAndCommit(code: string, runOpts?: { signal?: AbortSignal }): Promise<AxonRunResult> {
|
|
250
313
|
const run = scheduler.active() // throws SYSCALL_OUTSIDE_RUN if no wake is running
|
|
314
|
+
|
|
315
|
+
// A script that has not STARTED must not start once the wake is
|
|
316
|
+
// cancelled. This is the boundary the kernel actually controls: the
|
|
317
|
+
// capsule can kill a spawned process (procs.ts kills the tree on
|
|
318
|
+
// abort), but a tool already inside `await` is only cancellable if it
|
|
319
|
+
// threads the signal itself — which is not a contract we put on module
|
|
320
|
+
// authors. So the kernel stops the SEQUENCE instead.
|
|
321
|
+
//
|
|
322
|
+
// The case this exists for is a turn that emitted several blocks: they
|
|
323
|
+
// run as a batch (see `run` below), and without this check every
|
|
324
|
+
// remaining script still executed after the user pressed Escape. One
|
|
325
|
+
// long command was already killed; forty small writes were not.
|
|
326
|
+
//
|
|
327
|
+
// Checked here rather than in `run` so it covers both entry points,
|
|
328
|
+
// and BEFORE the action is committed — a script that never ran must
|
|
329
|
+
// not appear in the log as one that did.
|
|
330
|
+
if (runOpts?.signal?.aborted) throw interruptedError(runOpts.signal)
|
|
331
|
+
|
|
251
332
|
const id = Bun.randomUUIDv7()
|
|
252
333
|
await session.commitEntry("cognet:action:typescript", { id, content: code }, run)
|
|
253
334
|
// The entry id IS the capsule command id — one id for one execution,
|
|
@@ -407,7 +488,7 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
407
488
|
*/
|
|
408
489
|
run: ((code: string | string[]) => {
|
|
409
490
|
const { signal } = scheduler.active() // throws SYSCALL_OUTSIDE_RUN if no wake is running
|
|
410
|
-
if (Array.isArray(code)) return
|
|
491
|
+
if (Array.isArray(code)) return runBatch(code, signal)
|
|
411
492
|
return runAndCommit(code, { signal })
|
|
412
493
|
}) as KernelAbi["run"],
|
|
413
494
|
scope: () => capsule.current.scope,
|
|
@@ -621,6 +702,11 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
621
702
|
// stop claiming a brain that is gone, and a cognet whose unload
|
|
622
703
|
// failed is no more wakeable than one whose unload worked.
|
|
623
704
|
scheduler.detach()
|
|
705
|
+
// Drop the stimulus subscription too — detach() stops wakes, but
|
|
706
|
+
// the bus would otherwise hold this scheduler alive for the life
|
|
707
|
+
// of the process, and a host running several agents in sequence
|
|
708
|
+
// accumulates one dead listener per shutdown.
|
|
709
|
+
scheduler.dispose()
|
|
624
710
|
|
|
625
711
|
await capsule.shutdown()
|
|
626
712
|
if (failure) throw failure
|
|
@@ -169,11 +169,87 @@ export function Scheduler(opts: SchedulerOpts) {
|
|
|
169
169
|
const invocation = Invocation({ session: opts.session, reserve, release, runWake, interrupt })
|
|
170
170
|
const continuous = Continuous({ session: opts.session, reserve, release, runWake })
|
|
171
171
|
|
|
172
|
+
/**
|
|
173
|
+
* Wake an invocation cognet when the WORLD reaches it — the trigger that
|
|
174
|
+
* makes `mode: "invocation"` mean what its docstring says ("invoked once
|
|
175
|
+
* per admitted stimulus arrival") for a stimulus nobody called in.
|
|
176
|
+
*
|
|
177
|
+
* Without this the only path to a wake was kernel.stream()/request(), so
|
|
178
|
+
* a stimulus from a sense organ (a channel module, a sensor) queued and
|
|
179
|
+
* waited for a caller that never came: the message landed in the log and
|
|
180
|
+
* the agent never thought about it. A body has no caller by definition.
|
|
181
|
+
*
|
|
182
|
+
* Three gates, and each rejects for its own reason:
|
|
183
|
+
*
|
|
184
|
+
* MODE — continuous cognets own their clock (a cognet plugin drives
|
|
185
|
+
* kernel.wake()); waking them here would be the runtime asserting a
|
|
186
|
+
* rhythm it cannot know, which continuous.ts exists to prevent.
|
|
187
|
+
*
|
|
188
|
+
* PROVENANCE — a stimulus committed BY a wake is that wake's own echo.
|
|
189
|
+
* Waking on it is an infinite loop: the brain hears itself and thinks
|
|
190
|
+
* again, forever. runStorage answers this exactly — anything ingested
|
|
191
|
+
* inside a wake carries that wake's async context.
|
|
192
|
+
*
|
|
193
|
+
* MASK — `wakeOn`, when the cognet declares one. Absent means wake on
|
|
194
|
+
* everything, which is the right default for a conversational brain
|
|
195
|
+
* and wrong for one that only cares about a single channel.
|
|
196
|
+
*
|
|
197
|
+
* Contention is NOT a gate: an invocation cognet is one conversation, so
|
|
198
|
+
* a stimulus arriving mid-wake is dropped by reserve() throwing
|
|
199
|
+
* RUN_IN_PROGRESS. That is correct — it stays on the queue and the
|
|
200
|
+
* running wake's own drain picks it up.
|
|
201
|
+
*/
|
|
202
|
+
function onStimulus(entry: AxonStimulusEntry): void {
|
|
203
|
+
if (!cognet || cognet.mode.kind !== "invocation") return
|
|
204
|
+
|
|
205
|
+
// The brain's own echo — never wake on it.
|
|
206
|
+
if (runStorage.getStore()) return
|
|
207
|
+
|
|
208
|
+
const mask = cognet.wakeOn
|
|
209
|
+
if (mask && !mask.includes(entry.type)) return
|
|
210
|
+
|
|
211
|
+
let wire: ReturnType<typeof invocation.stream>
|
|
212
|
+
try {
|
|
213
|
+
wire = invocation.stream()
|
|
214
|
+
} catch {
|
|
215
|
+
// RUN_IN_PROGRESS: a wake is already running and will drain this
|
|
216
|
+
// stimulus itself. Nothing is lost, so nothing to report.
|
|
217
|
+
return
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
// The wire MUST be consumed to completion or its reservation leaks
|
|
221
|
+
// (runWake's finally lives inside the generator). Detached because
|
|
222
|
+
// no caller is waiting — a sensation is not a question. Entries
|
|
223
|
+
// commit as they are produced.
|
|
224
|
+
void (async () => {
|
|
225
|
+
for await (const _entry of wire.stream) {
|
|
226
|
+
// nothing to collect
|
|
227
|
+
}
|
|
228
|
+
})().catch(() => {
|
|
229
|
+
// Already durable as kernel:run:failed by the time it lands here.
|
|
230
|
+
})
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
// Stimuli reach the bus on every ingest (durable and transient alike —
|
|
234
|
+
// session.ts forwards both), so this is the arrival signal without
|
|
235
|
+
// threading a second callback through the session's queue. Subscribed
|
|
236
|
+
// for the scheduler's lifetime: onStimulus itself gates on whether a
|
|
237
|
+
// cognet is attached and what mode it is in.
|
|
238
|
+
const unsubscribe = opts.bus.onAny((event, payload) => {
|
|
239
|
+
if (!event.startsWith("cognet:stimulus:")) return
|
|
240
|
+
onStimulus(payload as AxonStimulusEntry)
|
|
241
|
+
})
|
|
242
|
+
|
|
172
243
|
return {
|
|
173
244
|
get loaded() {
|
|
174
245
|
return cognet !== null
|
|
175
246
|
},
|
|
176
247
|
|
|
248
|
+
/** Drop the bus subscription — run when the kernel shuts down. */
|
|
249
|
+
dispose() {
|
|
250
|
+
unsubscribe()
|
|
251
|
+
},
|
|
252
|
+
|
|
177
253
|
/** register the loaded cognet — the kernel runs load(abi) first */
|
|
178
254
|
attach(next: KernelCognet) {
|
|
179
255
|
cognet = next
|