@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.
Files changed (39) hide show
  1. package/README.md +31 -0
  2. package/package.json +37 -0
  3. package/src/Axon.ts +260 -0
  4. package/src/cognet/cognet.ts +318 -0
  5. package/src/cognet/index.ts +4 -0
  6. package/src/index.ts +11 -0
  7. package/src/modules/context.ts +90 -0
  8. package/src/modules/index.ts +6 -0
  9. package/src/modules/load.ts +119 -0
  10. package/src/modules/modules.ts +87 -0
  11. package/src/modules/setup.ts +91 -0
  12. package/src/platform/blueprint.ts +201 -0
  13. package/src/platform/boot.ts +160 -0
  14. package/src/platform/bus.ts +207 -0
  15. package/src/platform/hooks.ts +30 -0
  16. package/src/platform/index.ts +18 -0
  17. package/src/platform/inject.ts +236 -0
  18. package/src/runtime/handle.ts +283 -0
  19. package/src/runtime/index.ts +2 -0
  20. package/src/runtime/inference.ts +221 -0
  21. package/src/runtime/runtime.ts +207 -0
  22. package/src/runtime/server/connect-auth.ts +123 -0
  23. package/src/runtime/server/endpoints.ts +257 -0
  24. package/src/runtime/server/h3.ts +33 -0
  25. package/src/runtime/server/index.ts +8 -0
  26. package/src/runtime/server/middleware.ts +59 -0
  27. package/src/runtime/server/plugins.ts +23 -0
  28. package/src/runtime/server/routes.ts +33 -0
  29. package/src/runtime/server/server.ts +138 -0
  30. package/src/runtime/server/session-view.ts +100 -0
  31. package/src/runtime/server/sse.ts +45 -0
  32. package/src/runtime/server/streams.ts +186 -0
  33. package/src/runtime/source/context.ts +67 -0
  34. package/src/runtime/source/render.ts +90 -0
  35. package/src/runtime/source/scripts.ts +55 -0
  36. package/src/tools/index.ts +11 -0
  37. package/src/tools/load.ts +119 -0
  38. package/src/tools/mediate.ts +92 -0
  39. 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,2 @@
1
+ export { AxonHandle } from "./handle"
2
+ export { AxonRuntime } from "./runtime"
@@ -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
+ }