@arcforge/core 2.0.167 → 2.0.168

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/core",
3
- "version": "2.0.167",
3
+ "version": "2.0.168",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "exports": {
@@ -14,16 +14,17 @@
14
14
  "test:coverage": "bun test --coverage"
15
15
  },
16
16
  "dependencies": {
17
- "@arcforge/air": "2.0.167",
18
- "@arcforge/cognet": "2.0.167",
19
- "@arcforge/engines": "2.0.167",
20
- "@arcforge/err": "2.0.167",
21
- "@arcforge/kernel": "2.0.167",
22
- "@arcforge/session": "2.0.167",
23
- "@arcforge/types": "2.0.167",
24
- "@arcforge/cloud": "2.0.167",
25
- "@arcforge/capsule": "2.0.167",
26
- "@arcforge/vstr": "2.0.167",
17
+ "@arcforge/air": "2.0.168",
18
+ "@arcforge/capsule": "2.0.168",
19
+ "@arcforge/cloud": "2.0.168",
20
+ "@arcforge/cognet": "2.0.168",
21
+ "@arcforge/engines": "2.0.168",
22
+ "@arcforge/err": "2.0.168",
23
+ "@arcforge/kernel": "2.0.168",
24
+ "@arcforge/link": "2.0.168",
25
+ "@arcforge/session": "2.0.168",
26
+ "@arcforge/types": "2.0.168",
27
+ "@arcforge/vstr": "2.0.168",
27
28
  "crossws": "^0.3.5",
28
29
  "h3": "^1.13.0",
29
30
  "hookable": "^5.5.3",
package/src/Axon.ts CHANGED
@@ -215,6 +215,8 @@ export async function Axon(opts?: AxonOpts) {
215
215
  // A thunk: a hot reload rebuilds the set, and a captured map
216
216
  // would keep serving a tool the author deleted.
217
217
  loaded: () => tools.globals(),
218
+ namespaced: () => tools.namespaced(blueprint.tools),
219
+ reload: next => tools.reload(next),
218
220
  })
219
221
 
220
222
  // inject before [middleware, plugins, hooks]. The blueprint rides
