@arcforge/kernel 2.0.155 → 2.0.156
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/capsule.ts +26 -216
- package/src/contracts.ts +11 -1
- package/src/engine.ts +26 -1
- package/src/kernel.ts +114 -11
- package/src/mediation.ts +146 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.156",
|
|
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.156",
|
|
19
|
+
"@arcforge/engines": "2.0.156",
|
|
20
|
+
"@arcforge/err": "2.0.156",
|
|
21
|
+
"@arcforge/session": "2.0.156",
|
|
22
|
+
"@arcforge/types": "2.0.156",
|
|
23
|
+
"@arclabs/cloud": "2.0.156",
|
|
24
|
+
"@axon/capsule": "2.0.156"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@types/bun": "latest",
|
package/src/capsule.ts
CHANGED
|
@@ -1,9 +1,8 @@
|
|
|
1
|
-
import { isAbsolute, resolve } from "node:path"
|
|
2
1
|
import { Capsule, CapsuleT } from "@axon/capsule"
|
|
3
2
|
import type { CapsulePartialConfig, CapsuleTool } from "@axon/capsule"
|
|
4
3
|
import { err } from "@arcforge/err"
|
|
5
|
-
import { CAPSULE_TRANSIENT_EVENTS,
|
|
6
|
-
import type { AxonBlueprint, AxonEventMap
|
|
4
|
+
import { CAPSULE_TRANSIENT_EVENTS, Policy } from "@arcforge/types"
|
|
5
|
+
import type { AxonBlueprint, AxonEventMap } from "@arcforge/types"
|
|
7
6
|
import type { AxonEscalate, AxonHost } from "@arcforge/types"
|
|
8
7
|
import type { KernelBus } from "./contracts"
|
|
9
8
|
import type { AxonSessionT } from "@arcforge/session"
|
|
@@ -39,221 +38,32 @@ function toCapsuleTools(blueprint: AxonBlueprint): CapsuleTool[] {
|
|
|
39
38
|
}
|
|
40
39
|
|
|
41
40
|
/**
|
|
42
|
-
* The capsule's
|
|
43
|
-
* that must never silently grant an undeclared capability to arbitrary
|
|
44
|
-
* loaded code. Axon is a different trust boundary: it is wiring up a
|
|
45
|
-
* capsule for its OWN declared blueprint, not sandboxing foreign code, so
|
|
46
|
-
* its default posture is the opposite — allow everything the blueprint's
|
|
47
|
-
* own policy doesn't explicitly restrict. Every tool namespace actually
|
|
48
|
-
* installed in the capsule gets an allow rule unless the blueprint's policy
|
|
49
|
-
* says otherwise; the user's own policy always wins (spread last).
|
|
41
|
+
* The capsule's policy, resolved.
|
|
50
42
|
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
for (const tool of blueprint.tools.filter(isLoadable)) tools[tool.name] = true
|
|
58
|
-
|
|
59
|
-
// The two layers, intersected into what the capsule enforces.
|
|
60
|
-
//
|
|
61
|
-
// The profile is a CEILING: an agent narrows within it and can never widen
|
|
62
|
-
// it. Resolved HERE rather than in the TUI, because this is the one seam
|
|
63
|
-
// every consumer passes through — `axon dev`, `axon run` in a script, a
|
|
64
|
-
// test harness. A ceiling applied only on the TUI's spawn path would be
|
|
65
|
-
// advisory, and the CLI is exactly where someone scripting would bypass it
|
|
66
|
-
// without meaning to.
|
|
67
|
-
// Both layers normalised to the KEYED shape before they meet.
|
|
68
|
-
//
|
|
69
|
-
// A bare `tools: "escalate"` is an authoring convenience; every rule below
|
|
70
|
-
// — the pairing, the wildcard lookup, the mediator — reads one shape. Doing
|
|
71
|
-
// it here rather than in each of them is the same discipline Blueprint()
|
|
72
|
-
// applies at the capsule seam.
|
|
73
|
-
const userPolicy = intersect(
|
|
74
|
-
blueprint.profilePolicy ? keyed(blueprint.profilePolicy) : undefined,
|
|
75
|
-
keyed(blueprint.config.policy ?? {}),
|
|
76
|
-
)
|
|
77
|
-
|
|
78
|
-
// The invariant: not setting a security policy means "I don't care" — the
|
|
79
|
-
// agent gets full access to the machine, no hassle, no dependencies. Setting
|
|
80
|
-
// ANY containment intent (fs/network/limits) opts into rootless confinement,
|
|
81
|
-
// which needs no privilege and just works. A user can always name isolation
|
|
82
|
-
// explicitly to force a tier (e.g. "hardened", or "none" despite having fs).
|
|
83
|
-
//
|
|
84
|
-
// Read off the INTERSECTED policy, so a profile declaring containment opts
|
|
85
|
-
// every agent on the machine into it — an agent that declares nothing still
|
|
86
|
-
// gets the wall its profile asked for.
|
|
87
|
-
const wantsContainment =
|
|
88
|
-
userPolicy.fs !== undefined || userPolicy.network !== undefined || userPolicy.limits !== undefined
|
|
89
|
-
const isolation = userPolicy.isolation ?? (wantsContainment ? "auto" : "none")
|
|
90
|
-
|
|
91
|
-
return {
|
|
92
|
-
...userPolicy,
|
|
93
|
-
isolation,
|
|
94
|
-
// fs paths are authored relative to the AGENT PROJECT, not the directory
|
|
95
|
-
// the user happened to launch from. `fs: { read: ["./workspace"] }` in
|
|
96
|
-
// agents/foo/axon.config.ts means agents/foo/workspace, wherever axon
|
|
97
|
-
// was run. Resolve against paths.root here, at the seam that knows it —
|
|
98
|
-
// the capsule only ever sees absolute paths.
|
|
99
|
-
...(userPolicy.fs ? { fs: resolveFsPaths(userPolicy.fs, blueprint.paths.root) } : {}),
|
|
100
|
-
process: { spawn: true, run: true, ...userPolicy.process },
|
|
101
|
-
tools: { ...tools, ...userPolicy.tools },
|
|
102
|
-
}
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
/**
|
|
106
|
-
* Intersect the profile ceiling with an agent's own policy.
|
|
107
|
-
*
|
|
108
|
-
* ── Why this is a UNION of keys, not of permissions ─────────────────────────
|
|
109
|
-
*
|
|
110
|
-
* Both layers' rules are carried forward per capability, and the MEDIATOR
|
|
111
|
-
* evaluates the pair at call time (see resolveVerdict in @arcforge/types).
|
|
112
|
-
* That split is deliberate: merging two glob rules into one is where a ceiling
|
|
113
|
-
* silently springs a leak — `allow: ["git status"]` unioned with
|
|
114
|
-
* `allow: ["git push"]` permits a command neither layer permitted alone.
|
|
115
|
-
*
|
|
116
|
-
* So this composes the SHAPE (which capabilities each layer has an opinion
|
|
117
|
-
* about) and leaves the VERDICT to per-call evaluation, where both rules are
|
|
118
|
-
* still separately available and the answer can name which one decided.
|
|
43
|
+
* Delegates to Policy() in @arcforge/types — the ONE place a profile ceiling
|
|
44
|
+
* and an agent's own policy become the shape the capsule enforces. This file
|
|
45
|
+
* used to carry that resolution itself (intersect/pairRule/keyed/bucket plus a
|
|
46
|
+
* second POLICY_WILDCARD literal), while the capsule's Blueprint() normalised
|
|
47
|
+
* the result again at its own seam. Two implementations of one rule, kept in
|
|
48
|
+
* step by a test that read both files' source for a matching string literal.
|
|
119
49
|
*
|
|
120
|
-
*
|
|
121
|
-
*
|
|
122
|
-
*
|
|
123
|
-
* a profile `false` is final regardless of what the agent says, and a profile
|
|
124
|
-
* `true` adds no constraint the agent could violate. Collapsing them at this
|
|
125
|
-
* seam keeps the common case (a profile that just says "no shell") from
|
|
126
|
-
* costing a pair lookup on every call.
|
|
127
|
-
*
|
|
128
|
-
* fs and limits are NOT intersected: they are OS-layer facts (bind mounts,
|
|
129
|
-
* cgroups) with no verdict to evaluate, and the mediator never sees them. The
|
|
130
|
-
* profile's are taken when present, since a ceiling that a bind mount ignores
|
|
131
|
-
* is not a ceiling.
|
|
50
|
+
* They were separate because the mediator is GUEST code and could not import
|
|
51
|
+
* across the subprocess boundary. Resolution now happens above both consumers,
|
|
52
|
+
* so there is one implementation and the guard it needed is gone.
|
|
132
53
|
*/
|
|
133
|
-
function intersect(
|
|
134
|
-
profile: NormalizedPolicy | undefined,
|
|
135
|
-
agent: NormalizedPolicy,
|
|
136
|
-
): NormalizedPolicy {
|
|
137
|
-
if (!profile) return agent
|
|
138
|
-
|
|
139
|
-
return {
|
|
140
|
-
...agent,
|
|
141
|
-
isolation: resolveIsolation(profile.isolation, agent.isolation) ?? agent.isolation,
|
|
142
|
-
|
|
143
|
-
// The OS wall. A profile grant is the outer bound, so an agent's paths
|
|
144
|
-
// are kept only where the profile has no opinion at all — otherwise a
|
|
145
|
-
// narrower mount would have to be computed, which bind mounts cannot
|
|
146
|
-
// express as an intersection of globs.
|
|
147
|
-
...(profile.fs ? { fs: profile.fs } : {}),
|
|
148
|
-
...(profile.limits ? { limits: profile.limits } : {}),
|
|
149
|
-
|
|
150
|
-
...(profile.network || agent.network
|
|
151
|
-
? { network: pairRules(profile.network, agent.network) }
|
|
152
|
-
: {}),
|
|
153
|
-
...(profile.tools || agent.tools
|
|
154
|
-
? { tools: pairRules(profile.tools, agent.tools) }
|
|
155
|
-
: {}),
|
|
156
|
-
|
|
157
|
-
process: {
|
|
158
|
-
spawn: pairRule(profile.process?.spawn, agent.process?.spawn),
|
|
159
|
-
run: pairRule(profile.process?.run, agent.process?.run),
|
|
160
|
-
},
|
|
161
|
-
}
|
|
162
|
-
}
|
|
163
|
-
|
|
164
54
|
/**
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
168
|
-
* pattern and cannot be widened at all. Otherwise the agent's rule stands and
|
|
169
|
-
* the profile's is carried alongside for the mediator to evaluate against.
|
|
55
|
+
* Exported so IN-PROCESS mediation enforces the SAME resolved policy the
|
|
56
|
+
* capsule does. Two resolutions of one policy is how a tool ends up permitted
|
|
57
|
+
* on one path and denied on the other, with nothing to say which is right.
|
|
170
58
|
*/
|
|
171
|
-
function
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
}
|
|
180
|
-
|
|
181
|
-
/** pairRule across two keyed maps, over the union of their keys. */
|
|
182
|
-
function pairRules(
|
|
183
|
-
profile: Record<string, PolicyRule> | undefined,
|
|
184
|
-
agent: Record<string, PolicyRule> | undefined,
|
|
185
|
-
): Record<string, PolicyRule> {
|
|
186
|
-
const keys = new Set([...Object.keys(profile ?? {}), ...Object.keys(agent ?? {})])
|
|
187
|
-
const out: Record<string, PolicyRule> = {}
|
|
188
|
-
|
|
189
|
-
// A profile WILDCARD applies to every key, not only to `*`.
|
|
190
|
-
//
|
|
191
|
-
// Without this the ceiling leaks in exactly the case the wildcard exists
|
|
192
|
-
// for: a profile saying `tools: "escalate"` normalises to `{ "*":
|
|
193
|
-
// "escalate" }`, an agent's `tools: { fs: true }` keeps its own key, and
|
|
194
|
-
// the mediator's exact-match then hands back `true` — the profile's
|
|
195
|
-
// blanket never consulted. A ceiling a named grant can punch through is
|
|
196
|
-
// not a ceiling.
|
|
197
|
-
//
|
|
198
|
-
// Paired per key rather than replacing the agent's rule, so the profile's
|
|
199
|
-
// blanket and the agent's specific are BOTH carried to the mediator and
|
|
200
|
-
// the verdict can still name which layer decided.
|
|
201
|
-
const blanket = profile?.[POLICY_WILDCARD]
|
|
202
|
-
|
|
203
|
-
for (const key of keys) out[key] = pairRule(profile?.[key] ?? blanket, agent?.[key])
|
|
204
|
-
return out
|
|
205
|
-
}
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
/** The key a blanket rule normalises to — mirrors POLICY_WILDCARD in @axon/capsule. */
|
|
209
|
-
const POLICY_WILDCARD = "*"
|
|
210
|
-
|
|
211
|
-
/**
|
|
212
|
-
* One authored policy, with every bare surface rule expanded to `{ "*": rule }`.
|
|
213
|
-
*
|
|
214
|
-
* `tools: "escalate"` and `tools: { "*": "escalate" }` are the same statement;
|
|
215
|
-
* this makes them the same VALUE, so nothing downstream has to ask which was
|
|
216
|
-
* written. `process` is a fixed pair rather than an open bucket, so a bare rule
|
|
217
|
-
* there applies to both verbs instead of becoming a key no verb would match.
|
|
218
|
-
*/
|
|
219
|
-
function keyed(policy: NonNullable<CapsulePartialConfig["policy"]>): NormalizedPolicy {
|
|
220
|
-
const { tools, network, process: proc, ...rest } = policy
|
|
221
|
-
return {
|
|
222
|
-
...rest,
|
|
223
|
-
...(tools !== undefined ? { tools: bucket(tools) } : {}),
|
|
224
|
-
...(network !== undefined ? { network: bucket(network) } : {}),
|
|
225
|
-
...(proc !== undefined
|
|
226
|
-
? { process: isBareRule(proc) ? { spawn: proc, run: proc } : proc }
|
|
227
|
-
: {}),
|
|
228
|
-
}
|
|
229
|
-
}
|
|
230
|
-
|
|
231
|
-
type NormalizedPolicy = Omit<NonNullable<CapsulePartialConfig["policy"]>, "tools" | "network" | "process"> & {
|
|
232
|
-
tools?: Record<string, PolicyRule>
|
|
233
|
-
network?: Record<string, PolicyRule>
|
|
234
|
-
process?: Partial<CapsulePolicy["process"]>
|
|
235
|
-
}
|
|
236
|
-
|
|
237
|
-
function bucket(value: NonNullable<CapsulePartialConfig["policy"]>["tools"]): Record<string, PolicyRule> {
|
|
238
|
-
if (value === undefined) return {}
|
|
239
|
-
return isBareRule(value) ? { [POLICY_WILDCARD]: value } : value
|
|
240
|
-
}
|
|
241
|
-
|
|
242
|
-
/** A rule with no keys of its own — `true`, `false`, `"escalate"`, or a glob object. */
|
|
243
|
-
function isBareRule(value: unknown): value is PolicyRule {
|
|
244
|
-
if (typeof value === "boolean" || value === "escalate") return true
|
|
245
|
-
if (typeof value !== "object" || value === null) return false
|
|
246
|
-
const keys = Object.keys(value)
|
|
247
|
-
return keys.length > 0 && keys.every(key => key === "allow" || key === "deny" || key === "escalate")
|
|
248
|
-
}
|
|
249
|
-
|
|
250
|
-
/** Resolve an fs policy's relative paths against the agent project root. */
|
|
251
|
-
function resolveFsPaths(fs: NonNullable<CapsulePolicy["fs"]>, root: string): CapsulePolicy["fs"] {
|
|
252
|
-
const abs = (p: string) => (isAbsolute(p) ? p : resolve(root, p))
|
|
253
|
-
return {
|
|
254
|
-
...(fs.read ? { read: fs.read.map(abs) } : {}),
|
|
255
|
-
...(fs.write ? { write: fs.write.map(abs) } : {}),
|
|
256
|
-
}
|
|
59
|
+
export function defaultPolicy(blueprint: AxonBlueprint): CapsulePartialConfig["policy"] {
|
|
60
|
+
return Policy({
|
|
61
|
+
blueprint,
|
|
62
|
+
// Scoped to LOADABLE tools for the same reason toCapsuleTools() is: a
|
|
63
|
+
// rule naming a namespace the capsule never installs grants nothing and
|
|
64
|
+
// only makes the policy surface read as larger than it is.
|
|
65
|
+
tools: blueprint.tools.filter(isLoadable).map(tool => tool.name),
|
|
66
|
+
}).policy
|
|
257
67
|
}
|
|
258
68
|
|
|
259
69
|
type AxonCapsuleOpts = {
|
|
@@ -326,7 +136,7 @@ export async function AxonCapsule(opts: AxonCapsuleOpts) {
|
|
|
326
136
|
capsule.onAny((event) => {
|
|
327
137
|
// The sandbox reports every cwd change as it happens, so the
|
|
328
138
|
// live location is always known without asking for it.
|
|
329
|
-
if (event.type === "
|
|
139
|
+
if (event.type === "process:cwd") liveCwd = event.cwd
|
|
330
140
|
const { type, ...data } = event
|
|
331
141
|
// onAny is a synchronous listener on the capsule's own bus — it
|
|
332
142
|
// cannot await, so both writes below are fire-and-forget. The
|
|
@@ -345,7 +155,7 @@ export async function AxonCapsule(opts: AxonCapsuleOpts) {
|
|
|
345
155
|
await capsule.boot()
|
|
346
156
|
|
|
347
157
|
currentId = crypto.randomUUID()
|
|
348
|
-
await opts.session.commit("
|
|
158
|
+
await opts.session.commit("process:attach", { capsuleId: currentId, cwd: liveCwd ?? opts.cwd })
|
|
349
159
|
|
|
350
160
|
return capsule
|
|
351
161
|
}
|
|
@@ -358,7 +168,7 @@ export async function AxonCapsule(opts: AxonCapsuleOpts) {
|
|
|
358
168
|
* already reassigned) by the time the old one's detach is recorded.
|
|
359
169
|
*/
|
|
360
170
|
async function detach(capsuleId: string, reason: "shutdown" | "crash" | "reload"): Promise<void> {
|
|
361
|
-
await opts.session.commit("
|
|
171
|
+
await opts.session.commit("process:detach", { capsuleId, reason })
|
|
362
172
|
}
|
|
363
173
|
|
|
364
174
|
async function reload() {
|
package/src/contracts.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { AxonBlueprint, CognetSchedule, CognetWake, KernelAbi } from "@arcforge/types"
|
|
1
|
+
import type { EngineRequirements, AxonBlueprint, CognetSchedule, CognetWake, KernelAbi } from "@arcforge/types"
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* What ring 0 requires of its injected collaborators — declared structurally,
|
|
@@ -34,6 +34,16 @@ export type KernelCognet = {
|
|
|
34
34
|
* sensor names the few kinds worth a thought.
|
|
35
35
|
*/
|
|
36
36
|
readonly wakeOn?: readonly string[]
|
|
37
|
+
/**
|
|
38
|
+
* The inference roles this brain declared.
|
|
39
|
+
*
|
|
40
|
+
* Read only when inference is REMOTE: role resolution then happened in the
|
|
41
|
+
* supervisor, so this process has no binding to read capability facts
|
|
42
|
+
* from, and the declaration is the honest answer to "what did this role
|
|
43
|
+
* ask for". It is also all a confined agent may know — the resolved
|
|
44
|
+
* capability names a provider and a model the boundary exists to hide.
|
|
45
|
+
*/
|
|
46
|
+
readonly engines?: EngineRequirements
|
|
37
47
|
load(abi: KernelAbi): Promise<void>
|
|
38
48
|
wake(wake: CognetWake): Promise<void>
|
|
39
49
|
update(blueprint: AxonBlueprint): Promise<void> | void
|
package/src/engine.ts
CHANGED
|
@@ -39,6 +39,22 @@ type EngineOpts = {
|
|
|
39
39
|
* dispatches through, and nothing else changes when it is missing.
|
|
40
40
|
*/
|
|
41
41
|
engines?: EnginesT
|
|
42
|
+
/**
|
|
43
|
+
* Build the driver for a role, when inference lives outside this process.
|
|
44
|
+
*
|
|
45
|
+
* Present in a CONFINED agent: the provider credential is held by the
|
|
46
|
+
* supervisor and never enters the box, so the agent asks for a role and
|
|
47
|
+
* receives tokens. Absent everywhere else (a local runtime, a test), where
|
|
48
|
+
* `engines` resolves a real driver in this heap.
|
|
49
|
+
*
|
|
50
|
+
* A DRIVER rather than a new seam, deliberately. `AxonEngineDriver` is
|
|
51
|
+
* already "a dumb token pipe: messages in, raw deltas out — no AIR parsing,
|
|
52
|
+
* no bus, no blocks", which is exactly what a wire is. So everything this
|
|
53
|
+
* manager owns — the grammar, the retry budget, the output contract, the
|
|
54
|
+
* idle-stall guard — stays here and cannot tell the tokens crossed a
|
|
55
|
+
* process boundary to arrive.
|
|
56
|
+
*/
|
|
57
|
+
remote?: (role: string) => AxonEngineDriver
|
|
42
58
|
}
|
|
43
59
|
|
|
44
60
|
type EngineContext = {
|
|
@@ -412,7 +428,16 @@ export function Engine(opts: EngineOpts) {
|
|
|
412
428
|
* fills it.
|
|
413
429
|
*/
|
|
414
430
|
function select(role: string | undefined): { driver: AxonEngineDriver; name: string } | null {
|
|
415
|
-
if (!role
|
|
431
|
+
if (!role) return null
|
|
432
|
+
|
|
433
|
+
// Remote first: in a confined agent there is no local driver to fall
|
|
434
|
+
// back to, because there is no credential in the box to build one
|
|
435
|
+
// with. Checked before `engines` so a runtime that happens to carry
|
|
436
|
+
// both cannot silently prefer the in-process path and pull a key
|
|
437
|
+
// inside the boundary.
|
|
438
|
+
if (opts.remote) return { driver: opts.remote(role), name: "supervisor" }
|
|
439
|
+
|
|
440
|
+
if (!opts.engines) return null
|
|
416
441
|
const bound = opts.engines.get(role)
|
|
417
442
|
|
|
418
443
|
// This manager IS the generate path — AIR parsing, the retry budget,
|
package/src/kernel.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { err } from "@arcforge/err"
|
|
2
|
-
import type { AxonBlueprint, AxonDriver, AxonEngineCall, AxonEngineEvent, AxonEntry, AxonEntryEvent, AxonEventMap, AxonRunResult, CapsuleCommandOrigin, EngineSession, KernelAbi, TransformOptions } from "@arcforge/types"
|
|
2
|
+
import type { AxonBlueprint, AxonDriver, AxonEngineCall, AxonEngineDriver, CapsulePolicy, 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"
|
|
@@ -7,9 +7,10 @@ import { Engine } from "./engine"
|
|
|
7
7
|
import { asEngineFault } from "@arcforge/engines"
|
|
8
8
|
import type { EnginesT } from "@arcforge/engines/catalogue"
|
|
9
9
|
import type { AxonSessionT } from "@arcforge/session"
|
|
10
|
-
import { AxonCapsule, type AxonCapsuleT } from "./capsule"
|
|
10
|
+
import { AxonCapsule, defaultPolicy, type AxonCapsuleT } from "./capsule"
|
|
11
11
|
import { Scheduler } from "./scheduler"
|
|
12
12
|
import type { KernelCognet } from "./contracts"
|
|
13
|
+
import { Mediation } from "./mediation"
|
|
13
14
|
import { Store } from "./store"
|
|
14
15
|
import { Knowledge } from "./knowledge"
|
|
15
16
|
import type { AxonEscalate, AxonHost } from "@arcforge/types"
|
|
@@ -34,6 +35,14 @@ type KernelOpts = {
|
|
|
34
35
|
* exactly one continuous stream.
|
|
35
36
|
*/
|
|
36
37
|
session: AxonSessionT
|
|
38
|
+
/**
|
|
39
|
+
* Inference lives outside this process — see EngineOpts.remote.
|
|
40
|
+
*
|
|
41
|
+
* Threaded through rather than reached for, so the kernel never learns
|
|
42
|
+
* whether it is confined. Ring 0 asks for a driver by role and gets one;
|
|
43
|
+
* where that driver's tokens come from is the boundary's business.
|
|
44
|
+
*/
|
|
45
|
+
remote?: (role: string) => AxonEngineDriver
|
|
37
46
|
/**
|
|
38
47
|
* The agent's base identity text, rendered fresh per call — backs the
|
|
39
48
|
* ABI's base(). Injected because rendering it is a PRESENTATION concern
|
|
@@ -277,6 +286,17 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
277
286
|
const cognet = opts.cognet
|
|
278
287
|
const session = opts.session
|
|
279
288
|
|
|
289
|
+
/**
|
|
290
|
+
* The blueprint currently live, kept in step by update().
|
|
291
|
+
*
|
|
292
|
+
* The kernel otherwise reads `opts.blueprint` directly, which is correct
|
|
293
|
+
* for everything resolved once at construction. Policy is not one of those
|
|
294
|
+
* things: a hot reload changes it, and mediation must enforce what the
|
|
295
|
+
* agent IS rather than what it was at boot.
|
|
296
|
+
*/
|
|
297
|
+
let live = opts.blueprint
|
|
298
|
+
const blueprintNow = () => live
|
|
299
|
+
|
|
280
300
|
const scheduler = Scheduler({
|
|
281
301
|
bus: opts.bus,
|
|
282
302
|
session: session,
|
|
@@ -293,8 +313,26 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
293
313
|
...(opts.escalate ? { escalate: opts.escalate } : {}),
|
|
294
314
|
})
|
|
295
315
|
|
|
316
|
+
/**
|
|
317
|
+
* The policy gate and audit trail for tools running IN this process.
|
|
318
|
+
*
|
|
319
|
+
* Built unconditionally — it costs nothing unloaded, and a runtime that
|
|
320
|
+
* had to decide whether to construct it would need to know whether it is
|
|
321
|
+
* confined, which is exactly the fact ring 0 is kept ignorant of.
|
|
322
|
+
*/
|
|
323
|
+
const mediation = Mediation({
|
|
324
|
+
// Resolved from the LIVE blueprint on every call, through the same
|
|
325
|
+
// function the capsule is configured with — one resolution, so a tool
|
|
326
|
+
// cannot be permitted in-process and denied in the box.
|
|
327
|
+
policy: () => defaultPolicy(blueprintNow()) as CapsulePolicy,
|
|
328
|
+
session,
|
|
329
|
+
...(opts.escalate ? { escalate: opts.escalate } : {}),
|
|
330
|
+
run: () => scheduler.current(),
|
|
331
|
+
})
|
|
332
|
+
|
|
296
333
|
const engine = Engine({
|
|
297
334
|
...(opts.engines ? { engines: opts.engines } : {}),
|
|
335
|
+
...(opts.remote ? { remote: opts.remote } : {}),
|
|
298
336
|
blueprint: opts.blueprint,
|
|
299
337
|
session,
|
|
300
338
|
cloud: opts.cloud,
|
|
@@ -508,28 +546,76 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
508
546
|
* an untraced second model would be exactly the observability hole this
|
|
509
547
|
* whole layer is supposed to close.
|
|
510
548
|
*/
|
|
549
|
+
/**
|
|
550
|
+
* What the cognet DECLARED for a role.
|
|
551
|
+
*
|
|
552
|
+
* The authority when inference is remote: role resolution happened in the
|
|
553
|
+
* supervisor, so this process has no `bound` entry to read capability
|
|
554
|
+
* facts from. The declaration is the honest answer to "what did this role
|
|
555
|
+
* ask for" — and it is all a confined agent may know, since the resolved
|
|
556
|
+
* capability names a provider and a model the boundary exists to hide.
|
|
557
|
+
*/
|
|
558
|
+
function declaredRole(role: string) {
|
|
559
|
+
return cognet.engines?.[role]
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
/**
|
|
563
|
+
* A declared requirement, as the ABI's EngineFacts.
|
|
564
|
+
*
|
|
565
|
+
* `in`/`out` accept a single modality as shorthand for one, so both are
|
|
566
|
+
* widened to arrays here — the ABI promises arrays and a consumer that had
|
|
567
|
+
* to test which it got would be reading the shorthand, not the fact.
|
|
568
|
+
*
|
|
569
|
+
* `slots` defaults to 1: the contract says at least one, and one is what a
|
|
570
|
+
* role gets unless resolution granted more. Claiming more than the
|
|
571
|
+
* supervisor actually allocated would let a cognet fan out past what its
|
|
572
|
+
* roles can serve.
|
|
573
|
+
*/
|
|
574
|
+
function factsFromDeclaration(declared: NonNullable<ReturnType<typeof declaredRole>>) {
|
|
575
|
+
const list = <T>(value: T | T[]): T[] => (Array.isArray(value) ? value : [value])
|
|
576
|
+
return {
|
|
577
|
+
context: declared.context,
|
|
578
|
+
modalities: { in: list(declared.in), out: list(declared.out) },
|
|
579
|
+
slots: 1,
|
|
580
|
+
}
|
|
581
|
+
}
|
|
582
|
+
|
|
511
583
|
const engineAbi = Object.assign(
|
|
512
584
|
(role: string) => {
|
|
513
585
|
const bound = opts.engines?.resolution.bound.find(entry => entry.role === role)
|
|
514
|
-
|
|
586
|
+
const declared = declaredRole(role)
|
|
587
|
+
|
|
588
|
+
// Remote inference has no local binding — and must not need one.
|
|
589
|
+
// The role's existence is settled by the cognet's own declaration;
|
|
590
|
+
// what fills it was settled by the supervisor before this process
|
|
591
|
+
// started.
|
|
592
|
+
if (!bound && !(opts.remote && declared)) {
|
|
515
593
|
throw err("ENGINE_ROLE_UNBOUND", {
|
|
516
594
|
detail: `no engine bound to "${role}" — declare it in engines: and check kernel.engine.has() for optional roles`,
|
|
517
595
|
})
|
|
518
596
|
}
|
|
519
597
|
|
|
520
598
|
// What the role ACTUALLY got, shared by every handle shape.
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
599
|
+
//
|
|
600
|
+
// Resolved facts when there is a local binding; the DECLARATION
|
|
601
|
+
// otherwise. A confined agent reads what it asked for rather than
|
|
602
|
+
// what it was given, which is the same indirection that keeps
|
|
603
|
+
// cognition from learning which model is behind a role.
|
|
604
|
+
const facts = bound
|
|
605
|
+
? {
|
|
606
|
+
get context() { return bound.capability.context },
|
|
607
|
+
get modalities() { return { in: bound.capability.in, out: bound.capability.out } },
|
|
608
|
+
get slots() { return bound.slots },
|
|
609
|
+
}
|
|
610
|
+
: factsFromDeclaration(declared!)
|
|
611
|
+
const kind = bound?.requirement.type ?? declared?.type
|
|
526
612
|
|
|
527
613
|
// The handle follows the DECLARED type, because that is what the
|
|
528
614
|
// cognet's code was written against: a loop calling `.transform()`
|
|
529
615
|
// cannot run against a `.stream()` handle however substitutable
|
|
530
616
|
// the model behind it is. Resolution already refused anything
|
|
531
617
|
// whose type disagrees, so this never has to reconcile them.
|
|
532
|
-
if (
|
|
618
|
+
if (kind === "transform") {
|
|
533
619
|
return {
|
|
534
620
|
...facts,
|
|
535
621
|
type: "transform" as const,
|
|
@@ -538,7 +624,7 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
538
624
|
}
|
|
539
625
|
}
|
|
540
626
|
|
|
541
|
-
if (
|
|
627
|
+
if (kind === "stream") {
|
|
542
628
|
return {
|
|
543
629
|
...facts,
|
|
544
630
|
type: "stream" as const,
|
|
@@ -559,8 +645,14 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
559
645
|
}
|
|
560
646
|
},
|
|
561
647
|
{
|
|
648
|
+
// A role EXISTS if something can serve it. Locally that means a
|
|
649
|
+
// binding; remotely it means the cognet declared it and the
|
|
650
|
+
// supervisor accepted the blueprint — an unfillable role would
|
|
651
|
+
// have failed the supervisor's own resolution before this process
|
|
652
|
+
// was ever spawned.
|
|
562
653
|
has: (role: string): boolean =>
|
|
563
|
-
opts.engines?.resolution.bound.some(entry => entry.role === role) ?? false
|
|
654
|
+
(opts.engines?.resolution.bound.some(entry => entry.role === role) ?? false)
|
|
655
|
+
|| Boolean(opts.remote && declaredRole(role)),
|
|
564
656
|
},
|
|
565
657
|
)
|
|
566
658
|
|
|
@@ -893,6 +985,16 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
893
985
|
return opts.engines
|
|
894
986
|
},
|
|
895
987
|
|
|
988
|
+
/**
|
|
989
|
+
* Policy + audit for in-process tools.
|
|
990
|
+
*
|
|
991
|
+
* On the public surface because the tool loader is above ring 0: it
|
|
992
|
+
* lives in @axon/core, which composes the runtime, while the policy it
|
|
993
|
+
* enforces and the log it writes to are the kernel's. Handing the pair
|
|
994
|
+
* out is narrower than handing out either the policy or the session.
|
|
995
|
+
*/
|
|
996
|
+
mediation,
|
|
997
|
+
|
|
896
998
|
/** Invoke on a stimulus arrival — invocation-mode cognets only; throws for continuous-mode. */
|
|
897
999
|
stream: streamWithContract,
|
|
898
1000
|
|
|
@@ -950,6 +1052,7 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
950
1052
|
* Receives the full re-normalized blueprint from the runtime.
|
|
951
1053
|
*/
|
|
952
1054
|
async update(next: AxonBlueprint) {
|
|
1055
|
+
live = next
|
|
953
1056
|
engine.update(next)
|
|
954
1057
|
opts.onUpdate?.(next)
|
|
955
1058
|
await cognet.update(next)
|
package/src/mediation.ts
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto"
|
|
2
|
+
import { evaluateRule } from "@arcforge/types"
|
|
3
|
+
import type { AxonEscalate, CapsulePolicy, PolicyRule } from "@arcforge/types"
|
|
4
|
+
import type { AxonSessionT } from "@arcforge/session"
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Mediation — the policy gate and audit trail for tools running IN this
|
|
8
|
+
* process.
|
|
9
|
+
*
|
|
10
|
+
* The counterpart to the capsule's guest-side `Mediator`, which cannot serve
|
|
11
|
+
* an in-process tool: it lives inside the subprocess and answers over a wire.
|
|
12
|
+
* Same decisions, same event vocabulary, no boundary.
|
|
13
|
+
*
|
|
14
|
+
* ── What this layer is, once the OS wall exists ─────────────────────────────
|
|
15
|
+
*
|
|
16
|
+
* In the capsule this WAS the security boundary. Once the whole agent runs
|
|
17
|
+
* inside a box, bwrap is the wall — a path outside the policy does not exist, a
|
|
18
|
+
* denied network has no socket — and this becomes the AUDIT and ESCALATION
|
|
19
|
+
* layer. That is a demotion, not a removal: the OS cannot say "ask the user
|
|
20
|
+
* about this one command", and a denial arriving as ENOENT teaches the model
|
|
21
|
+
* nothing. A typed refusal it can reason about is worth more than a syscall
|
|
22
|
+
* error it cannot.
|
|
23
|
+
*
|
|
24
|
+
* Deny-by-default is preserved exactly: a call with no matching rule is
|
|
25
|
+
* refused. A mediator must never grant capability by omission.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
type MediationOpts = {
|
|
29
|
+
policy: () => CapsulePolicy
|
|
30
|
+
session: AxonSessionT
|
|
31
|
+
/** The platform's decider. Absent = nobody to ask, which means deny. */
|
|
32
|
+
escalate?: AxonEscalate
|
|
33
|
+
/** Correlates each span to the run that caused it, when one is active. */
|
|
34
|
+
run?: () => { runId: string } | null
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** How long an unanswered escalation waits before failing closed. */
|
|
38
|
+
const ESCALATION_TIMEOUT_MS = 30_000
|
|
39
|
+
|
|
40
|
+
const POLICY_WILDCARD = "*"
|
|
41
|
+
|
|
42
|
+
export function Mediation(opts: MediationOpts) {
|
|
43
|
+
/**
|
|
44
|
+
* Resolve which rule governs a call.
|
|
45
|
+
*
|
|
46
|
+
* `process.spawn`/`process.run` are the two built-in verbs, resolved by
|
|
47
|
+
* exact name. Everything else is a tool, keyed by its namespace — an exact
|
|
48
|
+
* key wins, a `*` entry catches the rest, which is what a bare
|
|
49
|
+
* `tools: "escalate"` normalises to.
|
|
50
|
+
*/
|
|
51
|
+
function ruleFor(fn: string, owner: string): PolicyRule | undefined {
|
|
52
|
+
const policy = opts.policy()
|
|
53
|
+
if (fn === "process.spawn") return policy.process.spawn
|
|
54
|
+
if (fn === "process.run") return policy.process.run
|
|
55
|
+
return policy.tools?.[owner] ?? policy.tools?.[POLICY_WILDCARD]
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
async function check(fn: string, subject: string, args: unknown[], owner: string): Promise<boolean> {
|
|
59
|
+
const rule = ruleFor(fn, owner)
|
|
60
|
+
const verdict = evaluateRule(rule, subject, "agent")?.verdict ?? "deny"
|
|
61
|
+
|
|
62
|
+
if (verdict === "allow") return true
|
|
63
|
+
|
|
64
|
+
if (verdict === "deny") {
|
|
65
|
+
await opts.session.commit("process:policy:denied", {
|
|
66
|
+
id: randomUUID(), module: owner, fn, args, rule: String(rule),
|
|
67
|
+
}, span())
|
|
68
|
+
return false
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// Escalate — a human decision, and the one thing the OS wall cannot
|
|
72
|
+
// express. Fails CLOSED, and RECORDS the timeout: this layer's whole
|
|
73
|
+
// remaining job is escalation and audit, so an escalation that expired
|
|
74
|
+
// with nothing written is a hole in its only function.
|
|
75
|
+
const id = randomUUID()
|
|
76
|
+
await opts.session.commit("process:policy:escalation", {
|
|
77
|
+
id, module: owner, fn, args, rule: String(rule),
|
|
78
|
+
}, span())
|
|
79
|
+
|
|
80
|
+
const started = Date.now()
|
|
81
|
+
const allow = await decide(id, fn, args)
|
|
82
|
+
await opts.session.commit("process:policy:decision", {
|
|
83
|
+
id, allow, durationMs: Date.now() - started,
|
|
84
|
+
}, span())
|
|
85
|
+
return allow
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function decide(id: string, fn: string, args: unknown[]): Promise<boolean> {
|
|
89
|
+
// No decider attached (a script, a headless run) means nobody to ask,
|
|
90
|
+
// and an unanswered escalation must never read as permission.
|
|
91
|
+
if (!opts.escalate) return Promise.resolve(false)
|
|
92
|
+
|
|
93
|
+
return new Promise<boolean>(resolve => {
|
|
94
|
+
let settled = false
|
|
95
|
+
const settle = (allow: boolean) => {
|
|
96
|
+
if (settled) return
|
|
97
|
+
settled = true
|
|
98
|
+
clearTimeout(timer)
|
|
99
|
+
resolve(allow)
|
|
100
|
+
}
|
|
101
|
+
const timer = setTimeout(() => settle(false), ESCALATION_TIMEOUT_MS)
|
|
102
|
+
|
|
103
|
+
void Promise.resolve(opts.escalate!({ id, fn, args, rule: "escalate" }))
|
|
104
|
+
.then(allow => settle(allow === true))
|
|
105
|
+
// A decider that threw has not granted anything. Same posture
|
|
106
|
+
// as a timeout: closed.
|
|
107
|
+
.catch(() => settle(false))
|
|
108
|
+
})
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function span() {
|
|
112
|
+
const active = opts.run?.()
|
|
113
|
+
return active ? { runId: active.runId, spanId: Bun.randomUUIDv7() } : undefined
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
return {
|
|
117
|
+
check,
|
|
118
|
+
/**
|
|
119
|
+
* The span stream every surface reads.
|
|
120
|
+
*
|
|
121
|
+
* The event NAMES are unchanged from the capsule's — Fleet folds its
|
|
122
|
+
* flame graph and `procTree()` reads the process tree straight out of
|
|
123
|
+
* these. Renaming them while moving the machinery is how a flame graph
|
|
124
|
+
* silently stops pairing brackets.
|
|
125
|
+
*/
|
|
126
|
+
emit: {
|
|
127
|
+
start(input: { module: string; fn: string; args: unknown[] }) {
|
|
128
|
+
void opts.session.commit("process:fn:start", { commandId: "", ...input }, span())
|
|
129
|
+
},
|
|
130
|
+
complete(input: { module: string; fn: string; result: unknown; durationMs: number }) {
|
|
131
|
+
void opts.session.commit("process:fn:complete", { commandId: "", ...input }, span())
|
|
132
|
+
},
|
|
133
|
+
failed(input: { module: string; fn: string; error: unknown; durationMs: number }) {
|
|
134
|
+
void opts.session.commit("process:fn:failed", {
|
|
135
|
+
commandId: "",
|
|
136
|
+
module: input.module,
|
|
137
|
+
fn: input.fn,
|
|
138
|
+
error: input.error as never,
|
|
139
|
+
durationMs: input.durationMs,
|
|
140
|
+
}, span())
|
|
141
|
+
},
|
|
142
|
+
},
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export type MediationT = ReturnType<typeof Mediation>
|