@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,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"