@arcforge/kernel 2.0.143 → 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.143",
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.143",
19
- "@arcforge/engines": "2.0.143",
20
- "@arcforge/err": "2.0.143",
21
- "@arcforge/session": "2.0.143",
22
- "@arcforge/types": "2.0.143",
23
- "@arclabs/cloud": "2.0.143",
24
- "@axon/capsule": "2.0.143"
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
@@ -234,10 +234,17 @@ export async function Kernel(opts: KernelOpts) {
234
234
  *
235
235
  * Mutations commit through the kernel, never the cognet: same rule as
236
236
  * run()'s action/result pair — the brain requests, the kernel records.
237
- * Fire-and-forget with a swallowed rejection for the same reason emit()
238
- * swallows: the write already succeeded and resolved to the caller, so a
239
- * failed telemetry append has nowhere to surface, and must never take
240
- * 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.
241
248
  */
242
249
  const knowledge = Knowledge({
243
250
  root: opts.blueprint.paths.root,
@@ -245,7 +252,13 @@ export async function Kernel(opts: KernelOpts) {
245
252
  onMutate: (event, name) => {
246
253
  void session
247
254
  .commit(`cognet:knowledge:${event}`, { name }, scheduler.current() ?? undefined)
248
- .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
+ })
249
262
  },
250
263
  })
251
264
 
@@ -689,6 +702,11 @@ export async function Kernel(opts: KernelOpts) {
689
702
  // stop claiming a brain that is gone, and a cognet whose unload
690
703
  // failed is no more wakeable than one whose unload worked.
691
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()
692
710
 
693
711
  await capsule.shutdown()
694
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