@@ -189,20 +189,20 @@ let installedToolGlobals: string[] = []
189
189
  /**
190
190
  * Tool exports as globals — the agent's whole scope, in one heap.
191
191
  *
192
- * Everything exported from `src/tools/*.ts` (a module's included) lands here
193
- * under its OWN export name, unaugmented. Filenames group; they do not
194
- * namespace. `export function add()` is `add()`; `export const fs = {...}`
195
- * is `fs.read()`. That is the entire rule, and it is the same one the
196
- * generated `.agent/tool-globals.d.ts` declares.
192
+ * Placement follows ORIGIN, and `Tools.globals()` has already applied it:
193
+ * the agent's own `src/tools/*.ts` and the shared workspace's are flat
194
+ * (`export function add()` is `add()`), a MODULE's live under the module's
195
+ * name (`github.openPr()`). This installer only writes what it is handed.
197
196
  *
198
197
  * ONE INSTALLER, ONE SOURCE. These come from the loaded tool scope — the
199
- * same `scope.globals()` the model's own code executes against — so
198
+ * same `Tools.globals()` the model's own code executes against — so
200
199
  * script-land, prompts, routes, hooks and model-emitted code cannot see
201
- * different shapes of the same tool. There used to be a second installer
202
- * here projecting `axon.tools.<file>.<export>`, which double-wrapped a
200
+ * different shapes of the same tool. A second installer here once projected
201
+ * `axon.tools.<file>.<export>` off the flat map, which double-wrapped a
203
202
  * module exporting one object (`fs` became `{ fs: {...} }`) and silently
204
- * clobbered the correct binding. Both the projection and the surface it
205
- * read are gone.
203
+ * clobbered the correct binding. That projection is not coming back: the
204
+ * namespaced surface is built by `Tools.namespaced()` from the loaded set's
205
+ * own namespaces, never re-derived from the flat globals.
206
206
  *
207
207
  * The values are ALREADY MEDIATED — the loader wraps every export before it
208
208
  * reaches this scope — so policy, tracing and escalation are enforced by
@@ -222,13 +222,26 @@ function installToolGlobals(g: Record<string, unknown>, loaded: Record<string, u
222
222
  for (const [name, value] of Object.entries(loaded)) {
223
223
  // Tool vs tool is fatal: two files exporting the same name give the
224
224
  // author no way to say which they meant, and last-one-wins picks
225
- // silently. Tool vs HOST BUILTIN is not a collision — `@axon/fs`
226
- // exporting `fs` is the author's explicit declaration and the whole
227
- // point of installing it, so the tool takes the name. The builtin
228
- // stays reachable the correct way, by importing `node:fs`.
225
+ // silently.
229
226
  if (installedToolGlobals.includes(name)) {
230
227
  throw err("TOOL_GLOBAL_COLLISION", { context: { name } })
231
228
  }
229
+
230
+ // Tool vs anything that ALREADY owns the name — a host builtin like
231
+ // `fetch`, or the runtime's own `axon`/`args` — is not a collision to
232
+ // resolve, it is a name that is taken. The tool does not get it.
233
+ //
234
+ // Silently replacing `fetch` breaks every piece of agent-authored code
235
+ // around the tool that relies on the real one, and it fails nowhere
236
+ // near the cause. Overwriting `axon` or `args` is worse: it removes
237
+ // the runtime handle the rest of the scope is written against.
238
+ //
239
+ // Skipping is not a silent failure, because nothing is lost — the tool
240
+ // stays fully reachable through `axon.tools.<namespace>.<fn>()`, which
241
+ // is exactly the case that surface exists for. The flat global is a
242
+ // convenience; the namespaced one is the guarantee.
243
+ if (name in g) continue
244
+
232
245
  g[name] = value
233
246
  installedToolGlobals.push(name)
234
247
  }
@@ -1,6 +1,6 @@
1
1
  import { err } from "@arcforge/err"
2
2
  import type { AxonCloudClient } from "@arcforge/cloud"
3
- import { foldChunks, type AxonBlueprint, type AxonRequestInput, type AxonResult } from "@arcforge/types"
3
+ import { foldChunks, type AxonBlueprint, type AxonRequestInput, type AxonResult, type AxonToolNamespaces } from "@arcforge/types"
4
4
  import { AxonHooksT, Inject } from "../platform"
5
5
  import type { AxonBusT } from "../platform"
6
6
  import type { AxonOutputEvent } from "@arcforge/types"
@@ -26,6 +26,23 @@ type AxonHandleOpts = {
26
26
  * captured map would keep serving the tool the author just deleted.
27
27
  */
28
28
  loaded?: () => Record<string, unknown>
29
+ /**
30
+ * The same tools, addressed by namespace — backs `axon.tools.*`.
31
+ *
32
+ * A thunk for the same reason `loaded` is one, and built from the loaded
33
+ * set's own namespaces rather than re-derived from the flat globals: that
34
+ * re-derivation is what once turned a module exporting one object into
35
+ * `{ fs: { fs: {...} } }` (see inject.ts).
36
+ */
37
+ namespaced?: () => AxonToolNamespaces
38
+ /**
39
+ * Rebuild the loaded tool set for a hot reload.
40
+ *
41
+ * The thunks above serve whatever is loaded NOW; this is what makes "now"
42
+ * change. Without it `update()` re-projected both surfaces off a set that
43
+ * could never differ from the one Axon() installed at boot.
44
+ */
45
+ reload?: (tools: AxonBlueprint["tools"]) => Promise<void>
29
46
  }
30
47
 
