@arcforge/core 2.0.219 → 2.0.244
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 +19 -15
- package/src/Axon.ts +11 -10
- package/src/cognet/cognet.ts +29 -65
- package/src/index.ts +5 -0
- package/src/platform/blueprint.ts +16 -2
- package/src/platform/boot.ts +1 -2
- package/src/platform/bus.ts +23 -28
- package/src/platform/inject.ts +3 -4
- package/src/runtime/accounts.ts +20 -0
- package/src/runtime/conform.ts +34 -0
- package/src/runtime/connect.ts +43 -0
- package/src/runtime/grants.ts +233 -0
- package/src/runtime/handle.ts +15 -14
- package/src/runtime/inference.ts +54 -19
- package/src/runtime/server/endpoints.ts +3 -3
- package/src/runtime/server/session-view.ts +4 -0
- package/src/runtime/server/streams.ts +1 -2
- package/src/runtime/services/conformance.ts +178 -0
- package/src/runtime/services/index.ts +4 -0
- package/src/runtime/services/resolve.ts +114 -0
- package/src/runtime/services/standard.ts +203 -0
- package/src/tools/mediate.ts +9 -8
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
import { err } from "@arcforge/err"
|
|
2
|
+
import type { AxonBlueprint, AxonDriver, CognetUse, ProviderDefinition, RemoteEngines, ResolvedEngineFacts, ServiceGrants, ServiceProvider, ServiceRequirement } from "@arcforge/types"
|
|
3
|
+
import type { EnginesT } from "@arcforge/engines/catalogue"
|
|
4
|
+
import { granted, STANDARD, type Granted } from "./services"
|
|
5
|
+
|
|
6
|
+
type GrantsOpts = {
|
|
7
|
+
blueprint: AxonBlueprint
|
|
8
|
+
/** This process's resolved engines — absent for a confined agent, or one whose uses ask the engines for nothing. */
|
|
9
|
+
engines?: EnginesT
|
|
10
|
+
/** A confined agent's engines, on the supervisor's side; the facts of each bound role crossed on the blueprint. */
|
|
11
|
+
remote?: RemoteEngines
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Grants — what fills each use the cognet declares, decided once, at boot,
|
|
16
|
+
* on the agent's side of the boundary.
|
|
17
|
+
*
|
|
18
|
+
* A use is filled by what the agent's `services:` grants it: one of its own
|
|
19
|
+
* providers (`./providers/features`), a route its inference sources supply,
|
|
20
|
+
* or — `auto`, and absent — its own provider for that interface if it wrote
|
|
21
|
+
* exactly one, else the engine resolution bound to the use. Then held to the
|
|
22
|
+
* use: what it `requires` of `describe()` must be met, and a limit wraps it.
|
|
23
|
+
*
|
|
24
|
+
* A REQUIRED use nothing fills stops the boot here, by name — a mind that
|
|
25
|
+
* started without it would reach for it mid-wake. An optional one is simply
|
|
26
|
+
* unavailable, which a mind asks about.
|
|
27
|
+
*
|
|
28
|
+
* Async because the agent's own providers are modules, loaded before the
|
|
29
|
+
* first call can reach one.
|
|
30
|
+
*/
|
|
31
|
+
export async function Grants(opts: GrantsOpts): Promise<ServiceGrants> {
|
|
32
|
+
const uses = opts.blueprint.cognet.uses ?? {}
|
|
33
|
+
const grants = granted(uses, opts.blueprint.config.services)
|
|
34
|
+
const own = await loaded(opts.blueprint.serviceProviders)
|
|
35
|
+
|
|
36
|
+
const filled = new Map<string, ServiceProvider>()
|
|
37
|
+
/** Providers that are an engine resolution bound: the resolver has already admitted what they cannot report. */
|
|
38
|
+
const engined = new Set<ServiceProvider>()
|
|
39
|
+
const unfilled: string[] = []
|
|
40
|
+
for (const [name, use] of Object.entries(uses)) {
|
|
41
|
+
const grant = grants[name]!
|
|
42
|
+
const provider = pick(name, use, grant)
|
|
43
|
+
if (!provider) {
|
|
44
|
+
if (!use.optional) unfilled.push(`${name} (${use.named})${grant.kind === "off" ? " — granted off" : ""}`)
|
|
45
|
+
continue
|
|
46
|
+
}
|
|
47
|
+
const unmet = unmetBy(use, provider.describe(), engined.has(provider))
|
|
48
|
+
if (unmet) {
|
|
49
|
+
if (!use.optional) unfilled.push(`${name} (${use.named}) — ${provider.name} ${unmet}`)
|
|
50
|
+
else err("SERVICE_UNAVAILABLE", { detail: `${name} is unavailable: ${provider.name} ${unmet}`, context: { use: name } })
|
|
51
|
+
continue
|
|
52
|
+
}
|
|
53
|
+
filled.set(name, grant.kind !== "off" && grant.limit ? limited(provider, name, grant.limit) : provider)
|
|
54
|
+
}
|
|
55
|
+
if (unfilled.length > 0) {
|
|
56
|
+
throw err("SERVICE_UNAVAILABLE", { detail: `this cognet requires uses nothing can fill:\n ${unfilled.join("\n ")}`, context: { uses: unfilled } })
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
return { granted: use => filled.get(use) ?? null }
|
|
60
|
+
|
|
61
|
+
/** What a grant names, as a provider of the use's interface — or null when nothing fills it. */
|
|
62
|
+
function pick(name: string, use: CognetUse, grant: Granted): ServiceProvider | null {
|
|
63
|
+
if (grant.kind === "off") return null
|
|
64
|
+
if (grant.kind === "own") {
|
|
65
|
+
const found = own.get(grant.path)
|
|
66
|
+
if (!found) throw err("SERVICE_INVALID", { detail: `services.${name}: no provider ${grant.path} — write providers/${grant.path.slice("./providers/".length)}.provider.ts`, context: { use: name } })
|
|
67
|
+
return written(grant.path, found, name, use, needed(grant.path, found.needs, name))
|
|
68
|
+
}
|
|
69
|
+
if (grant.kind === "auto") {
|
|
70
|
+
const implementing = [...own].filter(([, definition]) => definition.implements === use.named)
|
|
71
|
+
if (implementing.length > 1) throw err("SERVICE_INVALID", { detail: `services.${name}: ${implementing.map(([path]) => path).join(" and ")} both implement ${use.named} — grant one`, context: { use: name } })
|
|
72
|
+
if (implementing.length === 1) {
|
|
73
|
+
const [path, definition] = implementing[0]!
|
|
74
|
+
return written(path, definition, name, use, needed(path, definition.needs, name))
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
return engine(name, use)
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** The drivers a provider the agent wrote asked for, each bound as `<provider>/<engine>` — or a refusal naming what is missing. */
|
|
81
|
+
function needed(path: string, needs: Readonly<Record<string, unknown>>, use: string): Record<string, AxonDriver> {
|
|
82
|
+
return Object.fromEntries(Object.keys(needs).map(engine => {
|
|
83
|
+
const role = `${path}/${engine}`
|
|
84
|
+
const driver = drive(role)
|
|
85
|
+
if (!driver) throw err("SERVICE_UNAVAILABLE", { detail: `${use}: ${path} needs a ${engine} engine, and nothing this machine has can serve it`, context: { use: use, provider: path } })
|
|
86
|
+
return [engine, driver]
|
|
87
|
+
}))
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** The driver resolution bound to a role, here or on the supervisor's side — null when none was. */
|
|
91
|
+
function drive(role: string): AxonDriver | null {
|
|
92
|
+
if (opts.remote) {
|
|
93
|
+
const facts = opts.blueprint.cognet.resolvedEngines?.[role]
|
|
94
|
+
if (!facts) return null
|
|
95
|
+
return facts.type === "transform" ? opts.remote.transform(role) : opts.remote.generate(role)
|
|
96
|
+
}
|
|
97
|
+
return opts.engines?.has(role) ? opts.engines.get(role).driver : null
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** The engine resolution bound to the use, served through its interface's adapter — or null when none was bound. */
|
|
101
|
+
function engine(name: string, use: CognetUse): ServiceProvider | null {
|
|
102
|
+
const adapter = STANDARD[use.named]
|
|
103
|
+
if (!adapter) return null
|
|
104
|
+
if (opts.remote) {
|
|
105
|
+
const facts = opts.blueprint.cognet.resolvedEngines?.[name]
|
|
106
|
+
if (!facts) return null
|
|
107
|
+
const driver = facts.type === "transform" ? opts.remote.transform(name) : opts.remote.generate(name)
|
|
108
|
+
// The supervisor knows which route answers; the box is told only what it can do.
|
|
109
|
+
return bound(adapter.provider(driver, "supervisor", asked(use, facts)))
|
|
110
|
+
}
|
|
111
|
+
if (!opts.engines?.has(name)) return null
|
|
112
|
+
const { driver, binding } = opts.engines.get(name)
|
|
113
|
+
const facts: ResolvedEngineFacts = {
|
|
114
|
+
type: binding.requirement.type,
|
|
115
|
+
...(binding.capability.context !== undefined ? { context: binding.capability.context } : {}),
|
|
116
|
+
modalities: { in: [...binding.capability.in], out: [...binding.capability.out] },
|
|
117
|
+
slots: binding.slots,
|
|
118
|
+
}
|
|
119
|
+
return bound(adapter.provider(driver, `${binding.capability.provider}:${binding.capability.id}`, asked(use, facts)))
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function bound(provider: ServiceProvider): ServiceProvider {
|
|
123
|
+
engined.add(provider)
|
|
124
|
+
return provider
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** What resolution learned, with no more slots than the use asked for: `parallel` is the most it would use. */
|
|
128
|
+
function asked(use: CognetUse, facts: ResolvedEngineFacts): ResolvedEngineFacts {
|
|
129
|
+
return use.parallel !== undefined && use.parallel < facts.slots ? { ...facts, slots: use.parallel } : facts
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** Every provider the agent wrote, loaded and checked: each a module whose default export says what it implements. */
|
|
134
|
+
async function loaded(providers: AxonBlueprint["serviceProviders"]): Promise<Map<string, ProviderDefinition & { needs: AxonBlueprint["serviceProviders"][number]["engines"] }>> {
|
|
135
|
+
const found = new Map<string, ProviderDefinition & { needs: AxonBlueprint["serviceProviders"][number]["engines"] }>()
|
|
136
|
+
for (const provider of providers) {
|
|
137
|
+
const module = await import(provider.filePath) as { default?: unknown }
|
|
138
|
+
const definition = module.default
|
|
139
|
+
if (typeof definition !== "object" || definition === null || typeof (definition as ProviderDefinition).implements !== "string" || typeof (definition as ProviderDefinition).describe !== "function") {
|
|
140
|
+
throw err("SERVICE_INVALID", { detail: `${provider.filePath}: a provider's default export is defineProvider({ implements, describe, … })`, context: { provider: provider.name } })
|
|
141
|
+
}
|
|
142
|
+
found.set(provider.name, Object.assign(definition as ProviderDefinition, { needs: provider.engines }))
|
|
143
|
+
}
|
|
144
|
+
return found
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* A provider the agent wrote, as the kernel calls it: each method of the
|
|
149
|
+
* interface taking its arguments as the interface writes them — positional,
|
|
150
|
+
* in its parameters' order — from the one object a call crosses as.
|
|
151
|
+
*/
|
|
152
|
+
function written(path: string, definition: ProviderDefinition, name: string, use: CognetUse, engines: Record<string, AxonDriver>): ServiceProvider {
|
|
153
|
+
if (definition.implements !== use.named) {
|
|
154
|
+
throw err("SERVICE_INVALID", { detail: `services.${name}: ${path} implements ${definition.implements}, but ${name} uses ${use.named}`, context: { use: name } })
|
|
155
|
+
}
|
|
156
|
+
const missing = Object.entries(use.methods).filter(([method, shape]) => shape.kind !== "describe" && typeof definition[method] !== "function").map(([method]) => method)
|
|
157
|
+
if (missing.length > 0) throw err("SERVICE_INVALID", { detail: `${path} implements ${use.named} but has no ${missing.join(", ")}`, context: { provider: path } })
|
|
158
|
+
|
|
159
|
+
// What a method's `this` holds: the definition, and the machine's engines it asked for.
|
|
160
|
+
const self = Object.assign(Object.create(definition) as ProviderDefinition, { engines: engines })
|
|
161
|
+
const method = (named: string) => definition[named] as (...args: unknown[]) => unknown
|
|
162
|
+
const positional = (named: string, args: Readonly<Record<string, unknown>>) => use.methods[named]!.params.map(param => args[param])
|
|
163
|
+
return {
|
|
164
|
+
name: path,
|
|
165
|
+
describe: () => definition.describe.call(self),
|
|
166
|
+
call: async (named, args) => method(named).apply(self, positional(named, args)),
|
|
167
|
+
stream: (named, args) => method(named).apply(self, positional(named, args)) as AsyncIterable<unknown>,
|
|
168
|
+
open: async named => {
|
|
169
|
+
const session = await method(named).apply(self, []) as { push(value: unknown): Promise<unknown>; reset(): Promise<void> | void; close(): Promise<void> | void }
|
|
170
|
+
return { push: value => session.push(value), reset: async () => session.reset(), close: async () => session.close() }
|
|
171
|
+
},
|
|
172
|
+
release: async handle => {
|
|
173
|
+
if (!definition.release) throw err("SERVICE_INVALID", { detail: `${path} hands out handles but has no release()`, context: { provider: path } })
|
|
174
|
+
await definition.release.call(self, handle)
|
|
175
|
+
},
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Why what a provider reports does not meet what the use requires of it — null when it does.
|
|
181
|
+
*
|
|
182
|
+
* A field it does not report refuses a provider the agent wrote. For an engine
|
|
183
|
+
* the resolver bound it is UNKNOWN, as the resolver read it — a route that does
|
|
184
|
+
* not publish a context window was admitted there, and refusing it here would
|
|
185
|
+
* undo that decision with nothing new to go on.
|
|
186
|
+
*/
|
|
187
|
+
function unmetBy(use: CognetUse, described: Readonly<Record<string, unknown>>, resolved: boolean): string | null {
|
|
188
|
+
for (const [field, required] of Object.entries(use.requires ?? {})) {
|
|
189
|
+
const reported = described[field]
|
|
190
|
+
if (reported === undefined && resolved) continue
|
|
191
|
+
if (reported === undefined) return `does not report ${field}, which the use requires`
|
|
192
|
+
if (!meets(reported, required)) return `reports ${field} ${JSON.stringify(reported)}, which does not meet ${JSON.stringify(required)}`
|
|
193
|
+
}
|
|
194
|
+
return null
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
function meets(reported: unknown, required: ServiceRequirement): boolean {
|
|
198
|
+
if (typeof required !== "object") return reported === required
|
|
199
|
+
if ("includes" in required) return Array.isArray(reported) && required.includes.every(value => reported.includes(value))
|
|
200
|
+
if (typeof reported !== "number") return false
|
|
201
|
+
return (required.min === undefined || reported >= required.min) && (required.max === undefined || reported <= required.max)
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** A provider within a limit: past it, calls are refused with SERVICE_LIMIT until the window moves on. */
|
|
205
|
+
function limited(provider: ServiceProvider, name: string, limit: NonNullable<Exclude<Granted, { kind: "off" }>["limit"]>): ServiceProvider {
|
|
206
|
+
if (limit.usd !== undefined) throw err("SERVICE_INVALID", { detail: `services.${name}: a usd limit is not wired yet — nothing prices a call; limit calls instead`, context: { use: name } })
|
|
207
|
+
if (limit.calls === undefined) return provider
|
|
208
|
+
const window = { second: 1_000, minute: 60_000, hour: 3_600_000, day: 86_400_000 }[limit.per]
|
|
209
|
+
const made: number[] = []
|
|
210
|
+
const admit = () => {
|
|
211
|
+
const now = Date.now()
|
|
212
|
+
while (made.length > 0 && made[0]! <= now - window) made.shift()
|
|
213
|
+
if (made.length >= limit.calls!) throw err("SERVICE_LIMIT", { detail: `${name} reached its limit of ${limit.calls} calls a ${limit.per}`, context: { use: name } })
|
|
214
|
+
made.push(now)
|
|
215
|
+
}
|
|
216
|
+
return {
|
|
217
|
+
name: provider.name,
|
|
218
|
+
describe: () => provider.describe(),
|
|
219
|
+
call: async (method, args, signal) => {
|
|
220
|
+
admit()
|
|
221
|
+
return provider.call(method, args, signal)
|
|
222
|
+
},
|
|
223
|
+
stream: (method, args, signal) => {
|
|
224
|
+
admit()
|
|
225
|
+
return provider.stream(method, args, signal)
|
|
226
|
+
},
|
|
227
|
+
open: async method => {
|
|
228
|
+
admit()
|
|
229
|
+
return provider.open(method)
|
|
230
|
+
},
|
|
231
|
+
release: handle => provider.release(handle),
|
|
232
|
+
}
|
|
233
|
+
}
|
package/src/runtime/handle.ts
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
import { createRequire } from "node:module"
|
|
2
2
|
import { err } from "@arcforge/err"
|
|
3
3
|
import type { AxonCloudClient } from "@arcforge/cloud"
|
|
4
|
-
import { foldChunks, type AxonBlueprint, type AxonRequestInput, type AxonResult, type AxonToolNamespaces } from "@arcforge/types"
|
|
5
|
-
import {
|
|
6
|
-
import type { AxonBusT } from "../platform"
|
|
7
|
-
import type { AxonOutputEvent } from "@arcforge/types"
|
|
4
|
+
import { foldChunks, type AxonBlueprint, type AxonOutputEvent, type AxonRequestInput, type AxonResult, type AxonToolNamespaces } from "@arcforge/types"
|
|
5
|
+
import { Inject, type AxonBusT, type AxonHooksT } from "../platform"
|
|
8
6
|
import { Prompt } from "./source/render"
|
|
9
7
|
import { Scripts } from "./source/scripts"
|
|
8
|
+
import { Connections } from "./connect"
|
|
10
9
|
import { AxonKernelT } from "@arcforge/kernel"
|
|
11
10
|
import type { Output as OutputFactory } from "@arcforge/air/output"
|
|
12
11
|
import type { AxonSessionT } from "@arcforge/session"
|
|
@@ -161,6 +160,7 @@ export function AxonHandle(opts: AxonHandleOpts) {
|
|
|
161
160
|
|
|
162
161
|
|
|
163
162
|
const invoke = Invoke({ kernel })
|
|
163
|
+
const connections = Connections({ kernel: kernel, bus: opts.bus })
|
|
164
164
|
|
|
165
165
|
const handle = {
|
|
166
166
|
// Getter, not a snapshot: a reload can unload the brain at any time,
|
|
@@ -256,6 +256,8 @@ export function AxonHandle(opts: AxonHandleOpts) {
|
|
|
256
256
|
|
|
257
257
|
stream: invoke.stream,
|
|
258
258
|
|
|
259
|
+
connect: connections.open,
|
|
260
|
+
|
|
259
261
|
/**
|
|
260
262
|
* The sense door. Delegates straight to the session's ingest, which
|
|
261
263
|
* commits the stimulus and queues it for the next wake — the buffer's
|
|
@@ -267,6 +269,12 @@ export function AxonHandle(opts: AxonHandleOpts) {
|
|
|
267
269
|
*/
|
|
268
270
|
stim: session.stimuli.ingest,
|
|
269
271
|
|
|
272
|
+
/** Where a producer keeps the bytes its stimulus refers to. */
|
|
273
|
+
media: session.media,
|
|
274
|
+
|
|
275
|
+
/** The body this agent wears — told by what connects it to one, kept by the kernel, read by the cognet. */
|
|
276
|
+
body: opts.kernel.body,
|
|
277
|
+
|
|
270
278
|
/**
|
|
271
279
|
* Observe what the brain emits — the counterpart to stim().
|
|
272
280
|
*
|
|
@@ -291,22 +299,14 @@ export function AxonHandle(opts: AxonHandleOpts) {
|
|
|
291
299
|
// The bus carries whole envelopes; a handler wants the fact,
|
|
292
300
|
// not the correlation metadata around it.
|
|
293
301
|
const data = (payload as { data?: unknown })?.data ?? payload
|
|
294
|
-
|
|
295
|
-
await handler(data as AxonOutputEvent[K])
|
|
296
|
-
} catch (cause) {
|
|
297
|
-
// Swallowed on purpose. The emission already committed and
|
|
298
|
-
// cannot be un-emitted, and a broken speaker is not the
|
|
299
|
-
// mind's problem — a body that throws must not take the
|
|
300
|
-
// brain down with it. Logged, never propagated.
|
|
301
|
-
console.error(`[axon] handler for ${type} failed:`, cause)
|
|
302
|
-
}
|
|
302
|
+
await handler(data as AxonOutputEvent[K])
|
|
303
303
|
})
|
|
304
304
|
},
|
|
305
305
|
|
|
306
306
|
// No tick() here. The body emits stimuli and never decides when the
|
|
307
307
|
// brain looks at them: how fast frames arrive is a property of a
|
|
308
308
|
// sensor, how often it is worth thinking about them is a property of
|
|
309
|
-
// a mind.
|
|
309
|
+
// a mind. The brain's own host drives kernel.wake() at its `mode.hz`.
|
|
310
310
|
//
|
|
311
311
|
// This also makes bodies swappable — one that drove a specific brain
|
|
312
312
|
// had to be rewritten whenever the brain changed — and it is the only
|
|
@@ -350,6 +350,7 @@ export function AxonHandle(opts: AxonHandleOpts) {
|
|
|
350
350
|
get entries() { return session.entries },
|
|
351
351
|
get log() { return session.log },
|
|
352
352
|
get kernelLog() { return session.kernelLog },
|
|
353
|
+
get kernelFloor() { return session.kernelFloor },
|
|
353
354
|
},
|
|
354
355
|
}
|
|
355
356
|
|
package/src/runtime/inference.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { err } from "@arcforge/err"
|
|
2
|
-
import type { AxonBlueprint, AxonEventMap, AxonSpanName, EngineCapability, EngineCloud } from "@arcforge/types"
|
|
2
|
+
import type { AxonBlueprint, AxonEventMap, AxonSpanName, EngineCapability, EngineCloud, EngineRequirements } from "@arcforge/types"
|
|
3
|
+
import { engineRoles, granted } from "./services"
|
|
3
4
|
import { buildProvider, providerPool } from "@arcforge/engines/providers"
|
|
4
5
|
import { Engines, gather, type AxonProvider, type Catalogue, type EnginesT, type LocalRuntime } from "@arcforge/engines/catalogue"
|
|
6
|
+
import { Accounts } from "./accounts"
|
|
5
7
|
|
|
6
8
|
type InferenceOpts = {
|
|
7
9
|
blueprint: AxonBlueprint
|
|
@@ -45,13 +47,11 @@ export type InferenceReporter = {
|
|
|
45
47
|
* migration every author has to perform.
|
|
46
48
|
*/
|
|
47
49
|
export async function Inference(opts: InferenceOpts): Promise<EnginesT | undefined> {
|
|
48
|
-
const
|
|
49
|
-
const declared = carriedSlot.engines
|
|
50
|
-
?? ("definition" in carriedSlot ? carriedSlot.definition.engines : undefined)
|
|
50
|
+
const declared = roles(opts.blueprint).requirements
|
|
51
51
|
|
|
52
52
|
// No roles declared: nothing to resolve and nothing worth a span. Every
|
|
53
53
|
// agent published before roles existed takes this path.
|
|
54
|
-
if (
|
|
54
|
+
if (Object.keys(declared).length === 0) return undefined
|
|
55
55
|
if (!opts.session) return (await resolveRoles(opts)).engines
|
|
56
56
|
|
|
57
57
|
const resolved = await opts.session.span(
|
|
@@ -69,6 +69,30 @@ export async function Inference(opts: InferenceOpts): Promise<EnginesT | undefin
|
|
|
69
69
|
return resolved.engines
|
|
70
70
|
}
|
|
71
71
|
|
|
72
|
+
/**
|
|
73
|
+
* Every role to resolve: the engines the cognet declares, and one for each use
|
|
74
|
+
* of a standard interface the machine's engines may serve — named as the use
|
|
75
|
+
* is — with the routes the agent granted by name.
|
|
76
|
+
*
|
|
77
|
+
* Two carriers, one answer for the engines. The CLI form stamps requirements
|
|
78
|
+
* onto the blueprint slot at prepare (so resolution can run without importing
|
|
79
|
+
* a bundle); the live-definition form — tests, embedded hosts — has them only
|
|
80
|
+
* on the definition itself.
|
|
81
|
+
*/
|
|
82
|
+
function roles(blueprint: AxonBlueprint): { requirements: EngineRequirements; pins: Record<string, string> } {
|
|
83
|
+
const carried = blueprint.cognet
|
|
84
|
+
const engines = carried.engines ?? ("definition" in carried ? carried.definition.engines : undefined) ?? {}
|
|
85
|
+
const uses = carried.uses ?? {}
|
|
86
|
+
const services = engineRoles(uses, granted(uses, blueprint.config.services))
|
|
87
|
+
const clash = Object.keys(services.requirements).find(name => name in engines)
|
|
88
|
+
if (clash) throw err("SERVICE_INVALID", { detail: `"${clash}" is both an engine role and a use — name one of them something else`, context: { use: clash } })
|
|
89
|
+
// What the agent's own providers need of the machine, each as `<provider>/<engine>`. Optional to the
|
|
90
|
+
// resolver: a provider nothing grants needs nothing, and Grants refuses one that is granted without them.
|
|
91
|
+
const provided = Object.fromEntries((blueprint.serviceProviders ?? []).flatMap(provider =>
|
|
92
|
+
Object.entries(provider.engines).map(([name, requirement]) => [`${provider.name}/${name}`, { ...requirement, optional: true }])))
|
|
93
|
+
return { requirements: { ...engines, ...services.requirements, ...provided }, pins: services.pins }
|
|
94
|
+
}
|
|
95
|
+
|
|
72
96
|
/**
|
|
73
97
|
* What resolution produced, plus what it cost to produce.
|
|
74
98
|
*
|
|
@@ -92,15 +116,15 @@ async function resolveRoles(opts: InferenceOpts): Promise<Resolved> {
|
|
|
92
116
|
// only on the definition itself. Reading both keeps a test cognet and a
|
|
93
117
|
// published one on the same path, which is the whole point of the
|
|
94
118
|
// definition escape hatch existing.
|
|
95
|
-
const
|
|
96
|
-
const requirements = carried.engines
|
|
97
|
-
?? ("definition" in carried ? carried.definition.engines : undefined)
|
|
119
|
+
const { requirements, pins } = roles(opts.blueprint)
|
|
98
120
|
|
|
99
|
-
if (
|
|
121
|
+
if (Object.keys(requirements).length === 0) {
|
|
100
122
|
return { engines: undefined, providers: 0, failures: 0, cached: false }
|
|
101
123
|
}
|
|
102
124
|
|
|
103
|
-
const
|
|
125
|
+
const accounts = Accounts({ connections: opts.cloud.user.vault.connections, auth: opts.cloud.user.auth, profile: opts.blueprint.profileProviders })
|
|
126
|
+
const account = await accounts.list()
|
|
127
|
+
const pool = providerPool(opts.blueprint.profileProviders, opts.blueprint.config.providers, account)
|
|
104
128
|
|
|
105
129
|
const providers = new Map<string, AxonProvider>()
|
|
106
130
|
|
|
@@ -122,6 +146,8 @@ async function resolveRoles(opts: InferenceOpts): Promise<Resolved> {
|
|
|
122
146
|
// The agent's declared cortex choice. A preference on the primary
|
|
123
147
|
// role, never a constraint — see AxonConfig.model.
|
|
124
148
|
...(opts.blueprint.config.model !== undefined ? { model: opts.blueprint.config.model } : {}),
|
|
149
|
+
// What the agent granted its uses by name — not preferences: see resolveEngines.
|
|
150
|
+
granted: pins,
|
|
125
151
|
})
|
|
126
152
|
|
|
127
153
|
// A required role with nothing to fill it stops here, naming what was
|
|
@@ -198,15 +224,24 @@ async function gatherTraced(
|
|
|
198
224
|
const spanId = crypto.randomUUID()
|
|
199
225
|
return session.span(
|
|
200
226
|
"axon:inference:provider",
|
|
201
|
-
{ provider: provider.name, spanId }
|
|
202
|
-
() =>
|
|
203
|
-
|
|
204
|
-
provider
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
227
|
+
{ provider: provider.name, spanId: spanId },
|
|
228
|
+
async () => {
|
|
229
|
+
const [result] = await Promise.allSettled([provider.catalogue()])
|
|
230
|
+
if (!result) throw new Error("The provider catalogue observation returned no outcome")
|
|
231
|
+
return result
|
|
232
|
+
},
|
|
233
|
+
result => ({
|
|
234
|
+
provider: provider.name, spanId: spanId,
|
|
235
|
+
capabilities: result.status === "fulfilled" ? result.value.length : 0,
|
|
236
|
+
cached: result.status === "fulfilled" && catalogueWasCached(provider),
|
|
237
|
+
...(result.status === "rejected" ? { failure: { message: result.reason instanceof Error ? result.reason.message : String(result.reason) } } : {}),
|
|
238
|
+
}),
|
|
239
|
+
).then(result => {
|
|
240
|
+
// Discovery failures remain catalogue data; a missing required
|
|
241
|
+
// binding is the boundary that turns them into an agent error.
|
|
242
|
+
if (result.status === "rejected") throw result.reason
|
|
243
|
+
return result.value
|
|
244
|
+
})
|
|
210
245
|
},
|
|
211
246
|
})))
|
|
212
247
|
|
|
@@ -74,8 +74,8 @@ type EndpointsOpts = {
|
|
|
74
74
|
*/
|
|
75
75
|
function engineIdentity(
|
|
76
76
|
engines: EnginesT | undefined,
|
|
77
|
-
declared:
|
|
78
|
-
):
|
|
77
|
+
declared: AxonBlueprint["engine"],
|
|
78
|
+
): NonNullable<AxonBlueprint["engine"]> | null {
|
|
79
79
|
// The blueprint's answer first.
|
|
80
80
|
//
|
|
81
81
|
// A CONFINED agent has no engines of its own: resolving needs the
|
|
@@ -93,7 +93,7 @@ function engineIdentity(
|
|
|
93
93
|
const primary = bound.find(entry => entry.requirement.primary) ?? bound.find(entry => entry.role === "main")
|
|
94
94
|
if (!primary) return null
|
|
95
95
|
|
|
96
|
-
return { provider: primary.capability.provider, model: primary.capability.id }
|
|
96
|
+
return { provider: primary.capability.provider, model: primary.capability.id, ...(primary.effort !== undefined ? { effort: primary.effort } : {}) }
|
|
97
97
|
}
|
|
98
98
|
|
|
99
99
|
export function Endpoints(opts: EndpointsOpts) {
|
|
@@ -79,6 +79,10 @@ export function snapshot(axon: AxonHandle, query: AxonSessionQuery): AxonSession
|
|
|
79
79
|
const entries = select(axon.session.entries, "entries")
|
|
80
80
|
const log = select(axon.session.log, "log")
|
|
81
81
|
const kernelLog = select(axon.session.kernelLog, "kernelLog")
|
|
82
|
+
// The kernel log is a window: asking from before it begins is asking for
|
|
83
|
+
// events only the disk still has, and the answer is truncated, said so.
|
|
84
|
+
const floor = axon.session.kernelFloor
|
|
85
|
+
if (include.includes("kernelLog") && floor > 0 && (since === undefined || since < floor)) kernelLog.capped = true
|
|
82
86
|
|
|
83
87
|
// The cursor is the high-water mark across everything RETURNED, so a client
|
|
84
88
|
// that omitted kernelLog does not skip past kernel events it never received.
|
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import type { setResponseHeader } from "h3"
|
|
2
|
-
import type
|
|
3
|
-
import { classifyEvent } from "@arcforge/types"
|
|
2
|
+
import { classifyEvent, type AxonEventView, type AxonHandle, type AxonSessionQuery } from "@arcforge/types"
|
|
4
3
|
import type { AxonBusT } from "../../platform"
|
|
5
4
|
import { frame, sseResponse } from "./sse"
|
|
6
5
|
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs"
|
|
2
|
+
import { join } from "node:path"
|
|
3
|
+
import { err } from "@arcforge/err"
|
|
4
|
+
import type { CognetUse, ServiceProvider } from "@arcforge/types"
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* One case: a method, what it is given, and what a correct provider answers.
|
|
8
|
+
* `call` names a call; `stream` a stream, whose answers are checked as
|
|
9
|
+
* `{ events, last }`.
|
|
10
|
+
*/
|
|
11
|
+
export type Case = {
|
|
12
|
+
name: string
|
|
13
|
+
call?: string
|
|
14
|
+
stream?: string
|
|
15
|
+
given: Record<string, unknown>
|
|
16
|
+
expect: unknown
|
|
17
|
+
/** The tolerance on each number checked exactly, by field name. */
|
|
18
|
+
within?: Record<string, number>
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** How one case went: passed, or every way it did not. */
|
|
22
|
+
export type Outcome = { name: string; passed: boolean; problems: string[] }
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Conformance — the cases an interface ships, run against one provider of it.
|
|
26
|
+
*
|
|
27
|
+
* A strict interface is only strict if something checks: the cases are what
|
|
28
|
+
* a provider would most likely get wrong — conventions, units, ranges — and
|
|
29
|
+
* every provider of the interface is held to the same ones. Inputs are
|
|
30
|
+
* written in the cases (`$picture`, typed arrays, another call's answer), so
|
|
31
|
+
* running them needs nothing but the provider.
|
|
32
|
+
*/
|
|
33
|
+
export function Conformance(opts: { use: CognetUse; provider: ServiceProvider; dir: string }) {
|
|
34
|
+
return {
|
|
35
|
+
/** Every case in the interface's `cases.json`, in order. */
|
|
36
|
+
async run(): Promise<Outcome[]> {
|
|
37
|
+
const outcomes: Outcome[] = []
|
|
38
|
+
for (const one of cases(opts.dir)) outcomes.push(await run(one))
|
|
39
|
+
return outcomes
|
|
40
|
+
},
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
async function run(one: Case): Promise<Outcome> {
|
|
44
|
+
try {
|
|
45
|
+
const given = await inputs(one.given)
|
|
46
|
+
const answer = one.stream ? await streamed(one.stream, given) : await opts.provider.call(called(one), given)
|
|
47
|
+
const problems: string[] = []
|
|
48
|
+
check(answer, one.expect, "", one.within ?? {}, answer, problems)
|
|
49
|
+
return { name: one.name, passed: problems.length === 0, problems: problems }
|
|
50
|
+
} catch (cause) {
|
|
51
|
+
return { name: one.name, passed: false, problems: [`it failed: ${cause instanceof Error ? cause.message : String(cause)}`] }
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function called(one: Case): string {
|
|
56
|
+
const method = one.call
|
|
57
|
+
if (!method || !opts.use.methods[method]) throw err("SERVICE_INVALID", { detail: `case "${one.name}" calls ${method ?? "nothing"}, which ${opts.use.named} has not got` })
|
|
58
|
+
return method
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
async function streamed(method: string, given: Record<string, unknown>): Promise<{ events: unknown[]; last: unknown }> {
|
|
62
|
+
const events: unknown[] = []
|
|
63
|
+
for await (const event of opts.provider.stream(method, given)) events.push(event)
|
|
64
|
+
return { events: events, last: events.at(-1) ?? null }
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** What a case is given, with every `$…` written as the value it stands for. */
|
|
68
|
+
async function inputs(value: unknown): Promise<Record<string, unknown>> {
|
|
69
|
+
return await input(value) as Record<string, unknown>
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
async function input(value: unknown): Promise<unknown> {
|
|
73
|
+
if (Array.isArray(value)) return Promise.all(value.map(input))
|
|
74
|
+
if (value === null || typeof value !== "object") return value
|
|
75
|
+
const record = value as Record<string, unknown>
|
|
76
|
+
if ("$picture" in record) return picture(record.$picture as Picture)
|
|
77
|
+
if ("$u8" in record) return Uint8Array.from(record.$u8 as number[])
|
|
78
|
+
if ("$f32" in record) return Float32Array.from(record.$f32 as number[])
|
|
79
|
+
if ("$call" in record) return opts.provider.call(record.$call as string, await inputs(record.given ?? {}))
|
|
80
|
+
return Object.fromEntries(await Promise.all(Object.entries(record).map(async ([key, item]) => [key, await input(item)])))
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** A picture written in a case: one colour all over, or the raw RGB bytes of a file beside the cases. */
|
|
84
|
+
function picture(spec: Picture): { width: number; height: number; rgb: Uint8Array } {
|
|
85
|
+
const rgb = spec.file
|
|
86
|
+
? new Uint8Array(readFileSync(join(opts.dir, spec.file)))
|
|
87
|
+
: Uint8Array.from({ length: spec.width * spec.height * 3 }, (_, index) => spec.fill![index % 3]!)
|
|
88
|
+
if (rgb.length !== spec.width * spec.height * 3) throw err("SERVICE_INVALID", { detail: `a ${spec.width}×${spec.height} picture holds ${spec.width * spec.height * 3} bytes, not ${rgb.length}` })
|
|
89
|
+
return { width: spec.width, height: spec.height, rgb: rgb }
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
type Picture = { width: number; height: number; fill?: [number, number, number]; file?: string }
|
|
94
|
+
|
|
95
|
+
/** The cases beside an interface. */
|
|
96
|
+
function cases(dir: string): Case[] {
|
|
97
|
+
const parsed: unknown = JSON.parse(readFileSync(join(dir, "cases.json"), "utf8"))
|
|
98
|
+
if (!Array.isArray(parsed) || parsed.some(one => typeof one !== "object" || one === null || typeof one.name !== "string" || typeof one.given !== "object" || !("expect" in one) || (typeof one.call !== "string" && typeof one.stream !== "string"))) {
|
|
99
|
+
throw err("SERVICE_INVALID", { detail: `${dir}/cases.json is a list of { name, call | stream, given, expect, within? }` })
|
|
100
|
+
}
|
|
101
|
+
return parsed as Case[]
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Whether `value` is what `expected` says, every way it is not added to
|
|
106
|
+
* `problems`. An object of fields checks each; `{ min, max }`, `{ oneOf }`,
|
|
107
|
+
* `{ type }`, `{ length }` and `{ each }` check what they name; anything else
|
|
108
|
+
* must be equal — a number within its field's tolerance.
|
|
109
|
+
*/
|
|
110
|
+
function check(value: unknown, expected: unknown, path: string, within: Record<string, number>, answer: unknown, problems: string[]): void {
|
|
111
|
+
const at = path || "the answer"
|
|
112
|
+
if (expected !== null && typeof expected === "object" && !Array.isArray(expected)) {
|
|
113
|
+
const rule = expected as Record<string, unknown>
|
|
114
|
+
const keys = Object.keys(rule)
|
|
115
|
+
const rules = ["min", "max", "oneOf", "type", "length", "each"]
|
|
116
|
+
if (keys.length > 0 && keys.every(key => rules.includes(key))) {
|
|
117
|
+
if (rule.type !== undefined && typeof value !== rule.type) problems.push(`${at} is ${typeof value}, not ${rule.type}`)
|
|
118
|
+
if (rule.min !== undefined && !(typeof value === "number" && value >= (rule.min as number))) problems.push(`${at} is ${JSON.stringify(value)}, below ${rule.min}`)
|
|
119
|
+
if (rule.max !== undefined && !(typeof value === "number" && value <= (rule.max as number))) problems.push(`${at} is ${JSON.stringify(value)}, above ${rule.max}`)
|
|
120
|
+
if (rule.oneOf !== undefined && !(rule.oneOf as unknown[]).includes(value)) problems.push(`${at} is ${JSON.stringify(value)}, not one of ${JSON.stringify(rule.oneOf)}`)
|
|
121
|
+
if (rule.length !== undefined) {
|
|
122
|
+
const length = lengthOf(value)
|
|
123
|
+
if (length === null) problems.push(`${at} has no length`)
|
|
124
|
+
else check(length, typeof rule.length === "string" ? product(rule.length, answer) : rule.length, `${at}.length`, within, answer, problems)
|
|
125
|
+
}
|
|
126
|
+
if (rule.each !== undefined) {
|
|
127
|
+
const items = listed(value)
|
|
128
|
+
if (items === null) problems.push(`${at} is not a list`)
|
|
129
|
+
else {
|
|
130
|
+
// One problem per kind is enough: a mask of a million wrong values says so once.
|
|
131
|
+
const seen: string[] = []
|
|
132
|
+
items.forEach((item, index) => check(item, rule.each, `${at}[${index}]`, within, answer, seen))
|
|
133
|
+
if (seen.length > 0) problems.push(`${seen[0]}${seen.length > 1 ? ` (and ${seen.length - 1} more)` : ""}`)
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
return
|
|
137
|
+
}
|
|
138
|
+
if (value === null || typeof value !== "object") {
|
|
139
|
+
problems.push(`${at} is ${JSON.stringify(value)}, not an object`)
|
|
140
|
+
return
|
|
141
|
+
}
|
|
142
|
+
for (const [key, inner] of Object.entries(rule)) check((value as Record<string, unknown>)[key], inner, path ? `${path}.${key}` : key, within, answer, problems)
|
|
143
|
+
return
|
|
144
|
+
}
|
|
145
|
+
if (typeof expected === "number" && typeof value === "number") {
|
|
146
|
+
const tolerance = within[path.split(".").at(-1) ?? ""] ?? 0
|
|
147
|
+
if (Math.abs(value - expected) > tolerance) problems.push(`${at} is ${value}, not ${expected}${tolerance ? ` within ${tolerance}` : ""}`)
|
|
148
|
+
return
|
|
149
|
+
}
|
|
150
|
+
if (Array.isArray(expected)) {
|
|
151
|
+
const items = listed(value)
|
|
152
|
+
if (!items || items.length !== expected.length) problems.push(`${at} is ${JSON.stringify(value)}, not ${expected.length} long`)
|
|
153
|
+
else expected.forEach((item, index) => check(items[index], item, path, within, answer, problems))
|
|
154
|
+
return
|
|
155
|
+
}
|
|
156
|
+
if (value !== expected) problems.push(`${at} is ${JSON.stringify(value)}, not ${JSON.stringify(expected)}`)
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function lengthOf(value: unknown): number | null {
|
|
160
|
+
if (typeof value === "string" || Array.isArray(value)) return value.length
|
|
161
|
+
if (ArrayBuffer.isView(value)) return (value as unknown as { length: number }).length
|
|
162
|
+
return null
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function listed(value: unknown): unknown[] | null {
|
|
166
|
+
if (Array.isArray(value)) return value
|
|
167
|
+
if (ArrayBuffer.isView(value)) return Array.from(value as unknown as ArrayLike<number>)
|
|
168
|
+
return null
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** `"width*height"` — the product of the answer's own fields, for a length that depends on them. */
|
|
172
|
+
function product(expression: string, answer: unknown): number {
|
|
173
|
+
return expression.split("*").reduce((total, field) => {
|
|
174
|
+
const value = (answer as Record<string, unknown>)[field.trim()]
|
|
175
|
+
if (typeof value !== "number") throw err("SERVICE_INVALID", { detail: `a length of "${expression}" needs the answer's ${field.trim()}, which is ${JSON.stringify(value)}` })
|
|
176
|
+
return total * value
|
|
177
|
+
}, 1)
|
|
178
|
+
}
|