@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 +12 -11
- package/src/Axon.ts +2 -0
- package/src/platform/inject.ts +27 -14
- package/src/runtime/handle.ts +52 -1
- package/src/runtime/source/context.ts +13 -4
- package/src/runtime/source/scripts.ts +102 -1
- package/src/tools/tools.ts +101 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/core",
|
|
3
|
-
"version": "2.0.
|
|
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.
|
|
18
|
-
"@arcforge/
|
|
19
|
-
"@arcforge/
|
|
20
|
-
"@arcforge/
|
|
21
|
-
"@arcforge/
|
|
22
|
-
"@arcforge/
|
|
23
|
-
"@arcforge/
|
|
24
|
-
"@arcforge/
|
|
25
|
-
"@arcforge/
|
|
26
|
-
"@arcforge/
|
|
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
|
package/src/platform/inject.ts
CHANGED
|
@@ -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
|
-
*
|
|
193
|
-
*
|
|
194
|
-
*
|
|
195
|
-
*
|
|
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 `
|
|
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.
|
|
202
|
-
*
|
|
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.
|
|
205
|
-
*
|
|
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.
|
|
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
|
}
|
package/src/runtime/handle.ts
CHANGED
|
@@ -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,
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
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
|
-
|
|
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 {
|
package/src/tools/tools.ts
CHANGED
|
@@ -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())
|
|
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
|
|