31
48
  /**
@@ -116,6 +133,7 @@ export function AxonHandle(opts: AxonHandleOpts) {
116
133
  const scripts = Scripts({
117
134
  blueprint: opts.blueprint,
118
135
  inject: opts.inject,
136
+ session: session,
119
137
  })
120
138
 
121
139
 
@@ -128,6 +146,33 @@ export function AxonHandle(opts: AxonHandleOpts) {
128
146
 
129
147
  prompt: prompt.render,
130
148
 
149
+ /**
150
+ * `axon.tools.<namespace>.<fn>()` — the explicit tool surface.
151
+ *
152
+ * An ESCAPE HATCH, not the primary path. Model-emitted code and the
153
+ * author's own code call tools flat (`add(1, 2)`), exactly as the
154
+ * model's <scope> block and the generated `.agent/tool-globals.d.ts`
155
+ * declare them. This surface is for the cases a bare name cannot
156
+ * serve:
157
+ *
158
+ * - the name is already taken. A tool exporting `fetch` never
159
+ * replaces the host builtin, so this is where it lives.
160
+ * - the caller wants to be explicit about WHICH tool it means —
161
+ * host-side code, a route, a hook, a prompt's `<script setup>`.
162
+ *
163
+ * A GETTER over a thunk, never a snapshot: a hot reload replaces the
164
+ * loaded set, and a map projected once at construction meant a script
165
+ * calling a newly added tool got `undefined` while the model could
166
+ * already call it, and a deleted tool stayed callable until restart.
167
+ *
168
+ * The functions here are the SAME mediated ones the globals expose —
169
+ * one loader, one wrapper — so policy, tracing and escalation cannot
170
+ * drift between the two surfaces. A tool declared in the blueprint but
171
+ * never loaded is absent here, so calling it throws rather than
172
+ * silently doing nothing.
173
+ */
174
+ get tools() { return opts.namespaced?.() ?? {} },
175
+
131
176
  /**
132
177
  * Installed modules and their validated options.
133
178
  *
@@ -251,6 +296,12 @@ export function AxonHandle(opts: AxonHandleOpts) {
251
296
 
252
297
  async update(blueprint: AxonBlueprint) {
253
298
  await kernel.update(blueprint)
299
+ // Rebuild the loaded set FIRST. Both surfaces below read through
300
+ // thunks, so re-projecting them off a scope that was still the
301
+ // boot-time one left a deleted tool callable and an added one
302
+ // unreachable until restart — the set was installed once by Axon()
303
+ // and nothing rebuilt it.
304
+ await opts.reload?.(blueprint.tools)
254
305
  // Re-project the tool map from the blueprint that just went live,
255
306
  // so this handle and the capsule always agree on what exists.
256
307
  // …and re-bind the host-side tool globals off the new map, so a
@@ -32,10 +32,19 @@
32
32
  * `process.run()` and `process.spawn()` are there too, exactly as they are
33
33
  * in a script or a tool.
34
34
  *
35
- * It used to be a minimal `{ env }` shim here, which was correct only while
36
- * templates rendered outside the agent's process and could not be trusted
37
- * with the real one. In one heap that reasoning is gone, and the shim was
38
- * the last thing making a prompt's scope differ from every other context's.
35
+ * It used to be a minimal `{ env }` shim here, defended as a confidentiality
36
+ * boundary: a template's output reaches the model, so it should not see the
37
+ * shell that launched the TUI. That framing is wrong, and the shim was the
38
+ * last thing making a prompt's scope differ from every other context's.
39
+ *
40
+ * In-process is IN SCOPE. Prompt rendering happens inside the agent, in the
41
+ * same heap as the cognet, the scripts and the tools — none of which are
42
+ * narrowed. The user put the `.env` on this agent deliberately, and the
43
+ * declared vars are overlaid onto the ambient environment rather than
44
+ * replacing it precisely so an agent keeps PATH, HOME and the provider vars
45
+ * the runtime resolved. Anything on `process.env` here is something the agent
46
+ * is meant to have; the wall that separates agents from each other is the
47
+ * OS's, not a shim in one rendering context.
39
48
  *
40
49
  * The rest is read lazily off globalThis: the runtime handle is wired
41
50
  * after the constructs that render templates exist, so it can't be captured
@@ -1,11 +1,22 @@
1
1
  import { existsSync } from "node:fs"
2
2
  import { err } from "@arcforge/err"
3
3
  import { AxonBlueprint } from "@arcforge/types"
4
+ import type { AxonSessionT } from "@arcforge/session"
4
5
  import type { Inject } from "../../platform"
5
6
 
6
7
  type ScriptsOpts = {
7
8
  blueprint: AxonBlueprint
8
9
  inject: ReturnType<typeof Inject>
10
+ /**
11
+ * The durable record, so a script run is a SPAN rather than a silent gap.
12
+ *
13
+ * Without it a script was invisible: it drove the agent, its wakes landed
14
+ * in the log, and nothing said which script had caused them or how long
15
+ * the whole job took. The bracket is also what gives a flame graph its
16
+ * interior — everything the script causes nests inside it by containment,
17
+ * so one opaque bar becomes the tree of what actually happened.
18
+ */
19
+ session: AxonSessionT
9
20
  }
