@arcforge/kernel 2.0.140 → 2.0.142
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 +33 -0
- 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.142",
|
|
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.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"
|
|
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 = {
|
|
@@ -195,6 +196,33 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
195
196
|
session: session,
|
|
196
197
|
})
|
|
197
198
|
|
|
199
|
+
/**
|
|
200
|
+
* Long-term knowledge — the agent's own data/knowledge/ plus every
|
|
201
|
+
* module's, discovered by the build and carried on the blueprint.
|
|
202
|
+
*
|
|
203
|
+
* Entries rather than a directory to walk: a module's corpus stays in its
|
|
204
|
+
* own package, so the runtime is handed paths the same way it is handed
|
|
205
|
+
* resolved model weights. Writes still resolve against the AGENT root
|
|
206
|
+
* (paths.root, not paths.data — authored input, not runtime output), and
|
|
207
|
+
* module material is read-only.
|
|
208
|
+
*
|
|
209
|
+
* Mutations commit through the kernel, never the cognet: same rule as
|
|
210
|
+
* 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.
|
|
215
|
+
*/
|
|
216
|
+
const knowledge = Knowledge({
|
|
217
|
+
root: opts.blueprint.paths.root,
|
|
218
|
+
entries: opts.blueprint.knowledge,
|
|
219
|
+
onMutate: (event, name) => {
|
|
220
|
+
void session
|
|
221
|
+
.commit(`cognet:knowledge:${event}`, { name }, scheduler.current() ?? undefined)
|
|
222
|
+
.catch(() => {})
|
|
223
|
+
},
|
|
224
|
+
})
|
|
225
|
+
|
|
198
226
|
/**
|
|
199
227
|
* One block or many (concurrent, Promise.all-shaped) — always resolves.
|
|
200
228
|
*
|
|
@@ -425,6 +453,11 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
425
453
|
// access, one mediated door like stream/run (see Store())
|
|
426
454
|
store: store,
|
|
427
455
|
|
|
456
|
+
// long-term knowledge — the durable, human-readable counterpart to
|
|
457
|
+
// store's private kv. Same mediation (a name in, the kernel owns the
|
|
458
|
+
// path), different doctrine: this is the record, not a cache.
|
|
459
|
+
knowledge: knowledge,
|
|
460
|
+
|
|
428
461
|
// The brain's own rhythm. Called from a cognet plugin, never from the
|
|
429
462
|
// body — see KernelAbi.wake for why the body must not drive this.
|
|
430
463
|
// 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>
|