@arcforge/kernel 2.0.163 → 2.0.164
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/README.md +31 -0
- package/package.json +28 -9
- package/src/kernel.ts +3 -2
- package/src/mediation.ts +103 -13
- package/src/scope.ts +6 -8
package/README.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# @arcforge/kernel
|
|
2
|
+
|
|
3
|
+
The kernel of the [Axon](https://axon.arclabs.it) agent runtime — ring 0.
|
|
4
|
+
|
|
5
|
+
An Axon agent runs as its own OS process, and everything it does happens inside that one
|
|
6
|
+
box. The kernel is the trusted core: it owns the machine-facing operations, enforces
|
|
7
|
+
policy, and is the only constructor of the unprivileged capsule that agent code runs in.
|
|
8
|
+
|
|
9
|
+
Policy is declared in two places — a profile sets the ceiling for a machine, an agent
|
|
10
|
+
narrows within it — and enforced by two layers: the kernel mediating every syscall, and
|
|
11
|
+
OS-level confinement (namespaces and cgroups) bounding the process itself.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @arcforge/kernel
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Most people never install this directly. It arrives as a dependency of the Axon
|
|
18
|
+
framework when you scaffold an agent with `axon init`.
|
|
19
|
+
|
|
20
|
+
## Documentation
|
|
21
|
+
|
|
22
|
+
Full documentation is at **[axon.arclabs.it/docs/v2](https://axon.arclabs.it/docs/v2)**.
|
|
23
|
+
|
|
24
|
+
- [Kernel & Policy](https://axon.arclabs.it/docs/v2/concepts/kernel-and-policy)
|
|
25
|
+
- [Policy](https://axon.arclabs.it/docs/v2/agent/policy)
|
|
26
|
+
- [The Agent's World](https://axon.arclabs.it/docs/v2/concepts/agents-world)
|
|
27
|
+
- [Escalations](https://axon.arclabs.it/docs/v2/tui/escalations)
|
|
28
|
+
|
|
29
|
+
## License
|
|
30
|
+
|
|
31
|
+
Proprietary. © ArcLabs
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.164",
|
|
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,16 +15,35 @@
|
|
|
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.164",
|
|
19
|
+
"@arcforge/engines": "2.0.164",
|
|
20
|
+
"@arcforge/err": "2.0.164",
|
|
21
|
+
"@arcforge/session": "2.0.164",
|
|
22
|
+
"@arcforge/types": "2.0.164",
|
|
23
|
+
"@arclabs/cloud": "2.0.164",
|
|
24
|
+
"@axon/capsule": "2.0.164"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@types/bun": "latest",
|
|
28
28
|
"typescript": "^5"
|
|
29
|
-
}
|
|
29
|
+
},
|
|
30
|
+
"homepage": "https://axon.arclabs.it/docs/v2/concepts/kernel-and-policy",
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "git+https://github.com/artificial-cognition-laboratories/axon.git",
|
|
34
|
+
"directory": "libs/axon/kernel"
|
|
35
|
+
},
|
|
36
|
+
"bugs": {
|
|
37
|
+
"url": "https://github.com/artificial-cognition-laboratories/axon/issues"
|
|
38
|
+
},
|
|
39
|
+
"keywords": [
|
|
40
|
+
"axon",
|
|
41
|
+
"ai",
|
|
42
|
+
"agent",
|
|
43
|
+
"agents",
|
|
44
|
+
"llm",
|
|
45
|
+
"ai-agent",
|
|
46
|
+
"agent-runtime",
|
|
47
|
+
"typescript"
|
|
48
|
+
]
|
|
30
49
|
}
|
package/src/kernel.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { err } from "@arcforge/err"
|
|
2
|
-
import type { AxonBlueprint, AxonDriver, AxonEngineCall, AxonEngineDriver, CapsulePolicy, AxonEngineEvent, AxonEntry, AxonEntryEvent, AxonEventMap, AxonRunResult, CapsuleCommandOrigin, EngineSession, KernelAbi, TransformOptions } from "@arcforge/types"
|
|
2
|
+
import type { AxonBlueprint, AxonDriver, AxonEngineCall, AxonEngineDriver, CapsulePolicy, ResolvedCapsulePolicy, AxonEngineEvent, AxonEntry, AxonEntryEvent, AxonEventMap, AxonRunResult, CapsuleCommandOrigin, EngineSession, KernelAbi, TransformOptions } from "@arcforge/types"
|
|
3
3
|
import { EMPTY_CAPSULE_SCOPE } from "@arcforge/types"
|
|
4
4
|
import type { AxonCloudClient } from "@arclabs/cloud"
|
|
5
5
|
import type { KernelBus } from "./contracts"
|
|
@@ -67,6 +67,7 @@ type KernelOpts = {
|
|
|
67
67
|
* deny — the honest state for a headless run.
|
|
68
68
|
*/
|
|
69
69
|
escalate?: AxonEscalate
|
|
70
|
+
|
|
70
71
|
/**
|
|
71
72
|
* Resolved inference roles, when the cognet declared any.
|
|
72
73
|
*
|
|
@@ -324,7 +325,7 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
324
325
|
// Resolved from the LIVE blueprint on every call, through the same
|
|
325
326
|
// function the capsule is configured with — one resolution, so a tool
|
|
326
327
|
// cannot be permitted in-process and denied in the box.
|
|
327
|
-
policy: () => defaultPolicy(blueprintNow()) as
|
|
328
|
+
policy: () => defaultPolicy(blueprintNow()) as ResolvedCapsulePolicy,
|
|
328
329
|
session,
|
|
329
330
|
...(opts.escalate ? { escalate: opts.escalate } : {}),
|
|
330
331
|
run: () => scheduler.current(),
|
package/src/mediation.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto"
|
|
2
|
-
import { evaluateRule } from "@arcforge/types"
|
|
3
|
-
import type { AxonEscalate,
|
|
2
|
+
import { decideShell, evaluateRule, isMemberBag, splitCommand } from "@arcforge/types"
|
|
3
|
+
import type { AxonEscalate, EffectiveRule, ResolvedCapsulePolicy, ShellDecision } from "@arcforge/types"
|
|
4
4
|
import type { AxonSessionT } from "@arcforge/session"
|
|
5
5
|
|
|
6
6
|
/**
|
|
@@ -26,7 +26,7 @@ import type { AxonSessionT } from "@arcforge/session"
|
|
|
26
26
|
*/
|
|
27
27
|
|
|
28
28
|
type MediationOpts = {
|
|
29
|
-
policy: () =>
|
|
29
|
+
policy: () => ResolvedCapsulePolicy
|
|
30
30
|
session: AxonSessionT
|
|
31
31
|
/** The platform's decider. Absent = nobody to ask, which means deny. */
|
|
32
32
|
escalate?: AxonEscalate
|
|
@@ -41,23 +41,62 @@ const POLICY_WILDCARD = "*"
|
|
|
41
41
|
|
|
42
42
|
export function Mediation(opts: MediationOpts) {
|
|
43
43
|
/**
|
|
44
|
-
* Resolve which rule governs a call.
|
|
44
|
+
* Resolve which rule governs a call, by walking its ADDRESS.
|
|
45
45
|
*
|
|
46
46
|
* `process.spawn`/`process.run` are the two built-in verbs, resolved by
|
|
47
|
-
* exact name. Everything else is a tool,
|
|
48
|
-
*
|
|
49
|
-
*
|
|
47
|
+
* exact name. Everything else is a tool, addressed exactly as the code
|
|
48
|
+
* addresses it — the policy map mirrors the agent's global scope
|
|
49
|
+
* one-for-one, so a rule and a call site are the same string.
|
|
50
|
+
*
|
|
51
|
+
* Most specific first:
|
|
52
|
+
* `fs.remove` → `tools["fs"]["remove"]` → `tools["fs"]` → `tools["*"]`
|
|
53
|
+
* `read` → `tools["read"]` → `tools["*"]`
|
|
54
|
+
*
|
|
55
|
+
* A bag entry (`fs: { read: true }`) can only carry rules one level
|
|
56
|
+
* deep, matching the scope: a global is a function or a bag of
|
|
57
|
+
* functions, never deeper.
|
|
50
58
|
*/
|
|
51
|
-
function ruleFor(fn: string
|
|
59
|
+
function ruleFor(fn: string): EffectiveRule | undefined {
|
|
52
60
|
const policy = opts.policy()
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
61
|
+
|
|
62
|
+
// `shell.spawn` is the one built-in verb still decided by a rule.
|
|
63
|
+
// `shell.run` is not here: execution is decided by decideShell(), which
|
|
64
|
+
// reasons about the PROGRAM rather than glob-matching a command string.
|
|
65
|
+
if (fn === "shell.spawn") {
|
|
66
|
+
const spawn = policy.shell?.spawn
|
|
67
|
+
if (spawn !== null && typeof spawn === "object" && "rule" in spawn) return spawn.rule
|
|
68
|
+
return spawn as EffectiveRule | undefined
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const tools = policy.tools
|
|
72
|
+
if (!tools) return undefined
|
|
73
|
+
|
|
74
|
+
const [head, member] = splitAddress(fn)
|
|
75
|
+
const entry = tools[head]
|
|
76
|
+
|
|
77
|
+
if (isMemberBag(entry)) {
|
|
78
|
+
// A bag with no rule for this member is not a miss — the bag
|
|
79
|
+
// itself is the statement about everything under it, and falling
|
|
80
|
+
// through to `*` would let a wildcard override a rule the author
|
|
81
|
+
// wrote about this exact tool.
|
|
82
|
+
if (member !== undefined && member in entry) return entry[member]
|
|
83
|
+
return tools[POLICY_WILDCARD]
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
return entry ?? tools[POLICY_WILDCARD]
|
|
56
87
|
}
|
|
57
88
|
|
|
89
|
+
/**
|
|
90
|
+
* `fn` is the ADDRESS policy resolves against; `owner` is the module the
|
|
91
|
+
* export came from, carried for the audit record only. They were once the
|
|
92
|
+
* same idea — policy keyed on the owning namespace — which is why a rule
|
|
93
|
+
* about `fs` could not distinguish `fs.read` from a bare `read` shipped
|
|
94
|
+
* by a different module.
|
|
95
|
+
*/
|
|
58
96
|
async function check(fn: string, subject: string, args: unknown[], owner: string): Promise<boolean> {
|
|
59
|
-
const rule = ruleFor(fn
|
|
60
|
-
const
|
|
97
|
+
const rule = ruleFor(fn)
|
|
98
|
+
const resolved = evaluateRule(rule, subject, "agent")
|
|
99
|
+
const verdict = resolved?.verdict ?? "deny"
|
|
61
100
|
|
|
62
101
|
if (verdict === "allow") return true
|
|
63
102
|
|
|
@@ -113,8 +152,47 @@ export function Mediation(opts: MediationOpts) {
|
|
|
113
152
|
return active ? { runId: active.runId, spanId: Bun.randomUUIDv7() } : undefined
|
|
114
153
|
}
|
|
115
154
|
|
|
155
|
+
/**
|
|
156
|
+
* Decide one program execution.
|
|
157
|
+
*
|
|
158
|
+
* Separate from `check` because the QUESTION is different: `check` resolves
|
|
159
|
+
* an address to a rule and matches a subject against it, while this
|
|
160
|
+
* resolves an argv to the program it actually runs — seeing through `env`,
|
|
161
|
+
* `nice`, an absolute path, or a shell — and decides on that. The old
|
|
162
|
+
* `process.run` rule tried to do it as a glob over the command string, and
|
|
163
|
+
* four spellings of one command defeated it.
|
|
164
|
+
*
|
|
165
|
+
* Escalation still routes through the same decider, so a `"escalate"`
|
|
166
|
+
* verdict on an argument pattern prompts exactly like any other.
|
|
167
|
+
*/
|
|
168
|
+
async function shell(argv: string[], owner: string): Promise<ShellDecision> {
|
|
169
|
+
// Axon's posture: an agent whose blueprint declares no shell policy is
|
|
170
|
+
// a personal tool with the user's own privileges. The capsule's is the
|
|
171
|
+
// opposite — see decideShell's `fallback`.
|
|
172
|
+
const decision = decideShell(opts.policy().shell, argv, "allow")
|
|
173
|
+
if (decision.verdict === "allow") return decision
|
|
174
|
+
|
|
175
|
+
const fn = `shell.run:${decision.program}`
|
|
176
|
+
const subject = argv.join(" ")
|
|
177
|
+
|
|
178
|
+
if (decision.verdict === "deny") {
|
|
179
|
+
await opts.session.commit("process:policy:denied", {
|
|
180
|
+
id: randomUUID(), module: owner, fn, args: argv, rule: decision.reason,
|
|
181
|
+
}, span())
|
|
182
|
+
return decision
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
const allowed = await check(fn, subject, argv, owner)
|
|
186
|
+
return allowed ? { ...decision, verdict: "allow" } : { ...decision, verdict: "deny" }
|
|
187
|
+
}
|
|
188
|
+
|
|
116
189
|
return {
|
|
117
190
|
check,
|
|
191
|
+
shell,
|
|
192
|
+
/** `shell()` for a command that arrived as a string rather than argv. */
|
|
193
|
+
shellCommand(command: string, owner: string): Promise<ShellDecision> {
|
|
194
|
+
return shell(splitCommand(command), owner)
|
|
195
|
+
},
|
|
118
196
|
/**
|
|
119
197
|
* The span stream every surface reads.
|
|
120
198
|
*
|
|
@@ -144,3 +222,15 @@ export function Mediation(opts: MediationOpts) {
|
|
|
144
222
|
}
|
|
145
223
|
|
|
146
224
|
export type MediationT = ReturnType<typeof Mediation>
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* Split a call address into its head and (optional) member.
|
|
228
|
+
*
|
|
229
|
+
* `fs.read` → ["fs", "read"]; `read` → ["read", undefined]. Only the FIRST
|
|
230
|
+
* dot splits: the scope is one level deep, so anything after it is part of
|
|
231
|
+
* the member name rather than a third level to walk.
|
|
232
|
+
*/
|
|
233
|
+
function splitAddress(fn: string): [string, string | undefined] {
|
|
234
|
+
const dot = fn.indexOf(".")
|
|
235
|
+
return dot === -1 ? [fn, undefined] : [fn.slice(0, dot), fn.slice(dot + 1)]
|
|
236
|
+
}
|
package/src/scope.ts
CHANGED
|
@@ -38,7 +38,6 @@ export function toScopeModule(tool: AxonTool): AxonScopeModule {
|
|
|
38
38
|
name: tool.name,
|
|
39
39
|
...(tool.description ? { description: tool.description } : {}),
|
|
40
40
|
members: tool.fns,
|
|
41
|
-
...(tool.flat ? { flat: true } : {}),
|
|
42
41
|
...(tool.ambientTypes ? { ambientTypes: tool.ambientTypes } : {}),
|
|
43
42
|
}
|
|
44
43
|
}
|
|
@@ -48,14 +47,15 @@ export function toScopeModule(tool: AxonTool): AxonScopeModule {
|
|
|
48
47
|
* excluded — declaring something the capsule cannot call would tell the
|
|
49
48
|
* model to invoke a function that does not exist there.
|
|
50
49
|
*
|
|
51
|
-
*
|
|
50
|
+
* Members are then deduped by CALLABLE NAME, which is a different
|
|
52
51
|
* question from the one merge() answers. merge() resolves collisions between
|
|
53
52
|
* TOOL names (the filename): an agent's `weather.ts` shadowing a module's
|
|
54
53
|
* `weather.ts`. It cannot see two differently-named files whose exports
|
|
55
54
|
* collide — an agent's `weather.ts` and a module's `forecast.ts` both
|
|
56
55
|
* exporting `now()` are two distinct tools by its reckoning, so both survive.
|
|
57
56
|
*
|
|
58
|
-
* Both then install
|
|
57
|
+
* Both then install under the same global name, and everything downstream
|
|
58
|
+
* would silently pick a winner:
|
|
59
59
|
* the .d.ts and the model's <scope> each declare `function now()` twice, and
|
|
60
60
|
* the capsule builds its globals with Object.assign, so whichever tool loads
|
|
61
61
|
* last wins and the other export is unreachable with nothing reported. The
|
|
@@ -71,11 +71,9 @@ export function toScope(blueprint: AxonBlueprint): AxonScope {
|
|
|
71
71
|
// order modules happen to appear in the blueprint.
|
|
72
72
|
for (const tool of [...loadable].sort((a, b) => rank(a) - rank(b))) {
|
|
73
73
|
const module = toScopeModule(tool)
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
}
|
|
78
|
-
|
|
74
|
+
// Every export lands in the agent's global scope under its own name,
|
|
75
|
+
// so a name can only be claimed once. Agent-origin tools sorted
|
|
76
|
+
// first above means the agent's own export wins a contested name.
|
|
79
77
|
const members = module.members.filter(member => !claimed.has(member.name))
|
|
80
78
|
for (const member of members) claimed.add(member.name)
|
|
81
79
|
if (members.length > 0) modules.push({ ...module, members })
|