@arcforge/core 2.0.166
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -0
- package/package.json +37 -0
- package/src/Axon.ts +260 -0
- package/src/cognet/cognet.ts +318 -0
- package/src/cognet/index.ts +4 -0
- package/src/index.ts +11 -0
- package/src/modules/context.ts +90 -0
- package/src/modules/index.ts +6 -0
- package/src/modules/load.ts +119 -0
- package/src/modules/modules.ts +87 -0
- package/src/modules/setup.ts +91 -0
- package/src/platform/blueprint.ts +201 -0
- package/src/platform/boot.ts +160 -0
- package/src/platform/bus.ts +207 -0
- package/src/platform/hooks.ts +30 -0
- package/src/platform/index.ts +18 -0
- package/src/platform/inject.ts +236 -0
- package/src/runtime/handle.ts +283 -0
- package/src/runtime/index.ts +2 -0
- package/src/runtime/inference.ts +221 -0
- package/src/runtime/runtime.ts +207 -0
- package/src/runtime/server/connect-auth.ts +123 -0
- package/src/runtime/server/endpoints.ts +257 -0
- package/src/runtime/server/h3.ts +33 -0
- package/src/runtime/server/index.ts +8 -0
- package/src/runtime/server/middleware.ts +59 -0
- package/src/runtime/server/plugins.ts +23 -0
- package/src/runtime/server/routes.ts +33 -0
- package/src/runtime/server/server.ts +138 -0
- package/src/runtime/server/session-view.ts +100 -0
- package/src/runtime/server/sse.ts +45 -0
- package/src/runtime/server/streams.ts +186 -0
- package/src/runtime/source/context.ts +67 -0
- package/src/runtime/source/render.ts +90 -0
- package/src/runtime/source/scripts.ts +55 -0
- package/src/tools/index.ts +11 -0
- package/src/tools/load.ts +119 -0
- package/src/tools/mediate.ts +92 -0
- package/src/tools/tools.ts +88 -0
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
import type { AxonCloudClient } from "@arcforge/cloud"
|
|
2
|
+
import { err } from "@arcforge/err"
|
|
3
|
+
import type { AxonBlueprint as AxonBlueprintT, AxonPartialBlueprint } from "@arcforge/types"
|
|
4
|
+
import { AxonBusT, AxonHooksT, mergeBlueprint } from "../platform"
|
|
5
|
+
import type { AxonHandle } from "./handle"
|
|
6
|
+
import { AxonKernelT } from "@arcforge/kernel"
|
|
7
|
+
import type { AxonSessionT } from "@arcforge/session"
|
|
8
|
+
import type { ModulesT } from "../modules"
|
|
9
|
+
import { AxonServer } from "./server"
|
|
10
|
+
|
|
11
|
+
type AxonRuntimeOpts = {
|
|
12
|
+
blueprint: AxonBlueprintT
|
|
13
|
+
cloud: AxonCloudClient
|
|
14
|
+
axon: ReturnType<typeof AxonHandle>
|
|
15
|
+
kernel: AxonKernelT
|
|
16
|
+
/** Environmental — constructed at the Axon() seam, not kernel-owned. Every runtime-level commit goes through this directly. */
|
|
17
|
+
session: AxonSessionT
|
|
18
|
+
/** The raw event bus — trusted-host-only (devtools/TUI live event streaming via onAny). Never on AxonHandle. */
|
|
19
|
+
bus: AxonBusT
|
|
20
|
+
hooks: AxonHooksT
|
|
21
|
+
/** Live module set — reloaded on update(), disposed on shutdown(). */
|
|
22
|
+
modules: ModulesT
|
|
23
|
+
/** Date.now() captured at the top of Axon() — axon:boot:complete measures from here. */
|
|
24
|
+
bootStarted: number
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Final assembly. Axon() only composes the pieces — this is where the
|
|
29
|
+
* composed runtime gets one coherent shape, one canonical blueprint, and
|
|
30
|
+
* one shutdown path.
|
|
31
|
+
*
|
|
32
|
+
* The runtime owns the current blueprint. update() merges + re-normalizes
|
|
33
|
+
* exactly once, then hands every handle the same complete new blueprint —
|
|
34
|
+
* handles decide locally whether to react, but they can never diverge on
|
|
35
|
+
* what the agent currently is.
|
|
36
|
+
*
|
|
37
|
+
* kernel and session are siblings on the returned handle, for trusted host
|
|
38
|
+
* code only (TUI, CLI, tests) — never on `axon` (AxonHandle), which is the
|
|
39
|
+
* curated, sandboxed surface agent-authored scripts see. A script reaches
|
|
40
|
+
* `axon.request(...)`; a host reaches `runtime.kernel.request(...)` or
|
|
41
|
+
* `runtime.session` directly when it genuinely needs the execution or
|
|
42
|
+
* memory surface itself. The kernel was never meant to be reached FOR
|
|
43
|
+
* session access (that was the original design mistake this fixes) — it's
|
|
44
|
+
* fine as a first-class sibling for its own purpose, execution/OS
|
|
45
|
+
* orchestration. No thread concept anywhere here: one session is always
|
|
46
|
+
* exactly one continuous entry log.
|
|
47
|
+
*/
|
|
48
|
+
export async function AxonRuntime(opts: AxonRuntimeOpts) {
|
|
49
|
+
const session = opts.session
|
|
50
|
+
let blueprint = opts.blueprint
|
|
51
|
+
let revision = 0
|
|
52
|
+
let server = await AxonServer({ blueprint, hooks: opts.hooks, axon: opts.axon, bus: opts.bus, session, ...(opts.kernel.engines ? { engines: opts.kernel.engines } : {}) })
|
|
53
|
+
|
|
54
|
+
const runtime = {
|
|
55
|
+
axon: opts.axon,
|
|
56
|
+
kernel: opts.kernel,
|
|
57
|
+
session: session,
|
|
58
|
+
bus: opts.bus,
|
|
59
|
+
cloud: opts.cloud,
|
|
60
|
+
|
|
61
|
+
get blueprint() {
|
|
62
|
+
return blueprint
|
|
63
|
+
},
|
|
64
|
+
|
|
65
|
+
/** The live fetch handler — rebuilt on every update(), so callers must re-read it after a reload rather than caching it. */
|
|
66
|
+
get server() {
|
|
67
|
+
return server
|
|
68
|
+
},
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Hot-reload trigger. One canonical merge here; the kernel fans the
|
|
72
|
+
* full new blueprint out to its own organs (engine, loop, capsule).
|
|
73
|
+
* Server is rebuilt too — new/changed routes and middleware only
|
|
74
|
+
* take effect through a freshly constructed h3 app.
|
|
75
|
+
*
|
|
76
|
+
* The whole span lands in the session log — axon:reload:start, then
|
|
77
|
+
* axon:reload:complete or axon:reload:failed. Failure both records AND
|
|
78
|
+
* rethrows: durable for the UI, loud for the caller.
|
|
79
|
+
*/
|
|
80
|
+
async update(partial: AxonPartialBlueprint, updateOpts?: { mode?: "merge" | "replace" }) {
|
|
81
|
+
const started = Date.now()
|
|
82
|
+
const nextRevision = revision + 1
|
|
83
|
+
await session.commit("axon:reload:start", { revision: nextRevision })
|
|
84
|
+
|
|
85
|
+
try {
|
|
86
|
+
blueprint = mergeBlueprint(blueprint, partial, updateOpts?.mode)
|
|
87
|
+
await opts.axon.update(blueprint)
|
|
88
|
+
|
|
89
|
+
// Reload order is load-bearing. AxonServer() resets ALL hooks
|
|
90
|
+
// and re-runs plugins on every build — which would wipe hooks a
|
|
91
|
+
// module registered in setup(). So: dispose old module
|
|
92
|
+
// resources first, rebuild the server (resets hooks, re-runs
|
|
93
|
+
// plugins), THEN re-run module setup so its hooks land after
|
|
94
|
+
// the reset and survive. Reload stays shutdown+boot for
|
|
95
|
+
// modules — just interleaved with the server rebuild.
|
|
96
|
+
await opts.modules.dispose()
|
|
97
|
+
server = await AxonServer({ blueprint, hooks: opts.hooks, axon: opts.axon, bus: opts.bus, session, ...(opts.kernel.engines ? { engines: opts.kernel.engines } : {}) })
|
|
98
|
+
await opts.modules.setup(blueprint)
|
|
99
|
+
|
|
100
|
+
// The session log owns the runtime transaction; the entry
|
|
101
|
+
// log owns the cognition-visible causal fact. One durable
|
|
102
|
+
// generic system interaction per successful reload means AIR
|
|
103
|
+
// does not need a hot-reload-specific timeline primitive.
|
|
104
|
+
await session.commitEntry("axon:system:message", {
|
|
105
|
+
type: "hot-reload",
|
|
106
|
+
lang: "txt",
|
|
107
|
+
content: "Agent context hot-reloaded. The currently resolved system and scope are authoritative; account for any changes before continuing.",
|
|
108
|
+
attributes: { revision: String(nextRevision) },
|
|
109
|
+
})
|
|
110
|
+
|
|
111
|
+
await session.commit("axon:reload:complete", {
|
|
112
|
+
revision: nextRevision,
|
|
113
|
+
durationMs: Date.now() - started,
|
|
114
|
+
toolCount: blueprint.tools.length,
|
|
115
|
+
})
|
|
116
|
+
revision = nextRevision
|
|
117
|
+
} catch (cause) {
|
|
118
|
+
const failure = err(cause)
|
|
119
|
+
await session.commit("axon:reload:failed", { revision: nextRevision, error: failure, durationMs: Date.now() - started })
|
|
120
|
+
throw failure
|
|
121
|
+
}
|
|
122
|
+
},
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Teardown is error-isolated: one handle failing to shut down never
|
|
126
|
+
* leaves the others running. Collected failures rethrow at the end.
|
|
127
|
+
* session.end() runs last, unconditionally — a failed kernel
|
|
128
|
+
* shutdown must never skip flushing the log.
|
|
129
|
+
*
|
|
130
|
+
* The whole span lands in the session log — axon:shutdown:start, then
|
|
131
|
+
* axon:shutdown:complete or axon:shutdown:failed — same shape as update()'s
|
|
132
|
+
* axon:reload:start/complete/failed.
|
|
133
|
+
*/
|
|
134
|
+
async shutdown(reason?: string) {
|
|
135
|
+
const started = Date.now()
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Phase timing for the shutdown-hang investigation.
|
|
139
|
+
*
|
|
140
|
+
* Shutdown is a chain of unbounded awaits over code we do not all
|
|
141
|
+
* own (module dispose, cognet unload, capsule teardown), and the
|
|
142
|
+
* observed freeze scales with SESSION LENGTH — which points at an
|
|
143
|
+
* O(entries) walk rather than a stuck handler. Naming the phase is
|
|
144
|
+
* the difference between fixing that walk and hiding it behind a
|
|
145
|
+
* timeout.
|
|
146
|
+
*
|
|
147
|
+
* Writes to stderr because the TTY is already being torn down by
|
|
148
|
+
* the time later phases run, and the session log is one of the
|
|
149
|
+
* things being closed.
|
|
150
|
+
*/
|
|
151
|
+
const trace = process.env.AXON_SHUTDOWN_TRACE === "1"
|
|
152
|
+
let mark = Date.now()
|
|
153
|
+
const phase = (name: string): void => {
|
|
154
|
+
if (!trace) return
|
|
155
|
+
const now = Date.now()
|
|
156
|
+
process.stderr.write(`[shutdown] ${name} ${now - mark}ms (total ${now - started}ms)\n`)
|
|
157
|
+
mark = now
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
await session.commit("axon:shutdown:start", { reason })
|
|
161
|
+
phase("commit:start")
|
|
162
|
+
await opts.hooks.callHook("shutdown:before")
|
|
163
|
+
phase("hooks:shutdown:before")
|
|
164
|
+
|
|
165
|
+
const failures: unknown[] = []
|
|
166
|
+
|
|
167
|
+
for (const [name, close] of [
|
|
168
|
+
// Modules first — release external connections (Discord gateway,
|
|
169
|
+
// timers) in reverse order before the capsule that hosts tool
|
|
170
|
+
// code is torn down.
|
|
171
|
+
["modules", () => opts.modules.dispose()],
|
|
172
|
+
["kernel", () => opts.kernel.shutdown()], // abort run → kill userland
|
|
173
|
+
] as const) {
|
|
174
|
+
try {
|
|
175
|
+
await close()
|
|
176
|
+
phase(name)
|
|
177
|
+
} catch (cause) {
|
|
178
|
+
phase(`${name}:failed`)
|
|
179
|
+
failures.push(err("HANDLE_SHUTDOWN_FAILED", { detail: `${name} shutdown failed`, context: { name }, cause }))
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
if (failures.length > 0) {
|
|
184
|
+
const failure = err(new AggregateError(failures, "runtime shutdown completed with failures"))
|
|
185
|
+
await session.commit("axon:shutdown:failed", { error: failure, durationMs: Date.now() - started })
|
|
186
|
+
await session.end()
|
|
187
|
+
throw failure
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
await session.commit("axon:shutdown:complete", { durationMs: Date.now() - started })
|
|
191
|
+
phase("commit:complete")
|
|
192
|
+
await session.end()
|
|
193
|
+
phase("session:end")
|
|
194
|
+
},
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// Durable session-log commit (forwards to the bus itself) — a bare
|
|
198
|
+
// bus.emit would notify live listeners but never persist, leaving the
|
|
199
|
+
// session record with no boot fact at all.
|
|
200
|
+
await session.commit("axon:boot:complete", { durationMs: Date.now() - opts.bootStarted })
|
|
201
|
+
|
|
202
|
+
// lifecycle hook — plugins registering boot:after expect the runtime
|
|
203
|
+
// to actually wait on them before Axon() resolves
|
|
204
|
+
await opts.hooks.callHook("boot:after")
|
|
205
|
+
|
|
206
|
+
return runtime
|
|
207
|
+
}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { createError, getHeader, type H3Event } from "h3"
|
|
2
|
+
import { importSPKI, jwtVerify } from "jose"
|
|
3
|
+
import { isConnectScope, type ConnectGrant, type ConnectScope } from "@arcforge/types"
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* ConnectAuth — the gate in front of the agent's own /_axon surface.
|
|
7
|
+
*
|
|
8
|
+
* A deployed agent is a separate process with no database, so it cannot
|
|
9
|
+
* answer "may this caller talk to me" from first principles. It does not have
|
|
10
|
+
* to: the control plane already answered, once, when it minted the caller's
|
|
11
|
+
* token. What arrives here is a CAPABILITY — signed by the backend's private
|
|
12
|
+
* key, addressed to this agent by id, and valid for minutes — so the check is
|
|
13
|
+
* a local signature verification. No network call, no shared database, no
|
|
14
|
+
* dependency on the control plane being reachable.
|
|
15
|
+
*
|
|
16
|
+
* This replaces a design where the agent POSTed the caller's bearer token to
|
|
17
|
+
* the backend on every request. That cost a round trip per message, chained
|
|
18
|
+
* the agent's availability to the backend's, and — the real problem — meant
|
|
19
|
+
* the thing presented to the agent was the caller's own full credential,
|
|
20
|
+
* valid against every other agent and every backend route. A connect token is
|
|
21
|
+
* valid for exactly one agent and nothing else.
|
|
22
|
+
*
|
|
23
|
+
* WHEN THE GATE IS OPEN. With no public key configured — local dev, tests, an
|
|
24
|
+
* agent run outside the deploy pipeline — there is nothing to verify against
|
|
25
|
+
* and the gate is open: a locally-run agent is already inside its owner's
|
|
26
|
+
* trust boundary. It engages for a real deployment, which is exactly where
|
|
27
|
+
* the /_axon surface is publicly reachable. `AXON_JWT_PUBLIC_KEY` is injected
|
|
28
|
+
* into every Cloud Run deployment, so "deployed" and "enforcing" coincide.
|
|
29
|
+
*
|
|
30
|
+
* Health is never gated — the startup probe hits it before any caller exists.
|
|
31
|
+
*/
|
|
32
|
+
export type ConnectAuth = {
|
|
33
|
+
/**
|
|
34
|
+
* Throws 401/403 if the request may not proceed; resolves the grant when
|
|
35
|
+
* it may. Returns null when the gate is open — no token was required, so
|
|
36
|
+
* there is no grant to report.
|
|
37
|
+
*/
|
|
38
|
+
require(event: H3Event, scope: ConnectScope): Promise<ConnectGrant | null>
|
|
39
|
+
/** Whether the gate is actually enforcing (a verification key was configured). */
|
|
40
|
+
readonly enforcing: boolean
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
type ConnectAuthOpts = {
|
|
44
|
+
/** RS256 public key PEM. Absent → gate open. */
|
|
45
|
+
publicKey?: string
|
|
46
|
+
/** This agent's registry id — the audience every accepted token must name. Absent → gate open. */
|
|
47
|
+
agentId?: string
|
|
48
|
+
/** The expected `iss`. Defaults to the platform issuer. */
|
|
49
|
+
issuer?: string
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const DEFAULT_ISSUER = "axon-backend"
|
|
53
|
+
|
|
54
|
+
export function ConnectAuth(opts: ConnectAuthOpts): ConnectAuth {
|
|
55
|
+
const enforcing = Boolean(opts.publicKey && opts.agentId)
|
|
56
|
+
const issuer = opts.issuer ?? DEFAULT_ISSUER
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Parsed once. The PEM never changes, and this sits on the request path of
|
|
60
|
+
* every call to a deployed agent — a key import per request would be a
|
|
61
|
+
* self-inflicted cost.
|
|
62
|
+
*/
|
|
63
|
+
let keyPromise: Promise<CryptoKey> | null = null
|
|
64
|
+
|
|
65
|
+
function key(): Promise<CryptoKey> {
|
|
66
|
+
// Env vars carry PEMs with escaped newlines; a real PEM needs them back.
|
|
67
|
+
keyPromise ??= importSPKI(opts.publicKey!.replace(/\\n/g, "\n"), "RS256")
|
|
68
|
+
return keyPromise
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
async function require(event: H3Event, scope: ConnectScope): Promise<ConnectGrant | null> {
|
|
72
|
+
if (!enforcing) return null
|
|
73
|
+
|
|
74
|
+
const header = getHeader(event, "authorization")
|
|
75
|
+
const token = header?.startsWith("Bearer ") ? header.slice(7) : null
|
|
76
|
+
if (!token) {
|
|
77
|
+
throw createError({ statusCode: 401, statusMessage: "connect: missing bearer token" })
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
let grant: ConnectGrant
|
|
81
|
+
try {
|
|
82
|
+
// jwtVerify checks the signature, `iss`, `aud` and `exp` together.
|
|
83
|
+
// Audience is the load-bearing one: a token minted for another
|
|
84
|
+
// agent has a perfectly valid signature and must still be refused.
|
|
85
|
+
const { payload } = await jwtVerify(token, await key(), {
|
|
86
|
+
issuer,
|
|
87
|
+
audience: opts.agentId!,
|
|
88
|
+
algorithms: ["RS256"],
|
|
89
|
+
})
|
|
90
|
+
|
|
91
|
+
if (typeof payload.sub !== "string" || typeof payload.exp !== "number") {
|
|
92
|
+
throw createError({ statusCode: 401, statusMessage: "connect: token is missing required claims" })
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const claimed = Array.isArray(payload.scope) ? payload.scope : []
|
|
96
|
+
grant = {
|
|
97
|
+
user: payload.sub,
|
|
98
|
+
agent: opts.agentId!,
|
|
99
|
+
scopes: claimed.filter((value): value is ConnectScope => typeof value === "string" && isConnectScope(value)),
|
|
100
|
+
expiresAt: payload.exp,
|
|
101
|
+
}
|
|
102
|
+
} catch (cause) {
|
|
103
|
+
if (isH3Error(cause)) throw cause
|
|
104
|
+
// Every verification failure — bad signature, wrong audience,
|
|
105
|
+
// expired, malformed — is one 401. Distinguishing them for the
|
|
106
|
+
// caller would only help someone probing for which part they got
|
|
107
|
+
// wrong; the agent's own log carries the detail.
|
|
108
|
+
throw createError({ statusCode: 401, statusMessage: "connect: invalid or expired token" })
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
if (!grant.scopes.includes(scope)) {
|
|
112
|
+
throw createError({ statusCode: 403, statusMessage: `connect: token does not grant "${scope}"` })
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
return grant
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
return { require, enforcing }
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function isH3Error(value: unknown): boolean {
|
|
122
|
+
return typeof value === "object" && value !== null && "statusCode" in value
|
|
123
|
+
}
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
import { createError, defineEventHandler, getQuery, readBody, setResponseStatus } from "h3"
|
|
2
|
+
import type { AxonBlueprint, AxonHandle, AxonRequestInput } from "@arcforge/types"
|
|
3
|
+
import type { EnginesT } from "@arcforge/engines/catalogue"
|
|
4
|
+
import type { AxonBusT } from "../../platform"
|
|
5
|
+
import { ConnectAuth } from "./connect-auth"
|
|
6
|
+
import { H3T } from "./h3"
|
|
7
|
+
import { parseQuery, snapshot } from "./session-view"
|
|
8
|
+
import { eventStream, runStream } from "./streams"
|
|
9
|
+
|
|
10
|
+
type EndpointsOpts = {
|
|
11
|
+
h3: H3T
|
|
12
|
+
axon: AxonHandle
|
|
13
|
+
/** Raw bus — /_axon/events bridges it to SSE. Trusted-host-only, never on AxonHandle. */
|
|
14
|
+
bus: AxonBusT
|
|
15
|
+
blueprint: AxonBlueprint
|
|
16
|
+
/**
|
|
17
|
+
* The agent's resolved inference roles, for the health endpoint's
|
|
18
|
+
* `engine` field. Absent when the cognet declared none.
|
|
19
|
+
*/
|
|
20
|
+
engines?: EnginesT
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Endpoints — the framework-reserved `/_axon/*` surface every agent exposes,
|
|
25
|
+
* independent of user-authored routes. This is the normalized wire contract a
|
|
26
|
+
* remote client (AxonCloud.attach) speaks to: it never depends on what routes
|
|
27
|
+
* the agent's author did or didn't write.
|
|
28
|
+
*
|
|
29
|
+
* Mounted BEFORE user routes and under the reserved `/_axon` prefix, so an
|
|
30
|
+
* agent can never shadow or collide with it — the contract is guaranteed
|
|
31
|
+
* present on every deployment.
|
|
32
|
+
*
|
|
33
|
+
* GET /_axon/health — readiness. 200 once the runtime is serving.
|
|
34
|
+
* POST /_axon/request — one-shot invocation. body {prompt} → AxonResult JSON.
|
|
35
|
+
* POST /_axon/stream — streaming invocation. body {prompt} → SSE of AxonEntry.
|
|
36
|
+
* GET /_axon/session — session snapshot (history). ?since/?limit/?include.
|
|
37
|
+
* GET /_axon/events — ambient bus stream (live). Replays from ?since, then live.
|
|
38
|
+
*
|
|
39
|
+
* These mirror AxonHandle.request/stream exactly, so a RemoteAgent built on
|
|
40
|
+
* them is transport-transparent for those verbs. Authoring verbs (update,
|
|
41
|
+
* hooks) are deliberately absent — they are meaningless against a remote
|
|
42
|
+
* instance.
|
|
43
|
+
*
|
|
44
|
+
* The two read surfaces pair up: /session is state-at-a-point, /events is the
|
|
45
|
+
* ordered stream, and `time.seq` joins them. /events replays from a cursor, so a
|
|
46
|
+
* client can use it alone and skip /session entirely.
|
|
47
|
+
*
|
|
48
|
+
* Routing only. The projection each endpoint returns lives in session-view.ts,
|
|
49
|
+
* the two live wires in streams.ts, the SSE mechanics in sse.ts.
|
|
50
|
+
*/
|
|
51
|
+
/**
|
|
52
|
+
* The engine an agent declares, flattened for the wire.
|
|
53
|
+
*
|
|
54
|
+
* Two shapes reach here and mean the same thing: an EngineRef
|
|
55
|
+
* (`{ provider, model }`) and a constructed AxonEngineDef, whose provider is
|
|
56
|
+
* `name`. A client rendering them differently would make the model row's
|
|
57
|
+
* meaning depend on which form the author's config happened to use, so they
|
|
58
|
+
* are collapsed at this seam rather than downstream.
|
|
59
|
+
*
|
|
60
|
+
* Null when the agent declares nothing — distinct from a provider with no
|
|
61
|
+
* model, which is a real state (`{ provider: "mock" }`).
|
|
62
|
+
*/
|
|
63
|
+
/**
|
|
64
|
+
* What the agent's PRIMARY role actually resolved to.
|
|
65
|
+
*
|
|
66
|
+
* Reports the binding rather than a declaration, because nothing is declared
|
|
67
|
+
* any more: a user supplies providers, a cognet names roles, and which model
|
|
68
|
+
* serves the cortex is decided at boot. A client rendering "the model this
|
|
69
|
+
* agent is on" wants that answer, and there is no other place to get it.
|
|
70
|
+
*
|
|
71
|
+
* Null when the cognet declares no roles, or none is primary — a pure control
|
|
72
|
+
* loop genuinely has no model, and inventing one would put a dead row in
|
|
73
|
+
* every client's header.
|
|
74
|
+
*/
|
|
75
|
+
function engineIdentity(
|
|
76
|
+
engines: EnginesT | undefined,
|
|
77
|
+
declared: { provider: string; model: string | null } | undefined,
|
|
78
|
+
): { provider: string; model: string | null } | null {
|
|
79
|
+
// The blueprint's answer first.
|
|
80
|
+
//
|
|
81
|
+
// A CONFINED agent has no engines of its own: resolving needs the
|
|
82
|
+
// credential, which the boundary deliberately keeps on the supervisor's
|
|
83
|
+
// side. So the supervisor resolves, stamps the result on the blueprint,
|
|
84
|
+
// and this reads it. Preferring the kernel here reported `null` on every
|
|
85
|
+
// agent that was answering prompts perfectly well — the field looked
|
|
86
|
+
// broken while the agent was fine.
|
|
87
|
+
if (declared) return declared
|
|
88
|
+
|
|
89
|
+
// In-heap: nobody stamped anything, so resolve it from the live bindings.
|
|
90
|
+
const bound = engines?.resolution.bound
|
|
91
|
+
if (!bound?.length) return null
|
|
92
|
+
|
|
93
|
+
const primary = bound.find(entry => entry.requirement.primary) ?? bound.find(entry => entry.role === "main")
|
|
94
|
+
if (!primary) return null
|
|
95
|
+
|
|
96
|
+
return { provider: primary.capability.provider, model: primary.capability.id }
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
export function Endpoints(opts: EndpointsOpts) {
|
|
100
|
+
const { h3, axon } = opts
|
|
101
|
+
const router = h3.router
|
|
102
|
+
|
|
103
|
+
// The connect gate — verifies the caller's capability token locally
|
|
104
|
+
// against the public key this deployment was given. Enforces only when
|
|
105
|
+
// both the key and this agent's id are present (a real deployment); open
|
|
106
|
+
// locally, where there is nothing to verify against and the agent is
|
|
107
|
+
// already inside its owner's trust boundary. Env comes from the blueprint
|
|
108
|
+
// — the runtime never reads process.env directly.
|
|
109
|
+
const auth = ConnectAuth({
|
|
110
|
+
...(opts.blueprint.env.AXON_JWT_PUBLIC_KEY ? { publicKey: opts.blueprint.env.AXON_JWT_PUBLIC_KEY } : {}),
|
|
111
|
+
...(opts.blueprint.env.AGENT_ID ? { agentId: opts.blueprint.env.AGENT_ID } : {}),
|
|
112
|
+
})
|
|
113
|
+
|
|
114
|
+
// health carries the instance's session id so a client's attach handshake
|
|
115
|
+
// resolves "which instance am I bound to" up front (mirrors local session.id).
|
|
116
|
+
// Never gated — the startup probe hits it before any caller is authorized.
|
|
117
|
+
// Readiness, not liveness. `ok` used to be the literal `true`, so an agent
|
|
118
|
+
// whose brain failed to load answered 200 forever: the process was up, the
|
|
119
|
+
// routes served, the log filled with reload failures, and nothing outside
|
|
120
|
+
// could tell. A health check that cannot fail is not a health check.
|
|
121
|
+
//
|
|
122
|
+
// 503 is the honest status for "running but cannot serve its purpose" —
|
|
123
|
+
// it is what a load balancer needs to stop sending work, and what a human
|
|
124
|
+
// needs to stop trusting the green light.
|
|
125
|
+
// `agent` is the identity a client shows for what it attached TO. A caller
|
|
126
|
+
// that typed a URL has nothing else to render — "localhost:3010" in the
|
|
127
|
+
// slot where an agent name belongs is a hostname pretending to be an
|
|
128
|
+
// identity. A deployment already knows the name from its record; a bare
|
|
129
|
+
// URL can only learn it here, and the handshake is the one round trip
|
|
130
|
+
// every attach already makes.
|
|
131
|
+
router.get("/_axon/health", defineEventHandler(event => {
|
|
132
|
+
const ready = axon.ready
|
|
133
|
+
if (!ready) setResponseStatus(event, 503)
|
|
134
|
+
return {
|
|
135
|
+
ok: ready,
|
|
136
|
+
sessionId: axon.session.id,
|
|
137
|
+
agent: opts.blueprint.agent.name,
|
|
138
|
+
// What this agent is carrying. A client that attached over the
|
|
139
|
+
// wire has no blueprint to read — it never built this agent and
|
|
140
|
+
// never will — so the counts have to come from the agent itself
|
|
141
|
+
// or not exist. No duration: how long the build took is a fact
|
|
142
|
+
// about the process that ran it, and claiming it for a caller
|
|
143
|
+
// that only watched would be someone else's number.
|
|
144
|
+
modules: opts.blueprint.modules?.length ?? 0,
|
|
145
|
+
tools: opts.blueprint.tools?.length ?? 0,
|
|
146
|
+
// The primary role's RESOLVED binding — see engineIdentity.
|
|
147
|
+
engine: engineIdentity(opts.engines, opts.blueprint.engine),
|
|
148
|
+
// The AUDIENCE a caller must mint a connect token for, when this
|
|
149
|
+
// agent enforces one.
|
|
150
|
+
//
|
|
151
|
+
// Without it a client had to be TOLD the agent id out of band, so
|
|
152
|
+
// `:attach <url>` — which has only a URL — sent no token at all and
|
|
153
|
+
// got a bare 401 from any gated route. The assumption underneath
|
|
154
|
+
// was "local means open", which stopped being true the moment
|
|
155
|
+
// local staging started deploying through the real pipeline: those
|
|
156
|
+
// agents are local AND enforcing.
|
|
157
|
+
//
|
|
158
|
+
// Not a secret. It is the id in the owner's own dashboard, and it
|
|
159
|
+
// grants nothing: the backend still decides whether the caller may
|
|
160
|
+
// have a token for it, and the token it mints is scoped by `aud`
|
|
161
|
+
// to this one agent for minutes. Publishing it turns an
|
|
162
|
+
// unactionable 401 into "ask for a token for this".
|
|
163
|
+
//
|
|
164
|
+
// Absent when the gate is open, which is the honest signal that no
|
|
165
|
+
// token is needed rather than one the client must guess at.
|
|
166
|
+
...(auth.enforcing && opts.blueprint.env.AGENT_ID
|
|
167
|
+
? { agentId: opts.blueprint.env.AGENT_ID }
|
|
168
|
+
: {}),
|
|
169
|
+
...(ready ? {} : { reason: "no cognet loaded" }),
|
|
170
|
+
}
|
|
171
|
+
}))
|
|
172
|
+
|
|
173
|
+
// Body is parsed BEFORE the auth check, then the action runs only AFTER it.
|
|
174
|
+
//
|
|
175
|
+
// This looks backwards and is not. Verification awaits — the RS256 public
|
|
176
|
+
// key is imported asynchronously on first use — and h3's request body
|
|
177
|
+
// cannot be read across an await boundary: the stream is already disturbed
|
|
178
|
+
// by the time the handler resumes, and the read fails. So the body is
|
|
179
|
+
// taken first, while the request is still intact.
|
|
180
|
+
//
|
|
181
|
+
// Safe, because parsing is not acting: readInput does a bounded JSON parse
|
|
182
|
+
// and nothing else. The agent is never INVOKED until the gate passes, which
|
|
183
|
+
// is the property that matters.
|
|
184
|
+
router.post("/_axon/request", defineEventHandler(async event => {
|
|
185
|
+
const input = await readInput(event)
|
|
186
|
+
await auth.require(event, "request")
|
|
187
|
+
return await axon.request(input)
|
|
188
|
+
}))
|
|
189
|
+
|
|
190
|
+
router.post("/_axon/stream", defineEventHandler(async event => {
|
|
191
|
+
const input = await readInput(event)
|
|
192
|
+
await auth.require(event, "stream")
|
|
193
|
+
return runStream(event, axon.stream(input))
|
|
194
|
+
}))
|
|
195
|
+
|
|
196
|
+
// The session snapshot — what makes a deployed agent render identically to a
|
|
197
|
+
// local one. A remote client has no in-process session to read, so it
|
|
198
|
+
// hydrates from here on attach and appends from the stream afterwards.
|
|
199
|
+
// Gated: unlike /health (which the startup probe hits pre-auth), this is the
|
|
200
|
+
// agent's whole conversation and telemetry.
|
|
201
|
+
router.get("/_axon/session", defineEventHandler(async event => {
|
|
202
|
+
await auth.require(event, "read")
|
|
203
|
+
return snapshot(axon, parseQuery(getQuery(event)))
|
|
204
|
+
}))
|
|
205
|
+
|
|
206
|
+
// The ambient event channel — the runtime bus, over the wire. A remote
|
|
207
|
+
// client subscribes here and routes events into its mirrored session
|
|
208
|
+
// exactly as a local consumer routes bus.onAny(), which is what makes a
|
|
209
|
+
// deployed agent observable with no second code path.
|
|
210
|
+
//
|
|
211
|
+
// Distinct from POST /_axon/stream on purpose: that is request-scoped (it
|
|
212
|
+
// tells you YOUR turn finished and owns interrupt() for YOUR wake). This is
|
|
213
|
+
// everything happening in the session, including events between turns that a
|
|
214
|
+
// request-scoped stream can never see.
|
|
215
|
+
router.get("/_axon/events", defineEventHandler(async event => {
|
|
216
|
+
await auth.require(event, "read")
|
|
217
|
+
return eventStream(event, {
|
|
218
|
+
bus: opts.bus,
|
|
219
|
+
session: axon.session,
|
|
220
|
+
query: parseQuery(getQuery(event)),
|
|
221
|
+
})
|
|
222
|
+
}))
|
|
223
|
+
|
|
224
|
+
return {
|
|
225
|
+
mounted: [
|
|
226
|
+
"GET /_axon/health",
|
|
227
|
+
"POST /_axon/request",
|
|
228
|
+
"POST /_axon/stream",
|
|
229
|
+
"GET /_axon/session",
|
|
230
|
+
"GET /_axon/events",
|
|
231
|
+
],
|
|
232
|
+
enforcing: auth.enforcing,
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* Normalize the request body into AxonRequestInput. A bare string body, a
|
|
238
|
+
* `{ prompt }` object, or a `{ prompt: string[] }` batch are all accepted — the
|
|
239
|
+
* same shapes AxonHandle.request takes — so the wire and the local call agree.
|
|
240
|
+
* A body with no usable prompt is a 400 at this boundary, not a runtime throw.
|
|
241
|
+
*/
|
|
242
|
+
async function readInput(event: Parameters<typeof readBody>[0]): Promise<AxonRequestInput> {
|
|
243
|
+
const body = await readBody(event).catch(() => undefined)
|
|
244
|
+
|
|
245
|
+
if (typeof body === "string") return { prompt: body }
|
|
246
|
+
if (body && typeof body === "object" && "prompt" in body) {
|
|
247
|
+
const prompt = (body as { prompt: unknown }).prompt
|
|
248
|
+
if (typeof prompt === "string" || Array.isArray(prompt)) {
|
|
249
|
+
return { prompt: prompt as string | string[] }
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
throw createError({
|
|
254
|
+
statusCode: 400,
|
|
255
|
+
statusMessage: "_axon/request: body must be a string or { prompt: string | string[] }",
|
|
256
|
+
})
|
|
257
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { createApp, createRouter, toWebHandler, EventHandler } from "h3"
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Owns everything h3-specific: app/router construction, mounting the
|
|
5
|
+
* router onto the app, and serving. Middleware/Modules/Routes/Plugins
|
|
6
|
+
* only ever touch the `app`/`router` handles this hands them — they
|
|
7
|
+
* never construct or serve h3 themselves.
|
|
8
|
+
*/
|
|
9
|
+
export function H3() {
|
|
10
|
+
const app = createApp()
|
|
11
|
+
const router = createRouter()
|
|
12
|
+
|
|
13
|
+
return {
|
|
14
|
+
app,
|
|
15
|
+
router,
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Mount onto the app — call once, after all routes/middleware are
|
|
19
|
+
* registered. Defaults to the bare router; pass a wrapping handler
|
|
20
|
+
* to observe the router's resolution (e.g. request:after, which
|
|
21
|
+
* must run once the route handler has actually resolved).
|
|
22
|
+
*/
|
|
23
|
+
mount(handler: EventHandler = router.handler) {
|
|
24
|
+
app.use(handler)
|
|
25
|
+
},
|
|
26
|
+
|
|
27
|
+
/** convert to a web-standard fetch handler for Bun.serve or any web-fetch runtime */
|
|
28
|
+
toFetchHandler() {
|
|
29
|
+
return toWebHandler(app)
|
|
30
|
+
},
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
export type H3T = ReturnType<typeof H3>
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server — the agent's HTTP surface.
|
|
3
|
+
*
|
|
4
|
+
* AxonServer() is the only thing outside this folder should reach for; the
|
|
5
|
+
* appliers (middleware, plugins, routes), the reserved /_axon endpoints, and
|
|
6
|
+
* the SSE machinery are its internals.
|
|
7
|
+
*/
|
|
8
|
+
export { AxonServer } from "./server"
|