@arcforge/core 2.0.218 → 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.
@@ -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
+ }
@@ -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 { AxonHooksT, Inject } from "../platform"
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
- try {
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. A cognet plugin drives kernel.tick() from inside the brain.
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
 
@@ -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 carriedSlot = opts.blueprint.cognet
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 (!declared || Object.keys(declared).length === 0) return undefined
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 carried = opts.blueprint.cognet
96
- const requirements = carried.engines
97
- ?? ("definition" in carried ? carried.definition.engines : undefined)
119
+ const { requirements, pins } = roles(opts.blueprint)
98
120
 
99
- if (!requirements || Object.keys(requirements).length === 0) {
121
+ if (Object.keys(requirements).length === 0) {
100
122
  return { engines: undefined, providers: 0, failures: 0, cached: false }
101
123
  }
102
124
 
103
- const pool = providerPool(opts.blueprint.profileProviders, opts.blueprint.config.providers)
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 } as never,
202
- () => provider.catalogue(),
203
- (capabilities: EngineCapability[]) => ({
204
- provider: provider.name,
205
- spanId,
206
- capabilities: capabilities.length,
207
- cached: catalogueWasCached(provider),
208
- }) as never,
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: { provider: string; model: string | null } | undefined,
78
- ): { provider: string; model: string | null } | null {
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 { AxonEventView, AxonHandle, AxonSessionQuery } from "@arcforge/types"
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
+ }
@@ -0,0 +1,4 @@
1
+ // services — the machine's engines as providers of the standard interfaces, and how a use is granted.
2
+
3
+ export { STANDARD } from "./standard"
4
+ export { granted, engineRoles, checked, type Granted } from "./resolve"