@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 +8 -8
- package/src/kernel.ts +102 -1
- package/src/knowledge.ts +204 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
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.
|
|
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.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
|
|
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,
|
package/src/knowledge.ts
ADDED
|
@@ -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>
|