@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcforge/kernel",
3
- "version": "2.0.142",
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.142",
19
- "@arcforge/engines": "2.0.142",
20
- "@arcforge/err": "2.0.142",
21
- "@arcforge/session": "2.0.142",
22
- "@arcforge/types": "2.0.142",
23
- "@arclabs/cloud": "2.0.142",
24
- "@axon/capsule": "2.0.142"
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 ??= Date.now()
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
- * Fire-and-forget with a swallowed rejection for the same reason emit()
212
- * swallows: the write already succeeded and resolved to the caller, so a
213
- * failed telemetry append has nowhere to surface, and must never take
214
- * down the runtime it is observing.
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 Promise.all(code.map(c => runAndCommit(c, { signal })))
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