@arcforge/core 2.0.166
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 +31 -0
- package/package.json +37 -0
- package/src/Axon.ts +260 -0
- package/src/cognet/cognet.ts +318 -0
- package/src/cognet/index.ts +4 -0
- package/src/index.ts +11 -0
- package/src/modules/context.ts +90 -0
- package/src/modules/index.ts +6 -0
- package/src/modules/load.ts +119 -0
- package/src/modules/modules.ts +87 -0
- package/src/modules/setup.ts +91 -0
- package/src/platform/blueprint.ts +201 -0
- package/src/platform/boot.ts +160 -0
- package/src/platform/bus.ts +207 -0
- package/src/platform/hooks.ts +30 -0
- package/src/platform/index.ts +18 -0
- package/src/platform/inject.ts +236 -0
- package/src/runtime/handle.ts +283 -0
- package/src/runtime/index.ts +2 -0
- package/src/runtime/inference.ts +221 -0
- package/src/runtime/runtime.ts +207 -0
- package/src/runtime/server/connect-auth.ts +123 -0
- package/src/runtime/server/endpoints.ts +257 -0
- package/src/runtime/server/h3.ts +33 -0
- package/src/runtime/server/index.ts +8 -0
- package/src/runtime/server/middleware.ts +59 -0
- package/src/runtime/server/plugins.ts +23 -0
- package/src/runtime/server/routes.ts +33 -0
- package/src/runtime/server/server.ts +138 -0
- package/src/runtime/server/session-view.ts +100 -0
- package/src/runtime/server/sse.ts +45 -0
- package/src/runtime/server/streams.ts +186 -0
- package/src/runtime/source/context.ts +67 -0
- package/src/runtime/source/render.ts +90 -0
- package/src/runtime/source/scripts.ts +55 -0
- package/src/tools/index.ts +11 -0
- package/src/tools/load.ts +119 -0
- package/src/tools/mediate.ts +92 -0
- package/src/tools/tools.ts +88 -0
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
import { err } from "@arcforge/err"
|
|
2
|
+
import type { AxonCloudClient } from "@arcforge/cloud"
|
|
3
|
+
import { foldChunks, type AxonBlueprint, type AxonRequestInput, type AxonResult } from "@arcforge/types"
|
|
4
|
+
import { AxonHooksT, Inject } from "../platform"
|
|
5
|
+
import type { AxonBusT } from "../platform"
|
|
6
|
+
import type { AxonOutputEvent } from "@arcforge/types"
|
|
7
|
+
import { Prompt } from "./source/render"
|
|
8
|
+
import { Scripts } from "./source/scripts"
|
|
9
|
+
import { AxonKernelT } from "@arcforge/kernel"
|
|
10
|
+
import { Output } from "@arcforge/air/output"
|
|
11
|
+
import type { AxonSessionT } from "@arcforge/session"
|
|
12
|
+
|
|
13
|
+
type AxonHandleOpts = {
|
|
14
|
+
cloud: AxonCloudClient
|
|
15
|
+
hooks: AxonHooksT
|
|
16
|
+
blueprint: AxonBlueprint
|
|
17
|
+
kernel: AxonKernelT
|
|
18
|
+
session: AxonSessionT
|
|
19
|
+
inject: ReturnType<typeof Inject>
|
|
20
|
+
/** Backs `on()` — every committed entry is announced here. */
|
|
21
|
+
bus: AxonBusT
|
|
22
|
+
/**
|
|
23
|
+
* The tools loaded in THIS process, when the agent runs in its own box.
|
|
24
|
+
*
|
|
25
|
+
* A thunk, not a value: a hot reload rebuilds the loaded set, and a
|
|
26
|
+
* captured map would keep serving the tool the author just deleted.
|
|
27
|
+
*/
|
|
28
|
+
loaded?: () => Record<string, unknown>
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Invoke — the handle's two invocation verbs.
|
|
33
|
+
*
|
|
34
|
+
* Owns the whole translation between the public shape and the kernel's:
|
|
35
|
+
* the public surface takes a prompt (or a bare string), the kernel takes
|
|
36
|
+
* content, and `request` additionally folds the wake's entries into the
|
|
37
|
+
* single `text` a caller expects. Split out so AxonHandle below stays pure
|
|
38
|
+
* composition — it wires organs together and exposes a shape, it does not
|
|
39
|
+
* reshape payloads.
|
|
40
|
+
*/
|
|
41
|
+
function Invoke(opts: { kernel: AxonKernelT }) {
|
|
42
|
+
const { kernel } = opts
|
|
43
|
+
|
|
44
|
+
// The typechecker behind `output`. Built once and reused: it holds a
|
|
45
|
+
// warm TypeScript program, so the per-request cost is an incremental
|
|
46
|
+
// check rather than a compiler spin-up. Construction is wiring only —
|
|
47
|
+
// no program is created until the first output type is compiled.
|
|
48
|
+
const output = Output({ scope: () => kernel.scope() })
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* The public surface takes a prompt; the kernel takes content.
|
|
52
|
+
*
|
|
53
|
+
* An `output` type is compiled HERE, synchronously, before anything is
|
|
54
|
+
* scheduled — so an invalid type throws at the caller's own line with a
|
|
55
|
+
* real TypeScript message, rather than costing a model call and
|
|
56
|
+
* surfacing as a confusing repair loop.
|
|
57
|
+
*/
|
|
58
|
+
function toKernelInput(input: AxonRequestInput | string) {
|
|
59
|
+
const normalized = typeof input === "string" ? { prompt: input } : input
|
|
60
|
+
// The surface travels with the message whether or not a shape was
|
|
61
|
+
// asked for — it is the reply's address, not part of the contract.
|
|
62
|
+
const channel = normalized.channel === undefined ? {} : { channel: normalized.channel }
|
|
63
|
+
if (!normalized.output) return { content: normalized.prompt, ...channel }
|
|
64
|
+
|
|
65
|
+
const compiled = output.compile(normalized.output)
|
|
66
|
+
return {
|
|
67
|
+
content: normalized.prompt,
|
|
68
|
+
...channel,
|
|
69
|
+
output: { declaration: compiled.declaration, check: compiled.check },
|
|
70
|
+
...(normalized.retries === undefined ? {} : { retries: normalized.retries }),
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
return {
|
|
75
|
+
/**
|
|
76
|
+
* Run to completion. `text` is every text output the wake produced,
|
|
77
|
+
* chunk-folded and joined — the one-line answer a caller usually
|
|
78
|
+
* wants — with the full entry list alongside it for anyone who needs
|
|
79
|
+
* the causal detail.
|
|
80
|
+
*/
|
|
81
|
+
async request(input: AxonRequestInput | string): Promise<AxonResult> {
|
|
82
|
+
const { entries } = await kernel.request(toKernelInput(input))
|
|
83
|
+
const text = foldChunks(entries)
|
|
84
|
+
.filter(e => e.type === "cognet:output:text")
|
|
85
|
+
.map(e => (e.data as { content: string }).content)
|
|
86
|
+
.join("\n")
|
|
87
|
+
return { text, entries }
|
|
88
|
+
},
|
|
89
|
+
|
|
90
|
+
/** The same invocation, as a live entry stream plus an interrupt handle. */
|
|
91
|
+
stream(input: AxonRequestInput | string) {
|
|
92
|
+
return kernel.stream(toKernelInput(input))
|
|
93
|
+
},
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Composes the runtime-facing handle — the `axon` global agent code sees.
|
|
99
|
+
*
|
|
100
|
+
* Pure composition: builds each organ (prompt, scripts, tools, invoke) and
|
|
101
|
+
* exposes one coherent shape over them. Anything with logic of its own lives
|
|
102
|
+
* in the organ that owns it, never here.
|
|
103
|
+
*
|
|
104
|
+
* Must satisfy the AxonHandle contract in @arcforge/types — that contract is
|
|
105
|
+
* the public API surface; anything extra here is core-internal. No thread
|
|
106
|
+
* concept: one Axon() instance is always exactly one continuous stream.
|
|
107
|
+
*/
|
|
108
|
+
export function AxonHandle(opts: AxonHandleOpts) {
|
|
109
|
+
const kernel = opts.kernel
|
|
110
|
+
const session = opts.session
|
|
111
|
+
|
|
112
|
+
const prompt = Prompt({
|
|
113
|
+
blueprint: opts.blueprint,
|
|
114
|
+
})
|
|
115
|
+
|
|
116
|
+
const scripts = Scripts({
|
|
117
|
+
blueprint: opts.blueprint,
|
|
118
|
+
inject: opts.inject,
|
|
119
|
+
})
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
const invoke = Invoke({ kernel })
|
|
123
|
+
|
|
124
|
+
const handle = {
|
|
125
|
+
// Getter, not a snapshot: a reload can unload the brain at any time,
|
|
126
|
+
// and a consumer holding the handle must see the current answer.
|
|
127
|
+
get ready() { return kernel.ready },
|
|
128
|
+
|
|
129
|
+
prompt: prompt.render,
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Installed modules and their validated options.
|
|
133
|
+
*
|
|
134
|
+
* Reads `opts.blueprint` rather than a captured snapshot for the
|
|
135
|
+
* same reason `ready` is a getter: a hot reload replaces the
|
|
136
|
+
* blueprint, and a module plugin re-running after one must see the
|
|
137
|
+
* options the agent has NOW, not the ones it booted with.
|
|
138
|
+
*/
|
|
139
|
+
modules: {
|
|
140
|
+
list(): string[] {
|
|
141
|
+
return opts.blueprint.modules.map(module => module.name)
|
|
142
|
+
},
|
|
143
|
+
|
|
144
|
+
all<T extends Record<string, unknown> = Record<string, unknown>>(name: string): T[] {
|
|
145
|
+
const instances = opts.blueprint.modules.filter(entry => entry.name === name)
|
|
146
|
+
if (instances.length === 0) {
|
|
147
|
+
throw err("MODULE_NOT_INSTALLED", {
|
|
148
|
+
detail: `no module named "${name}" is installed on this agent`,
|
|
149
|
+
context: { name, installed: opts.blueprint.modules.map(m => m.name) },
|
|
150
|
+
})
|
|
151
|
+
}
|
|
152
|
+
return instances.map(module => (module.options ?? {}) as T)
|
|
153
|
+
},
|
|
154
|
+
|
|
155
|
+
options<T extends Record<string, unknown> = Record<string, unknown>>(name: string): T {
|
|
156
|
+
const module = opts.blueprint.modules.find(entry => entry.name === name)
|
|
157
|
+
if (!module) {
|
|
158
|
+
// Loud, not empty. A plugin asking for a module that is
|
|
159
|
+
// not installed is asking under the wrong name, and
|
|
160
|
+
// returning {} would hand it every default silently —
|
|
161
|
+
// a sensor that opens the wrong device and says nothing.
|
|
162
|
+
throw err("MODULE_NOT_INSTALLED", {
|
|
163
|
+
detail: `no module named "${name}" is installed on this agent`,
|
|
164
|
+
context: { name, installed: opts.blueprint.modules.map(m => m.name) },
|
|
165
|
+
})
|
|
166
|
+
}
|
|
167
|
+
return (module.options ?? {}) as T
|
|
168
|
+
},
|
|
169
|
+
},
|
|
170
|
+
|
|
171
|
+
prompts: {
|
|
172
|
+
list: prompt.list,
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* Render a prompt this agent does not declare, from an entry the
|
|
176
|
+
* host scanned elsewhere — a cached registry prompt.
|
|
177
|
+
*
|
|
178
|
+
* The scope is still this agent's (`axon`, its own env), which is
|
|
179
|
+
* why this has to run here rather than host-side. Sits under
|
|
180
|
+
* `prompts` beside `list` rather than alongside the bare
|
|
181
|
+
* `prompt(name)` verb: that one is the agent's own library, this
|
|
182
|
+
* one takes an entry the caller already resolved.
|
|
183
|
+
*/
|
|
184
|
+
renderEntry: prompt.renderEntry,
|
|
185
|
+
},
|
|
186
|
+
|
|
187
|
+
request: invoke.request,
|
|
188
|
+
|
|
189
|
+
stream: invoke.stream,
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* The sense door. Delegates straight to the session's ingest, which
|
|
193
|
+
* commits the stimulus and queues it for the next wake — the buffer's
|
|
194
|
+
* one drainer is the scheduler, so a stimulus is delivered exactly
|
|
195
|
+
* once and then gone.
|
|
196
|
+
*
|
|
197
|
+
* This is the "future AxonHandle surface" session.stimuli.ingest was
|
|
198
|
+
* written for; the machinery predates the verb.
|
|
199
|
+
*/
|
|
200
|
+
stim: session.stimuli.ingest,
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Observe what the brain emits — the counterpart to stim().
|
|
204
|
+
*
|
|
205
|
+
* Subscribes to the BUS rather than to the commit pipeline. Delivery
|
|
206
|
+
* and durability are separate questions: an output that is one day
|
|
207
|
+
* transient (a 24kHz speech stream is the same firehose problem as a
|
|
208
|
+
* microphone, in reverse) must still reach the body, and wiring this
|
|
209
|
+
* to the commit would silently couple the two.
|
|
210
|
+
*/
|
|
211
|
+
on<K extends keyof AxonOutputEvent>(
|
|
212
|
+
type: K,
|
|
213
|
+
handler: (data: AxonOutputEvent[K]) => void | Promise<void>,
|
|
214
|
+
): () => void {
|
|
215
|
+
// onAny + filter rather than on(type). Entries are FORWARDED onto
|
|
216
|
+
// the bus (bus.forward) rather than declared in AxonEventMap, so
|
|
217
|
+
// there is no typed channel to subscribe to — the same reason the
|
|
218
|
+
// WebSocket relay reads them this way. The type parameter is the
|
|
219
|
+
// contract with the caller; the filter is what enforces it.
|
|
220
|
+
return opts.bus.onAny(async (event: string, payload: unknown) => {
|
|
221
|
+
if (event !== type) return
|
|
222
|
+
|
|
223
|
+
// The bus carries whole envelopes; a handler wants the fact,
|
|
224
|
+
// not the correlation metadata around it.
|
|
225
|
+
const data = (payload as { data?: unknown })?.data ?? payload
|
|
226
|
+
try {
|
|
227
|
+
await handler(data as AxonOutputEvent[K])
|
|
228
|
+
} catch (cause) {
|
|
229
|
+
// Swallowed on purpose. The emission already committed and
|
|
230
|
+
// cannot be un-emitted, and a broken speaker is not the
|
|
231
|
+
// mind's problem — a body that throws must not take the
|
|
232
|
+
// brain down with it. Logged, never propagated.
|
|
233
|
+
console.error(`[axon] handler for ${type} failed:`, cause)
|
|
234
|
+
}
|
|
235
|
+
})
|
|
236
|
+
},
|
|
237
|
+
|
|
238
|
+
// No tick() here. The body emits stimuli and never decides when the
|
|
239
|
+
// brain looks at them: how fast frames arrive is a property of a
|
|
240
|
+
// sensor, how often it is worth thinking about them is a property of
|
|
241
|
+
// a mind. A cognet plugin drives kernel.tick() from inside the brain.
|
|
242
|
+
//
|
|
243
|
+
// This also makes bodies swappable — one that drove a specific brain
|
|
244
|
+
// had to be rewritten whenever the brain changed — and it is the only
|
|
245
|
+
// answer that survives composition, where two sensors at different
|
|
246
|
+
// rates have no claim to being "the" tick.
|
|
247
|
+
|
|
248
|
+
scripts: scripts,
|
|
249
|
+
|
|
250
|
+
// Getter, not a snapshot: update() swaps the map, and a consumer
|
|
251
|
+
|
|
252
|
+
async update(blueprint: AxonBlueprint) {
|
|
253
|
+
await kernel.update(blueprint)
|
|
254
|
+
// Re-project the tool map from the blueprint that just went live,
|
|
255
|
+
// so this handle and the capsule always agree on what exists.
|
|
256
|
+
// …and re-bind the host-side tool globals off the new map, so a
|
|
257
|
+
// script sees the same set. Inject owns every globalThis write;
|
|
258
|
+
// this asks it to redo them rather than reaching for the global
|
|
259
|
+
// itself.
|
|
260
|
+
opts.inject.runtime(handle as never, blueprint, opts.loaded)
|
|
261
|
+
},
|
|
262
|
+
|
|
263
|
+
// expose lifecycle hooks — one call point, awaited in order, runtime-fired
|
|
264
|
+
hooks: {
|
|
265
|
+
hook: opts.hooks.hook,
|
|
266
|
+
removeHook: opts.hooks.removeHook,
|
|
267
|
+
},
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* Session identity and logs, read-only. Getters rather than a snapshot:
|
|
271
|
+
* the underlying arrays are live and a consumer reading `entries` must
|
|
272
|
+
* see the current state, not whatever existed when the handle was built.
|
|
273
|
+
*/
|
|
274
|
+
session: {
|
|
275
|
+
get id() { return session.id },
|
|
276
|
+
get entries() { return session.entries },
|
|
277
|
+
get log() { return session.log },
|
|
278
|
+
get kernelLog() { return session.kernelLog },
|
|
279
|
+
},
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
return handle
|
|
283
|
+
}
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
import { err } from "@arcforge/err"
|
|
2
|
+
import type { AxonBlueprint, AxonEventMap, AxonSpanName, EngineCapability, EngineCloud } from "@arcforge/types"
|
|
3
|
+
import { buildProvider, providerPool } from "@arcforge/engines/providers"
|
|
4
|
+
import { Engines, gather, type AxonProvider, type Catalogue, type EnginesT } from "@arcforge/engines/catalogue"
|
|
5
|
+
|
|
6
|
+
type InferenceOpts = {
|
|
7
|
+
blueprint: AxonBlueprint
|
|
8
|
+
cloud: EngineCloud
|
|
9
|
+
/**
|
|
10
|
+
* Where to report resolution cost. Optional so an embedded host or a
|
|
11
|
+
* test can resolve roles without a session.
|
|
12
|
+
*/
|
|
13
|
+
session?: InferenceReporter
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** The slice of the session this needs — commit spans, nothing else. */
|
|
17
|
+
export type InferenceReporter = {
|
|
18
|
+
span<K extends AxonSpanName, T>(
|
|
19
|
+
name: K,
|
|
20
|
+
start: AxonEventMap[`${K}:start`],
|
|
21
|
+
run: () => Promise<T>,
|
|
22
|
+
complete?: (value: T) => Omit<AxonEventMap[`${K}:complete`], "durationMs">,
|
|
23
|
+
): Promise<T>
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Resolve this agent's declared engine roles against what its user has.
|
|
28
|
+
*
|
|
29
|
+
* Runs ONCE, at the Axon() seam, before the kernel exists and long before
|
|
30
|
+
* the cognet loads — because a required role that nothing can fill has to
|
|
31
|
+
* stop the boot. A brain that has already started is a brain that will reach
|
|
32
|
+
* for an engine which is not there, at a point where the only thing left to
|
|
33
|
+
* do about it is crash mid-wake.
|
|
34
|
+
*
|
|
35
|
+
* Lives in core rather than ring 0 for the same reason `base()` does:
|
|
36
|
+
* gathering catalogues is network work against a user's providers, and the
|
|
37
|
+
* kernel must stay a syscall table with no filesystem and no fetch of its
|
|
38
|
+
* own.
|
|
39
|
+
*
|
|
40
|
+
* Returns undefined for a cognet that declared no roles. That is every agent
|
|
41
|
+
* published before this existed, and they keep dispatching through the
|
|
42
|
+
* single `engine:` exactly as before — the role layer is additive, not a
|
|
43
|
+
* migration every author has to perform.
|
|
44
|
+
*/
|
|
45
|
+
export async function Inference(opts: InferenceOpts): Promise<EnginesT | undefined> {
|
|
46
|
+
const carriedSlot = opts.blueprint.cognet
|
|
47
|
+
const declared = carriedSlot.engines
|
|
48
|
+
?? ("definition" in carriedSlot ? carriedSlot.definition.engines : undefined)
|
|
49
|
+
|
|
50
|
+
// No roles declared: nothing to resolve and nothing worth a span. Every
|
|
51
|
+
// agent published before roles existed takes this path.
|
|
52
|
+
if (!declared || Object.keys(declared).length === 0) return undefined
|
|
53
|
+
if (!opts.session) return (await resolveRoles(opts)).engines
|
|
54
|
+
|
|
55
|
+
const resolved = await opts.session.span(
|
|
56
|
+
"axon:inference",
|
|
57
|
+
{ roles: Object.keys(declared) } as never,
|
|
58
|
+
() => resolveRoles(opts),
|
|
59
|
+
(value: Resolved) => ({
|
|
60
|
+
bound: value.engines?.resolution.bound.length ?? 0,
|
|
61
|
+
providers: value.providers,
|
|
62
|
+
failures: value.failures,
|
|
63
|
+
cached: value.cached,
|
|
64
|
+
}) as never,
|
|
65
|
+
)
|
|
66
|
+
|
|
67
|
+
return resolved.engines
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* What resolution produced, plus what it cost to produce.
|
|
72
|
+
*
|
|
73
|
+
* The counts ride on the return value rather than module state because a
|
|
74
|
+
* fleet boots several agents in ONE process: anything held outside the call
|
|
75
|
+
* would be read by whichever boot finished last, and a trace that reports
|
|
76
|
+
* another agent's provider count is worse than one that reports none.
|
|
77
|
+
*/
|
|
78
|
+
type Resolved = {
|
|
79
|
+
engines: EnginesT | undefined
|
|
80
|
+
providers: number
|
|
81
|
+
failures: number
|
|
82
|
+
/** Whether the hosted catalogue was served without touching the wire. */
|
|
83
|
+
cached: boolean
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
async function resolveRoles(opts: InferenceOpts): Promise<Resolved> {
|
|
87
|
+
// Two carriers, one answer. The CLI form stamps requirements onto the
|
|
88
|
+
// blueprint slot at prepare (so resolution can run without importing a
|
|
89
|
+
// bundle); the live-definition form — tests, embedded hosts — has them
|
|
90
|
+
// only on the definition itself. Reading both keeps a test cognet and a
|
|
91
|
+
// published one on the same path, which is the whole point of the
|
|
92
|
+
// definition escape hatch existing.
|
|
93
|
+
const carried = opts.blueprint.cognet
|
|
94
|
+
const requirements = carried.engines
|
|
95
|
+
?? ("definition" in carried ? carried.definition.engines : undefined)
|
|
96
|
+
|
|
97
|
+
if (!requirements || Object.keys(requirements).length === 0) {
|
|
98
|
+
return { engines: undefined, providers: 0, failures: 0, cached: false }
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
const pool = providerPool(opts.blueprint.profileProviders, opts.blueprint.config.providers)
|
|
102
|
+
|
|
103
|
+
const providers = new Map<string, AxonProvider>()
|
|
104
|
+
|
|
105
|
+
for (const declared of pool) {
|
|
106
|
+
providers.set(declared.provider, buildProvider(declared, { cloud: opts.cloud, env: opts.blueprint.env }))
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const gathered = await gatherTraced([...providers.values()], opts.session)
|
|
110
|
+
const catalogue = gathered.catalogue
|
|
111
|
+
|
|
112
|
+
const engines = Engines({
|
|
113
|
+
requirements,
|
|
114
|
+
capabilities: catalogue.capabilities,
|
|
115
|
+
providers,
|
|
116
|
+
// The agent's declared cortex choice. A preference on the primary
|
|
117
|
+
// role, never a constraint — see AxonConfig.model.
|
|
118
|
+
...(opts.blueprint.config.model !== undefined ? { model: opts.blueprint.config.model } : {}),
|
|
119
|
+
})
|
|
120
|
+
|
|
121
|
+
// A required role with nothing to fill it stops here, naming what was
|
|
122
|
+
// missing AND which sources could not answer — a user whose Ollama is
|
|
123
|
+
// down needs to see that, not "no engine matched", which would send them
|
|
124
|
+
// editing a config that is already correct.
|
|
125
|
+
if (engines.resolution.missing.length > 0) {
|
|
126
|
+
const unmet = engines.resolution.missing
|
|
127
|
+
.map(entry => ` ${entry.role}: ${entry.reasons[0] ?? "no candidate in any declared provider"}`)
|
|
128
|
+
.join("\n")
|
|
129
|
+
const failed = catalogue.failures
|
|
130
|
+
.map(failure => ` ${failure.provider}: ${failure.message}`)
|
|
131
|
+
.join("\n")
|
|
132
|
+
|
|
133
|
+
throw err("ENGINE_REQUIREMENTS_UNMET", {
|
|
134
|
+
detail: `this cognet needs engines nothing available can supply:\n${unmet}`
|
|
135
|
+
+ (failed ? `\n\nproviders that could not answer:\n${failed}` : ""),
|
|
136
|
+
})
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// A pin the pool could not honour is a WARNING, not a failure: the agent
|
|
140
|
+
// runs on what ranking chose and is fully usable. But it must be visible —
|
|
141
|
+
// a user who picked a model and silently got another one has no way to
|
|
142
|
+
// tell the picker worked at all. err() emits to the session's error
|
|
143
|
+
// channel, which is what the TUI renders.
|
|
144
|
+
const unhonoured = engines.resolution.unhonoured
|
|
145
|
+
if (unhonoured) {
|
|
146
|
+
const bound = engines.resolution.bound.find(entry => entry.requirement.primary)
|
|
147
|
+
?? engines.resolution.bound[0]
|
|
148
|
+
|
|
149
|
+
err("ENGINE_PIN_UNAVAILABLE", {
|
|
150
|
+
detail: `"${unhonoured.pin}" — ${unhonoured.reason}.`
|
|
151
|
+
+ (bound ? ` Running on ${bound.capability.provider}:${bound.capability.id} instead.` : ""),
|
|
152
|
+
context: {
|
|
153
|
+
pin: unhonoured.pin,
|
|
154
|
+
...(bound ? { using: `${bound.capability.provider}:${bound.capability.id}` } : {}),
|
|
155
|
+
},
|
|
156
|
+
})
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
return {
|
|
160
|
+
engines: engines,
|
|
161
|
+
providers: pool.length,
|
|
162
|
+
failures: catalogue.failures.length,
|
|
163
|
+
cached: gathered.cached,
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* gather(), with one span per provider.
|
|
170
|
+
*
|
|
171
|
+
* Providers answer CONCURRENTLY, which is the one case the envelope's
|
|
172
|
+
* bracket-matching cannot recover nesting for — so these carry an explicit
|
|
173
|
+
* spanId, exactly as engine calls do. Without them a slow boot says only
|
|
174
|
+
* "inference took 300ms"; with them it says which source was slow, which is
|
|
175
|
+
* the difference between a diagnosis and a shrug.
|
|
176
|
+
*
|
|
177
|
+
* Failures stay DATA, as gather() defines them: a provider that could not
|
|
178
|
+
* answer closes its own span as :failed and the catalogue is still returned.
|
|
179
|
+
*/
|
|
180
|
+
async function gatherTraced(
|
|
181
|
+
providers: readonly AxonProvider[],
|
|
182
|
+
session?: InferenceReporter,
|
|
183
|
+
): Promise<{ catalogue: Catalogue; cached: boolean }> {
|
|
184
|
+
if (!session) {
|
|
185
|
+
const catalogue = await gather(providers)
|
|
186
|
+
return { catalogue, cached: false }
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
const catalogue = await gather(providers.map(provider => ({
|
|
190
|
+
...provider,
|
|
191
|
+
catalogue: () => {
|
|
192
|
+
const spanId = crypto.randomUUID()
|
|
193
|
+
return session.span(
|
|
194
|
+
"axon:inference:provider",
|
|
195
|
+
{ provider: provider.name, spanId } as never,
|
|
196
|
+
() => provider.catalogue(),
|
|
197
|
+
(capabilities: EngineCapability[]) => ({
|
|
198
|
+
provider: provider.name,
|
|
199
|
+
spanId,
|
|
200
|
+
capabilities: capabilities.length,
|
|
201
|
+
cached: catalogueWasCached(provider),
|
|
202
|
+
}) as never,
|
|
203
|
+
)
|
|
204
|
+
},
|
|
205
|
+
})))
|
|
206
|
+
|
|
207
|
+
return { catalogue, cached: providers.every(catalogueWasCached) }
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Did this provider answer from its own cache rather than the wire?
|
|
212
|
+
*
|
|
213
|
+
* Providers that cache expose `cachedAt` — a timestamp set when the last
|
|
214
|
+
* answer was served from disk and cleared when it came from the network.
|
|
215
|
+
* A provider that does not cache (Ollama: a localhost call cheaper than the
|
|
216
|
+
* disk read that would cache it) never reports true, which is the honest
|
|
217
|
+
* answer rather than a flattering one.
|
|
218
|
+
*/
|
|
219
|
+
function catalogueWasCached(provider: AxonProvider): boolean {
|
|
220
|
+
return (provider as AxonProvider & { cachedAt?: number }).cachedAt !== undefined
|
|
221
|
+
}
|