@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 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.163",
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.163",
19
- "@arcforge/engines": "2.0.163",
20
- "@arcforge/err": "2.0.163",
21
- "@arcforge/session": "2.0.163",
22
- "@arcforge/types": "2.0.163",
23
- "@arclabs/cloud": "2.0.163",
24
- "@axon/capsule": "2.0.163"
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 CapsulePolicy,
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, CapsulePolicy, PolicyRule } from "@arcforge/types"
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: () => CapsulePolicy
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, keyed by its namespace — an exact
48
- * key wins, a `*` entry catches the rest, which is what a bare
49
- * `tools: "escalate"` normalises to.
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, owner: string): PolicyRule | undefined {
59
+ function ruleFor(fn: string): EffectiveRule | undefined {
52
60
  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]
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, owner)
60
- const verdict = evaluateRule(rule, subject, "agent")?.verdict ?? "deny"
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
- * Flat members are then deduped by CALLABLE NAME, which is a different
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 flat, and everything downstream silently picks a winner:
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
- if (!module.flat) {
75
- modules.push(module)
76
- continue
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 })