@arcforge/kernel 2.0.154 → 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcforge/kernel",
3
- "version": "2.0.154",
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.154",
19
- "@arcforge/engines": "2.0.154",
20
- "@arcforge/err": "2.0.154",
21
- "@arcforge/session": "2.0.154",
22
- "@arcforge/types": "2.0.154",
23
- "@arclabs/cloud": "2.0.154",
24
- "@axon/capsule": "2.0.154"
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, resolveIsolation } from "@arcforge/types"
6
- import type { AxonBlueprint, AxonEventMap, CapsulePolicy, PolicyRule } from "@arcforge/types"
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 own defaults are deny-by-default — correct for a sandbox
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
- * Scoped to loadable tools for the same reason toCapsuleTools() is: a rule
52
- * naming a namespace the capsule never installs grants nothing and only
53
- * makes the policy surface read as larger than it is.
54
- */
55
- function defaultPolicy(blueprint: AxonBlueprint): CapsulePartialConfig["policy"] {
56
- const tools: Record<string, true> = {}
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
- * ── The bare cases collapse here ────────────────────────────────────────────
121
- *
122
- * `true`/`false`/`"escalate"` carry no patterns, so there is nothing to defer:
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
- * One capability's rule under both layers.
166
- *
167
- * A bare profile verdict wins outright — it cannot be narrowed further by a
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 pairRule(profile: PolicyRule | undefined, agent: PolicyRule | undefined): PolicyRule {
172
- if (profile === false) return false
173
- if (profile === "escalate" && agent !== false) return "escalate"
174
- if (profile === undefined) return agent ?? true
175
- if (profile === true) return agent ?? true
176
- // Profile is glob-shaped: the agent narrows within it, and the pair is
177
- // evaluated per call. With no agent rule, the profile IS the rule.
178
- return agent ?? profile
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 === "capsule:cwd") liveCwd = event.cwd
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("capsule:attach", { capsuleId: currentId, cwd: liveCwd ?? opts.cwd })
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("capsule:detach", { capsuleId, reason })
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 || !opts.engines) return null
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
- if (!bound) {
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
- const facts = {
522
- get context() { return bound.capability.context },
523
- get modalities() { return { in: bound.capability.in, out: bound.capability.out } },
524
- get slots() { return bound.slots },
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 (bound.requirement.type === "transform") {
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 (bound.requirement.type === "stream") {
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)
@@ -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>