@arcforge/kernel 2.0.141 → 2.0.143

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.141",
3
+ "version": "2.0.143",
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.141",
19
- "@arcforge/engines": "2.0.141",
20
- "@arcforge/err": "2.0.141",
21
- "@arcforge/session": "2.0.141",
22
- "@arcforge/types": "2.0.141",
23
- "@arclabs/cloud": "2.0.141",
24
- "@axon/capsule": "2.0.141"
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"
25
25
  },
26
26
  "devDependencies": {
27
27
  "@types/bun": "latest",
package/src/kernel.ts CHANGED
@@ -9,6 +9,7 @@ import { AxonCapsule, type AxonCapsuleT } from "./capsule"
9
9
  import { Scheduler } from "./scheduler"
10
10
  import type { KernelCognet } from "./contracts"
11
11
  import { Store } from "./store"
12
+ import { Knowledge } from "./knowledge"
12
13
  import type { AxonHost } from "@arcforge/types"
13
14
 
14
15
  type KernelOpts = {
@@ -84,6 +85,32 @@ function formatValue(value: unknown): string {
84
85
  */
85
86
  export type RunOptions = { signal?: AbortSignal; origin?: CapsuleCommandOrigin }
86
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
+
87
114
  /**
88
115
  * Run one block against the capsule and normalize the outcome — the ABI
89
116
  * boundary this seam exists for. Exec() below (capsule's own contract)
@@ -195,6 +222,33 @@ export async function Kernel(opts: KernelOpts) {
195
222
  session: session,
196
223
  })
197
224
 
225
+ /**
226
+ * Long-term knowledge — the agent's own data/knowledge/ plus every
227
+ * module's, discovered by the build and carried on the blueprint.
228
+ *
229
+ * Entries rather than a directory to walk: a module's corpus stays in its
230
+ * own package, so the runtime is handed paths the same way it is handed
231
+ * resolved model weights. Writes still resolve against the AGENT root
232
+ * (paths.root, not paths.data — authored input, not runtime output), and
233
+ * module material is read-only.
234
+ *
235
+ * Mutations commit through the kernel, never the cognet: same rule as
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.
241
+ */
242
+ const knowledge = Knowledge({
243
+ root: opts.blueprint.paths.root,
244
+ entries: opts.blueprint.knowledge,
245
+ onMutate: (event, name) => {
246
+ void session
247
+ .commit(`cognet:knowledge:${event}`, { name }, scheduler.current() ?? undefined)
248
+ .catch(() => {})
249
+ },
250
+ })
251
+
198
252
  /**
199
253
  * One block or many (concurrent, Promise.all-shaped) — always resolves.
200
254
  *
@@ -218,8 +272,50 @@ export async function Kernel(opts: KernelOpts) {
218
272
  * the two-verb rule — the cognet never calls session.commit itself; it
219
273
  * just reads the returned result for its own control flow.
220
274
  */
275
+ /**
276
+ * A batch of blocks from one turn — concurrent, as it has always been.
277
+ *
278
+ * Concurrency is deliberate (see `run` on the capsule surface and zero's
279
+ * own comment): the kernel commits each action and its result in order
280
+ * regardless of the order the work finishes in, so running them together
281
+ * is safe and much faster than a queue.
282
+ *
283
+ * What changes under cancellation is only WHETHER a script starts. Each
284
+ * `runAndCommit` re-checks the signal, so a batch interrupted partway
285
+ * commits the blocks that had already begun and skips the rest, instead of
286
+ * executing all of them because they were all dispatched in one tick.
287
+ *
288
+ * `allSettled`, not `all`: a skipped script rejects, and one rejection must
289
+ * not discard the results of siblings that genuinely ran. The results keep
290
+ * their positions so a caller reading `results[i]` still gets block `i`.
291
+ */
292
+ async function runBatch(code: string[], signal: AbortSignal): Promise<AxonRunResult[]> {
293
+ const settled = await Promise.allSettled(code.map(c => runAndCommit(c, { signal })))
294
+ return settled.map(outcome => outcome.status === "fulfilled"
295
+ ? outcome.value
296
+ : interruptedResult(outcome.reason))
297
+ }
298
+
221
299
  async function runAndCommit(code: string, runOpts?: { signal?: AbortSignal }): Promise<AxonRunResult> {
222
300
  const run = scheduler.active() // throws SYSCALL_OUTSIDE_RUN if no wake is running
301
+
302
+ // A script that has not STARTED must not start once the wake is
303
+ // cancelled. This is the boundary the kernel actually controls: the
304
+ // capsule can kill a spawned process (procs.ts kills the tree on
305
+ // abort), but a tool already inside `await` is only cancellable if it
306
+ // threads the signal itself — which is not a contract we put on module
307
+ // authors. So the kernel stops the SEQUENCE instead.
308
+ //
309
+ // The case this exists for is a turn that emitted several blocks: they
310
+ // run as a batch (see `run` below), and without this check every
311
+ // remaining script still executed after the user pressed Escape. One
312
+ // long command was already killed; forty small writes were not.
313
+ //
314
+ // Checked here rather than in `run` so it covers both entry points,
315
+ // and BEFORE the action is committed — a script that never ran must
316
+ // not appear in the log as one that did.
317
+ if (runOpts?.signal?.aborted) throw interruptedError(runOpts.signal)
318
+
223
319
  const id = Bun.randomUUIDv7()
224
320
  await session.commitEntry("cognet:action:typescript", { id, content: code }, run)
225
321
  // The entry id IS the capsule command id — one id for one execution,
@@ -379,7 +475,7 @@ export async function Kernel(opts: KernelOpts) {
379
475
  */
380
476
  run: ((code: string | string[]) => {
381
477
  const { signal } = scheduler.active() // throws SYSCALL_OUTSIDE_RUN if no wake is running
382
- if (Array.isArray(code)) return Promise.all(code.map(c => runAndCommit(c, { signal })))
478
+ if (Array.isArray(code)) return runBatch(code, signal)
383
479
  return runAndCommit(code, { signal })
384
480
  }) as KernelAbi["run"],
385
481
  scope: () => capsule.current.scope,
@@ -425,6 +521,11 @@ export async function Kernel(opts: KernelOpts) {
425
521
  // access, one mediated door like stream/run (see Store())
426
522
  store: store,
427
523
 
524
+ // long-term knowledge — the durable, human-readable counterpart to
525
+ // store's private kv. Same mediation (a name in, the kernel owns the
526
+ // path), different doctrine: this is the record, not a cache.
527
+ knowledge: knowledge,
528
+
428
529
  // The brain's own rhythm. Called from a cognet plugin, never from the
429
530
  // body — see KernelAbi.wake for why the body must not drive this.
430
531
  // Deliberately NOT awaited into the wake: admission is the contract,
@@ -0,0 +1,204 @@
1
+ import { existsSync } from "node:fs"
2
+ import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises"
3
+ import path from "node:path"
4
+ import { err } from "@arcforge/err"
5
+ import type { AxonKnowledge, KernelKnowledge, KnowledgeEntry } from "@arcforge/types"
6
+
7
+ type KnowledgeOpts = {
8
+ /** The agent root — <root>/data/knowledge/ is the writable store. */
9
+ root: string
10
+ /**
11
+ * Every knowledge file this agent can reach, discovered at build time —
12
+ * its own plus each installed module's, already namespaced.
13
+ *
14
+ * Carried rather than walked because a module's corpus lives in its own
15
+ * package: enumerating one directory would have meant copying every
16
+ * module's material into the agent, which forks it on the first update
17
+ * and duplicates megabytes per agent.
18
+ */
19
+ entries: readonly AxonKnowledge[]
20
+ /** Committed by the kernel on every mutation; the cognet never writes its own record. */
21
+ onMutate?: (event: "write" | "remove", name: string) => void
22
+ }
23
+
24
+ /**
25
+ * The writable store's layout authority — the ONE place that knows an
26
+ * agent's own knowledge lives at <agent>/data/knowledge/.
27
+ *
28
+ * Only the agent's own material has a layout here. A module's files are
29
+ * addressed by the absolute path the build recorded, because they live
30
+ * wherever the package manager put them.
31
+ */
32
+ function storeRoot(root: string): string {
33
+ return path.join(root, "data", "knowledge")
34
+ }
35
+
36
+ /**
37
+ * Resolve a name to a path inside the agent's OWN store, refusing anything
38
+ * that leaves it.
39
+ *
40
+ * A name is an IDENTIFIER, not a path — "axon/terminal.md" is a name whose
41
+ * separators happen to nest. Traversal is refused rather than sanitised
42
+ * because a caller that wrote "../../.env" meant something, and quietly
43
+ * rewriting it to a different file is worse than failing.
44
+ *
45
+ * Enforced, not trusted: the cognet is not adversarial, but a boundary that
46
+ * only holds for well-behaved code is not a boundary.
47
+ */
48
+ function resolveOwn(root: string, name: string): string {
49
+ const store = storeRoot(root)
50
+ const target = path.resolve(store, name)
51
+ const contained = target === store || target.startsWith(store + path.sep)
52
+ if (!contained) {
53
+ throw err("KNOWLEDGE_ESCAPE", { detail: `knowledge name "${name}" resolves outside the store`, context: { name } })
54
+ }
55
+ return target
56
+ }
57
+
58
+ /**
59
+ * Pull a one-line summary out of a written entry's frontmatter.
60
+ *
61
+ * A near-duplicate of the build scanner's parse, and deliberately so: this
62
+ * one runs against content already in memory for a single file the agent
63
+ * just wrote, while the scanner reads 4KB heads off disk across a whole
64
+ * corpus. Sharing would mean the kernel importing the build, which inverts
65
+ * the dependency — ring 0 must not depend on the CLI that produced its
66
+ * blueprint. Both are ten lines and neither is load-bearing on the other:
67
+ * a drift costs one entry a description until the next scan corrects it.
68
+ */
69
+ function describe(content: string): string {
70
+ if (!content.startsWith("---")) return ""
71
+ const end = content.indexOf("\n---", 3)
72
+ if (end < 0) return ""
73
+
74
+ let title = ""
75
+ for (const line of content.slice(3, end).split("\n")) {
76
+ const match = /^\s*(description|title)\s*:\s*(.+?)\s*$/.exec(line)
77
+ if (!match) continue
78
+ const value = match[2]!.replace(/^["'](.*)["']$/, "$1")
79
+ if (match[1] === "description") return value
80
+ title ||= value
81
+ }
82
+ return title
83
+ }
84
+
85
+ /**
86
+ * Knowledge — the cognet's long-term store, mediated.
87
+ *
88
+ * A leaf that owns one concern completely: reading and writing knowledge by
89
+ * NAME. It holds no cognition — no ranking, no retrieval strategy, no notion
90
+ * of relevance. `match` filters on metadata the caller supplied; everything
91
+ * else a brain wants (full-text search, embeddings, a symbolic index) it
92
+ * builds itself, because choosing how a mind recalls is memory policy and the
93
+ * kernel is forbidden from holding one.
94
+ *
95
+ * READS span every source; WRITES only ever touch the agent's own store.
96
+ * A module's files live under node_modules and the next install would
97
+ * destroy anything written there — so a write addressed at module material
98
+ * fails loudly rather than succeeding and disappearing later.
99
+ *
100
+ * See KernelKnowledge in @arcforge/types for the full doctrine.
101
+ */
102
+ export function Knowledge(opts: KnowledgeOpts): KernelKnowledge {
103
+ /**
104
+ * Name → the build's record of it, plus anything written since.
105
+ *
106
+ * Live rather than frozen at construction because the catalogue is the
107
+ * read path's index: an agent that wrote a memory and could not list or
108
+ * read it back until the next scan would have a store that silently
109
+ * forgets, which is precisely the self-managed-memory case this exists
110
+ * for. Writes register here; removals drop out.
111
+ */
112
+ const byName = new Map(opts.entries.map(entry => [entry.name, entry]))
113
+
114
+ return {
115
+ async list(listOpts) {
116
+ // Ordered before filtering and before the cap, so `limit` yields a
117
+ // stable prefix of one total order rather than whichever order the
118
+ // scan happened to produce.
119
+ const entries: KnowledgeEntry[] = [...byName.values()]
120
+ .map(entry => ({ name: entry.name, description: entry.description, size: entry.size, path: entry.path }))
121
+ .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
122
+
123
+ const match = listOpts?.match?.toLowerCase()
124
+ const filtered = match
125
+ ? entries.filter(entry => entry.name.toLowerCase().includes(match) || entry.description.toLowerCase().includes(match))
126
+ : entries
127
+
128
+ return listOpts?.limit === undefined ? filtered : filtered.slice(0, listOpts.limit)
129
+ },
130
+
131
+ async read(name) {
132
+ // The catalogue is the index: a name it knows resolves to the path
133
+ // the build recorded, wherever that package lives. A name it does
134
+ // not know may still be something the agent wrote since the scan,
135
+ // so its own store is checked before giving up.
136
+ const known = byName.get(name)
137
+ const file = known ? known.path : resolveOwn(opts.root, name)
138
+
139
+ if (!existsSync(file)) {
140
+ throw err("KNOWLEDGE_NOT_FOUND", { detail: `no knowledge entry named "${name}"`, context: { name } })
141
+ }
142
+ return readFile(file, "utf-8")
143
+ },
144
+
145
+ async write(name, content) {
146
+ const known = byName.get(name)
147
+ if (known?.origin === "module") {
148
+ throw err("KNOWLEDGE_READONLY", {
149
+ detail: `"${name}" belongs to module ${known.module} and cannot be written`,
150
+ context: { name, module: known.module ?? "" },
151
+ })
152
+ }
153
+
154
+ const file = resolveOwn(opts.root, name)
155
+ await mkdir(path.dirname(file), { recursive: true })
156
+
157
+ // Atomic, like store.set() — but for a different reason. The kv is
158
+ // a cache and a torn write there costs a rebuild; knowledge is the
159
+ // record, so a half-written entry is real loss. temp + rename means
160
+ // a kill mid-write leaves the previous content intact.
161
+ const tmp = `${file}.${crypto.randomUUID().slice(0, 8)}.tmp`
162
+ await writeFile(tmp, content)
163
+ await rename(tmp, file)
164
+
165
+ // Register it so the catalogue reflects the write immediately. The
166
+ // build rescans on the next prepare and supersedes this, but a
167
+ // brain must be able to list and read back what it just wrote
168
+ // within the same session.
169
+ byName.set(name, {
170
+ name,
171
+ description: describe(content),
172
+ size: Buffer.byteLength(content),
173
+ path: file,
174
+ origin: "agent",
175
+ })
176
+
177
+ opts.onMutate?.("write", name)
178
+ },
179
+
180
+ async remove(name) {
181
+ const known = byName.get(name)
182
+ if (known?.origin === "module") {
183
+ throw err("KNOWLEDGE_READONLY", {
184
+ detail: `"${name}" belongs to module ${known.module} and cannot be removed`,
185
+ context: { name, module: known.module ?? "" },
186
+ })
187
+ }
188
+
189
+ const file = resolveOwn(opts.root, name)
190
+ // Idempotent: a brain pruning its own memory should not have to
191
+ // check first, and "already gone" is the outcome it wanted.
192
+ if (!existsSync(file)) {
193
+ byName.delete(name)
194
+ return
195
+ }
196
+ await unlink(file)
197
+ byName.delete(name)
198
+
199
+ opts.onMutate?.("remove", name)
200
+ },
201
+ }
202
+ }
203
+
204
+ export type KnowledgeT = ReturnType<typeof Knowledge>