10
21
 
11
22
  /**
@@ -20,6 +31,46 @@ type ScriptsOpts = {
20
31
  * withArgs() so concurrent script invocations never race each other's
21
32
  * globalThis.args.
22
33
  */
34
+ /**
35
+ * Capture `console.log`/`console.error` for the duration of a script.
36
+ *
37
+ * Scripts talk through console — that is their existing contract, and every
38
+ * script in the registry is written to it. Captured HERE rather than relying
39
+ * on the capsule's redirect, because the two paths differ: the capsule
40
+ * captures only while a command is executing (`execution.current !== null`),
41
+ * which is true when the TUI runs a script through `link.run` and false for a
42
+ * direct `axon.scripts.request()`. Measured both ways — the direct path wrote
43
+ * to real stdout and emitted nothing at all.
44
+ *
45
+ * Doing it at the one place a script actually starts means every caller gets
46
+ * the same behaviour, rather than the output depending on which door was used.
47
+ *
48
+ * Writes still reach the real stream. A script's logs are its own output and a
49
+ * terminal running one headlessly should still see them; this ADDS the durable
50
+ * record rather than diverting it.
51
+ */
52
+ function captureConsole(onLine: (line: { level: "log" | "error"; content: string }) => void): () => void {
53
+ const realLog = console.log
54
+ const realError = console.error
55
+
56
+ const format = (args: unknown[]): string =>
57
+ args.map(arg => (typeof arg === "string" ? arg : JSON.stringify(arg))).join(" ")
58
+
59
+ console.log = (...args: unknown[]) => {
60
+ onLine({ level: "log", content: format(args) })
61
+ realLog(...args)
62
+ }
63
+ console.error = (...args: unknown[]) => {
64
+ onLine({ level: "error", content: format(args) })
65
+ realError(...args)
66
+ }
67
+
68
+ return () => {
69
+ console.log = realLog
70
+ console.error = realError
71
+ }
72
+ }
73
+
23
74
  export function Scripts(opts: ScriptsOpts) {
24
75
  function find(name: string) {
25
76
  const entry = opts.blueprint.scripts.find(s => s.name === name)
@@ -40,7 +91,57 @@ export function Scripts(opts: ScriptsOpts) {
40
91
  // `args` read resolves through.
41
92
  const runId = crypto.randomUUID()
42
93
  const specifier = `${entry.filePath}?run=${runId}`
43
- return opts.inject.withArgs(runId, args, () => import(specifier))
94
+
95
+ /**
96
+ * The span opens BEFORE the import and closes however it settles.
97
+ *
98
+ * Opened first, deliberately: a script that throws on its first line
99
+ * still ran, and a bracket that only opens on success would leave the
100
+ * failure outside any span — unpaired for anything counting depth, and
101
+ * invisible to a reader asking what the user started.
102
+ *
103
+ * `id` rides every member so a surface can correlate the logs and the
104
+ * terminal state back to this one invocation, the same way `commandId`
105
+ * ties capsule work to its block.
106
+ */
107
+ const started = Date.now()
108
+ await opts.session.commit("axon:script:start", { id: runId, name, args })
109
+
110
+ const release = captureConsole(line => {
111
+ // Fire-and-forget: a log line must not make the script await the
112
+ // durable write, and ordering is preserved by the session's own
113
+ // serialized writer rather than by this call site.
114
+ void opts.session.commit("axon:script:log", { id: runId, level: line.level, content: line.content })
115
+ })
116
+
117
+ try {
118
+ const result = await opts.inject.withArgs(runId, args, () => import(specifier))
119
+ await opts.session.commit("axon:script:complete", { id: runId, durationMs: Date.now() - started })
120
+ return result
121
+ } catch (cause) {
122
+ const failure = err(cause)
123
+ /**
124
+ * Interruption is a SETTLED OUTCOME, not a failure — a script the
125
+ * user stopped did what it was told, and rendering it red would
126
+ * teach them that stopping something is an error.
127
+ *
128
+ * Read off the ORIGINAL cause, not the wrapped error: `err()`
129
+ * returns its own AxonError, so `failure.name` is the wrapper's
130
+ * and an abort was recorded as `:failed`. Checked here rather than
131
+ * inside err() because only this call site knows that a cancelled
132
+ * script is a normal ending.
133
+ */
134
+ const interrupted = cause instanceof Error && cause.name === "AbortError"
135
+ await opts.session.commit(
136
+ interrupted ? "axon:script:interrupted" : "axon:script:failed",
137
+ interrupted
138
+ ? { id: runId, durationMs: Date.now() - started }
139
+ : { id: runId, error: failure, durationMs: Date.now() - started },
140
+ )
141
+ throw failure
142
+ } finally {
143
+ release()
144
+ }
44
145
  }
45
146
 
46
147
  return {
@@ -1,4 +1,8 @@
1
- import type { AxonTool } from "@arcforge/types"
1
+ import type { AxonTool, AxonToolNamespaces } from "@arcforge/types"
2
+ import { err } from "@arcforge/err"
3
+
4
+ /** One mediated tool export. Every call crosses policy, so all of them are async. */
5
+ type ToolFn = (...args: never[]) => Promise<unknown>
2
6
  import { isLoadable } from "@arcforge/kernel"
3
7
  import { loadTool, type LoadedTool } from "./load"
4
8
  import type { MediateOpts } from "./mediate"
@@ -32,6 +36,8 @@ type ToolsOpts = {
32
36
  */
33
37
  export function Tools(opts: ToolsOpts) {
34
38
  const loaded = new Map<string, LoadedTool>()
39
+ /** Origin per loaded namespace — decides flat vs namespaced placement. */
40
+ const origins = new Map<string, AxonTool["origin"]>()
35
41
 
36
42
  return {
37
43
  /**
@@ -50,9 +56,38 @@ export function Tools(opts: ToolsOpts) {
50
56
  async install(tools: AxonTool[]): Promise<void> {
51
57
  for (const tool of tools.filter(isLoadable)) {
52
58
  loaded.set(tool.name, await loadTool(tool, opts.mediation))
59
+ origins.set(tool.name, tool.origin)
53
60
  }
54
61
  },
55
62
 
63
+ /**
64
+ * Rebuild the whole set for a hot reload.
65
+ *
66
+ * Replaces rather than merges, so a tool the author DELETED actually
67
+ * goes away. Without this the set was built once at boot and never
68
+ * again: `install()` was called from Axon() alone, so after an
69
+ * `update()` the handle re-projected `axon.tools` and reinstalled the
70
+ * globals off a map that could no longer change. A deleted tool stayed
71
+ * callable until restart and an added one was never reachable.
72
+ *
73
+ * Loads into a SCRATCH map before touching the live one — a reload
74
+ * whose new set fails to load leaves the previous scope intact rather
75
+ * than a half-installed one, the same reason install() throws on the
76
+ * first failure instead of continuing.
77
+ */
78
+ async reload(tools: AxonTool[]): Promise<void> {
79
+ const next = new Map<string, LoadedTool>()
80
+ const nextOrigins = new Map<string, AxonTool["origin"]>()
81
+ for (const tool of tools.filter(isLoadable)) {
82
+ next.set(tool.name, await loadTool(tool, opts.mediation))
83
+ nextOrigins.set(tool.name, tool.origin)
84
+ }
85
+ loaded.clear()
86
+ origins.clear()
87
+ for (const [name, tool] of next) loaded.set(name, tool)
88
+ for (const [name, origin] of nextOrigins) origins.set(name, origin)
89
+ },
90
+
56
91
  /** Drop one namespace — a hot reload removing a tool the author deleted. */
57
92
  remove(namespace: string): void {
58
93
  loaded.delete(namespace)
@@ -79,9 +114,73 @@ export function Tools(opts: ToolsOpts) {
79
114
  */
80
115
  globals(): Record<string, unknown> {
81
116
  const globals: Record<string, unknown> = {}
82
- for (const tool of loaded.values()) Object.assign(globals, tool.values)
117
+ for (const tool of loaded.values()) {
118
+ // Placement follows ORIGIN. The agent's own src/tools (and the
119
+ // shared workspace's) are the author's vocabulary and go flat:
120
+ // they wrote `export function add()`, so `add()` works. A
121
+ // MODULE's tools are someone else's vocabulary installed into
122
+ // the agent, and flattening them lets any module claim a bare
123
+ // name in the author's scope — `github.openPr()` says whose it
124
+ // is. Same rule the generated .d.ts and the model's <scope>
125
+ // describe (Axon.ts, inject.ts).
126
+ if (origins.get(tool.namespace) === "module") globals[tool.namespace] = tool.values
127
+ else Object.assign(globals, tool.values)
128
+ }
83
129
  return globals
84
130
  },
131
+
132
+ /**
133
+ * The NAMESPACED view — `axon.tools.<namespace>.<fn>()`.
134
+ *
135
+ * The escape hatch, deliberately not the primary path. Model-emitted
136
+ * code calls tools flat, as the <scope> block and the .d.ts describe
137
+ * them; this exists for the cases where a bare name is unavailable or
138
+ * ambiguous, and it is always unambiguous:
139
+ *
140
+ * - a tool named after a host builtin. `installToolGlobals` refuses
141
+ * to clobber `fetch`, so the tool is only reachable here.
142
+ * - host-side code (a route, a hook, `<script setup>`) that wants to
143
+ * name the tool it means rather than rely on the flat scope.
144
+ *
145
+ * Built fresh from the live map on every call, never captured: a hot
146
+ * reload replaces the set, and a snapshot would keep serving a deleted
147
+ * tool. The values are the SAME mediated functions the globals expose —
148
+ * one loader, one wrapper — so policy, tracing and escalation cannot
149
+ * drift between the two surfaces.
150
+ */
151
+ namespaced(declared: AxonTool[] = []): AxonToolNamespaces {
152
+ const tools: Record<string, Record<string, ToolFn>> = {}
153
+
154
+ // DECLARED first, so a namespace the blueprint promises is present
155
+ // even when nothing loaded it — `isLoadable` is false for a tool
156
+ // with neither source nor entry path, so install() skips it while
157
+ // the model's <scope> block still lists it.
158
+ //
159
+ // Present, but every member THROWS. Absent, the call dies as
160
+ // "cannot read property of undefined" pointing at the caller;
161
+ // silently no-op'd, it would report success for work that never
162
+ // happened. Neither says the true thing, which is that the agent
163
+ // was promised a function nothing supplies.
164
+ for (const tool of declared) {
165
+ if (loaded.has(tool.name)) continue
166
+ // ASYNC, like every mediated tool call. A synchronous throw here
167
+ // would reach a caller as a raw exception where the same call
168
+ // on a loaded tool rejects, so `await tool.fn()` in a try/catch
169
+ // would behave differently depending on whether the tool exists.
170
+ tools[tool.name] = Object.fromEntries(tool.fns.map(fn => [fn.name, async () => {
171
+ throw err("CAPSULE_TOOL_FAILED", {
172
+ detail: `${tool.name}.${fn.name} is not defined — "${tool.name}" is declared in blueprint.tools but was never loaded (no source, no entry path)`,
173
+ context: { namespace: tool.name, fn: fn.name },
174
+ })
175
+ }]))
176
+ }
177
+
178
+ // Every value here came from `mediate()`, which returns an async
179
+ // wrapper — the cast states what the loader already guarantees
180
+ // rather than widening the public contract to `unknown`.
181
+ for (const tool of loaded.values()) tools[tool.namespace] = tool.values as Record<string, ToolFn>
182
+ return tools as AxonToolNamespaces
183
+ },
85
184
  }
86
185
  }
87
186