@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,90 @@
1
+ import { readFile } from "node:fs/promises"
2
+ import { err } from "@arcforge/err"
3
+ import type { vstr as Vstr } from "@arcforge/vstr"
4
+ import { AxonBlueprint, type AxonPrompt } from "@arcforge/types"
5
+ import { promptContext } from "./context"
6
+
7
+ /**
8
+ * `@arcforge/vstr` carries the whole Vue toolchain (@vue/compiler-sfc,
9
+ * runtime-core, server-renderer, turndown) — ~280ms of module evaluation, paid
10
+ * at IMPORT time by anything that reached the runtime. Only .vue prompts need
11
+ * it, so an agent with none, and every request that renders a static prompt,
12
+ * was paying for a compiler it never called.
13
+ *
14
+ * Loaded on first render and memoised: the cost moves to the first .vue
15
+ * render and is never paid twice.
16
+ */
17
+ let vstrModule: Promise<{ vstr: typeof Vstr }> | null = null
18
+ function loadVstr(): Promise<{ vstr: typeof Vstr }> {
19
+ vstrModule ??= import("@arcforge/vstr")
20
+ return vstrModule
21
+ }
22
+
23
+
24
+ type PromptOpts = {
25
+ blueprint: AxonBlueprint
26
+ }
27
+
28
+ /**
29
+ * Renders a prompt by name. Static .md is read as-is; dynamic .vue renders
30
+ * through Vuedown with the given props. Fs is always available at runtime
31
+ * (GCS FUSE mount in prod), so rendering happens live, off the source path —
32
+ * no pre-compiled render functions, no CLI-side rendering step.
33
+ */
34
+ export function Prompt(opts: PromptOpts) {
35
+ async function render(name: string, props?: Record<string, unknown>) {
36
+ const entry = opts.blueprint.prompts.find(p => p.name === name)
37
+ if (!entry) throw err("PROMPT_NOT_FOUND", { context: { name } })
38
+ return renderEntry(entry, props)
39
+ }
40
+
41
+ /**
42
+ * Render a prompt this agent does not declare.
43
+ *
44
+ * The scope is still this agent's — `promptContext` below hands the
45
+ * template the live `axon` handle and the agent's own resolved env, which
46
+ * is the whole reason rendering belongs in the runtime. What it does NOT
47
+ * need is a blueprint entry: a prompt is content, addressed by an absolute
48
+ * path, and the only thing installing one ever bought was getting that
49
+ * path into `blueprint.prompts`. Cached prompts (~/.axon/cache/prompts)
50
+ * come through here instead of being installed into the agent.
51
+ */
52
+ async function renderEntry(entry: AxonPrompt, props?: Record<string, unknown>) {
53
+ if (!entry.filePath) throw err("PROMPT_FILE_NOT_FOUND", { context: { path: entry.filePath ?? "" } })
54
+ const name = entry.name
55
+
56
+ if (entry.kind === "static") {
57
+ return await readFile(entry.filePath, "utf-8")
58
+ }
59
+
60
+ // vstr is a generic tool (no @axon/err dependency) — it throws a plain
61
+ // Error on a malformed SFC or a render throw. Wrap it here, at the
62
+ // boundary, into the structured code so it renders as a proper AxonError
63
+ // in chat instead of a raw string.
64
+ try {
65
+ return await (await loadVstr()).vstr(entry.filePath, {
66
+ context: promptContext(),
67
+ // Resolved at scan time and carried on the entry. Without
68
+ // these, a prompt composing <Identity /> cannot resolve the
69
+ // tag and the whole render throws — components are inlined
70
+ // fragments, so a prompt that uses one is unrenderable
71
+ // without them.
72
+ ...(entry.components ? { components: entry.components } : {}),
73
+ }).render(props)
74
+ } catch (cause) {
75
+ throw err("PROMPT_RENDER_FAILED", { cause, context: { name, path: entry.filePath } })
76
+ }
77
+ }
78
+
79
+ return {
80
+ render: render,
81
+
82
+ /** Render a prompt entry this agent doesn't declare — a cached registry prompt. */
83
+ renderEntry: renderEntry,
84
+
85
+ /** Every prompt declared in the blueprint — name + kind, for enumeration (axon.prompts.list()). */
86
+ list() {
87
+ return opts.blueprint.prompts
88
+ },
89
+ }
90
+ }
@@ -0,0 +1,55 @@
1
+ import { existsSync } from "node:fs"
2
+ import { err } from "@arcforge/err"
3
+ import { AxonBlueprint } from "@arcforge/types"
4
+ import type { Inject } from "../../platform"
5
+
6
+ type ScriptsOpts = {
7
+ blueprint: AxonBlueprint
8
+ inject: ReturnType<typeof Inject>
9
+ }
10
+
11
+ /**
12
+ * Scripts run in-process, unsandboxed — trusted agent-authored orchestration,
13
+ * not untrusted execution. Sandboxing lives one layer down: a script that
14
+ * calls axon.tools.* gets policy enforcement there. Raw fs/node access from
15
+ * a script is the author's own risk, same as any Node script.
16
+ *
17
+ * A script is a top-level module, not a function export — running it IS
18
+ * importing it. `axon`/`args` are already globals by the time this runs
19
+ * (Inject().runtime() ran at boot); `args` is scoped per-call via
20
+ * withArgs() so concurrent script invocations never race each other's
21
+ * globalThis.args.
22
+ */
23
+ export function Scripts(opts: ScriptsOpts) {
24
+ function find(name: string) {
25
+ const entry = opts.blueprint.scripts.find(s => s.name === name)
26
+ if (!entry) throw err("SCRIPT_NOT_FOUND", { context: { name } })
27
+ if (!entry.filePath || !existsSync(entry.filePath)) {
28
+ throw err("SCRIPT_FILE_NOT_FOUND", { context: { path: entry.filePath ?? "" } })
29
+ }
30
+ return entry
31
+ }
32
+
33
+ async function invoke(name: string, args: Record<string, unknown> = {}) {
34
+ const entry = find(name)
35
+ // cache-bust: a script is top-level code, not a function — re-running
36
+ // it means re-executing that code, but dynamic import() caches by
37
+ // resolved specifier, so a second call would silently no-op without this.
38
+ // The same token identifies this invocation's args (see Inject.withArgs):
39
+ // ALS does not survive import(), so the run id is what a top-level
40
+ // `args` read resolves through.
41
+ const runId = crypto.randomUUID()
42
+ const specifier = `${entry.filePath}?run=${runId}`
43
+ return opts.inject.withArgs(runId, args, () => import(specifier))
44
+ }
45
+
46
+ return {
47
+ async request(name: string, args?: Record<string, unknown>) {
48
+ return await invoke(name, args)
49
+ },
50
+
51
+ list() {
52
+ return opts.blueprint.scripts
53
+ },
54
+ }
55
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * tools — the agent's executable scope, loaded in its own process.
3
+ *
4
+ * Replaces the capsule's split tool machinery (a guest-side loader plus a
5
+ * host-side wire handshake) with one in-process operation. The mediation
6
+ * wrapper survives intact: once the whole agent runs inside an OS box, bwrap
7
+ * is the security wall and this becomes the audit and escalation layer.
8
+ */
9
+ export { Tools, type ToolsT } from "./tools"
10
+ export { loadTool, type LoadedTool } from "./load"
11
+ export { mediate, type MediateOpts } from "./mediate"
@@ -0,0 +1,119 @@
1
+ import { mkdir, writeFile } from "node:fs/promises"
2
+ import { tmpdir } from "node:os"
3
+ import { join } from "node:path"
4
+ import { createHash } from "node:crypto"
5
+ import { err } from "@arcforge/err"
6
+ import type { AxonTool } from "@arcforge/types"
7
+ import { mediate, type MediateOpts } from "./mediate"
8
+
9
+ /** One tool module once loaded: its namespace and the mediated functions it exports. */
10
+ export type LoadedTool = {
11
+ namespace: string
12
+ values: Record<string, unknown>
13
+ }
14
+
15
+ /**
16
+ * Where a tool's code comes from.
17
+ *
18
+ * `source` is bundled text (what a project scan produces, imports inlined);
19
+ * `entryPath` is a real file on disk (programmatic blueprints that never went
20
+ * through the bundler). Bundled source wins when both are present.
21
+ *
22
+ * ACROSS THE OLD BOUNDARY, source was the point: the capsule materialized it
23
+ * INSIDE the sandbox so no tool file — and none of the project around it — was
24
+ * ever mounted into the box, which is what kept the sandbox filesystem exactly
25
+ * what the fs policy declared. In-process that reason is gone; the tool's own
26
+ * file is part of the agent, so it can simply be imported. Materializing is
27
+ * kept only because bundled source has no path to import, and it writes to the
28
+ * OS temp dir rather than into the agent's tree.
29
+ */
30
+ async function materialize(source: string): Promise<string> {
31
+ // Content-hashed: repeated loads of identical source (a reload, two agents
32
+ // sharing a module) reuse one file rather than leaking a new one per call.
33
+ // A data: URI cannot be used — real tool sources exceed the OS module
34
+ // specifier length ceiling and throw NameTooLong.
35
+ const dir = join(tmpdir(), "axon-tools")
36
+ await mkdir(dir, { recursive: true })
37
+ const file = join(dir, `${createHash("sha256").update(source).digest("hex")}.ts`)
38
+ await writeFile(file, source)
39
+ return file
40
+ }
41
+
42
+ /**
43
+ * Load one tool and mediate everything it exports.
44
+ *
45
+ * ── Failure is LOUD, and that is the substantive change ─────────────────────
46
+ *
47
+ * The capsule's loader caught every failure, emitted `process:tool:load:failed`
48
+ * and returned normally; the host's `build/tools.ts` listened for that event
49
+ * and rejected the build. Two halves of one decision, joined only by an event
50
+ * name crossing a wire — nothing in the type system connected them, and the
51
+ * catch read as correct defensive code in isolation.
52
+ *
53
+ * In-process there is no wire to carry the event, so that catch would become a
54
+ * silent swallow: a tool that failed to load would leave the agent running
55
+ * with a namespace the model has been told it can call. This throws instead.
56
+ * A capsule missing scope the agent was promised is invalid state, not a
57
+ * warning — which is exactly what the host half already believed.
58
+ */
59
+ export async function loadTool(tool: AxonTool, mediation: MediateOpts): Promise<LoadedTool> {
60
+ const specifier = tool.source !== undefined
61
+ ? await materialize(tool.source)
62
+ : tool.entryPath
63
+
64
+ if (!specifier) {
65
+ throw err("CAPSULE_TOOL_FAILED", {
66
+ detail: `"${tool.name}" has neither bundled source nor an entry path`,
67
+ context: { namespace: tool.name },
68
+ })
69
+ }
70
+
71
+ let mod: Record<string, unknown>
72
+ try {
73
+ mod = (await import(specifier)) as Record<string, unknown>
74
+ } catch (cause) {
75
+ throw err("CAPSULE_TOOL_FAILED", {
76
+ detail: `"${tool.name}" failed to load`,
77
+ context: { namespace: tool.name },
78
+ cause,
79
+ })
80
+ }
81
+
82
+ // Two authoring shapes: named exports, or a default object carrying an
83
+ // `exports` bag. Named wins when present — a tool with both is declaring
84
+ // its surface twice and the explicit one is the honest answer.
85
+ const fallback = mod.default as { exports?: Record<string, unknown> } | undefined
86
+ const named = Object.fromEntries(Object.entries(mod).filter(([name]) => name !== "default"))
87
+ const exported = Object.keys(named).length > 0 ? named : (fallback?.exports ?? {})
88
+
89
+ const values: Record<string, unknown> = {}
90
+ for (const [name, value] of Object.entries(exported)) {
91
+ // `<tool>.<export>` — the POLICY address, not the call path.
92
+ //
93
+ // Deliberately namespaced although the global is flat: a policy rule
94
+ // is written against the tool the user installed (`fs: { read: ... }`),
95
+ // and a bare export name would make one rule cover every module that
96
+ // happens to export `read`. The caller says `read(...)`; the mediator
97
+ // asks about `fs.read`. Must match the capsule's own path (see
98
+ // process/scope.ts) or the two enforcement points would key policy
99
+ // differently.
100
+ const path = `${tool.name}.${name}`
101
+ values[name] = mediate(mediation, value, path, tool.name)
102
+ }
103
+
104
+ // The scope contract: what the model was TOLD it can call must be what
105
+ // actually loaded. A mismatch means the <scope> block and the editor's
106
+ // .d.ts describe functions that do not exist, so the model calls one and
107
+ // gets "not defined" — checked here rather than trusted, exactly as the
108
+ // capsule's build handshake checked it across the wire.
109
+ const declared = tool.fns.map(fn => fn.name).sort()
110
+ const loaded = Object.keys(values).sort()
111
+ if (declared.length !== loaded.length || declared.some((name, i) => name !== loaded[i])) {
112
+ throw err("CAPSULE_TOOL_SCOPE_MISMATCH", {
113
+ detail: `"${tool.name}" declares [${declared.join(", ")}] but exports [${loaded.join(", ")}]`,
114
+ context: { namespace: tool.name, declared, loaded },
115
+ })
116
+ }
117
+
118
+ return { namespace: tool.name, values }
119
+ }
@@ -0,0 +1,92 @@
1
+ import type { PolicyRule } from "@arcforge/types"
2
+
3
+ /**
4
+ * The mediation wrapper — every tool call passes through here before it runs.
5
+ *
6
+ * Lifted from the capsule's `process/scope.ts`, unchanged in substance: it
7
+ * recursively proxies callables so no caller can ever reach an unwrapped
8
+ * function, checks policy, and brackets the call with fn:start/complete/failed
9
+ * spans. That logic was never about the process boundary; it works identically
10
+ * whether the tool lives across a wire or in this heap, which is why it moves
11
+ * intact rather than being rewritten.
12
+ *
13
+ * ── What changes, and what deliberately does not ────────────────────────────
14
+ *
15
+ * What changes is the mediator's ROLE. In the capsule it was the security
16
+ * boundary. Once the whole agent runs inside an OS box, bwrap is the wall — a
17
+ * path outside the policy does not exist, a denied network has no socket — and
18
+ * this becomes the AUDIT and ESCALATION layer: typed denials the agent can
19
+ * reason about, human-in-the-loop prompts the OS cannot express, and the span
20
+ * stream Fleet folds into its flame graph.
21
+ *
22
+ * What does not change is that it still runs. A demoted mediator is not a
23
+ * removed one: the OS wall cannot say "ask the user about this one command",
24
+ * and a denial that arrives as ENOENT teaches the model nothing.
25
+ */
26
+
27
+ export type MediateOpts = {
28
+ /**
29
+ * Policy check for one call. Resolves allow/deny; an escalation is awaited
30
+ * inside it, so this promise settling means the verdict is final.
31
+ */
32
+ check(fn: string, subject: string, args: unknown[], owner: string): Promise<boolean>
33
+ /** Span emission — the audit trail every surface reads. */
34
+ emit: {
35
+ start(input: { module: string; fn: string; args: unknown[] }): void
36
+ complete(input: { module: string; fn: string; result: unknown; durationMs: number }): void
37
+ failed(input: { module: string; fn: string; error: unknown; durationMs: number }): void
38
+ }
39
+ }
40
+
41
+ /**
42
+ * Wrap one exported value so every call beneath it is mediated.
43
+ *
44
+ * Recursive by necessity: a tool may export an object of functions, or an
45
+ * object of objects. Wrapping only the top level would leave `github.pr.open`
46
+ * unmediated while `github.open` was checked — the kind of gap that is
47
+ * invisible until someone finds it.
48
+ *
49
+ * `receiver` carries the original `this` through Reflect.apply, so a tool
50
+ * written as a class method or an object literal using `this` keeps working.
51
+ */
52
+ export function mediate(opts: MediateOpts, value: unknown, path: string, owner: string, receiver?: object): unknown {
53
+ if (typeof value === "function") {
54
+ return async (...args: unknown[]) => {
55
+ // The first string argument is what a glob rule matches against —
56
+ // a path, a host, a command. A tool taking no string simply has
57
+ // nothing to match, and the rule's bare verdict decides.
58
+ const subject = typeof args[0] === "string" ? args[0] : ""
59
+ const allowed = await opts.check(path, subject, args, owner)
60
+ if (!allowed) throw new Error(`CAPSULE_POLICY_DENIED: ${path} denied by policy`)
61
+
62
+ // The span opens only AFTER policy admits the call: a denied call
63
+ // is a policy fact, not an execution that failed, and pairing a
64
+ // :start with no matching end would leave a permanently-open
65
+ // bracket in every flame graph.
66
+ const started = Date.now()
67
+ opts.emit.start({ module: owner, fn: path, args })
68
+ try {
69
+ const result = await Reflect.apply(value as (...a: unknown[]) => unknown, receiver, args)
70
+ opts.emit.complete({ module: owner, fn: path, result, durationMs: Date.now() - started })
71
+ return result
72
+ } catch (cause) {
73
+ opts.emit.failed({ module: owner, fn: path, error: cause, durationMs: Date.now() - started })
74
+ throw cause
75
+ }
76
+ }
77
+ }
78
+
79
+ if (value !== null && typeof value === "object") {
80
+ return new Proxy(value, {
81
+ get(target, key) {
82
+ const child = Reflect.get(target, key, target)
83
+ return typeof key === "string" ? mediate(opts, child, `${path}.${key}`, owner, target) : child
84
+ },
85
+ })
86
+ }
87
+
88
+ return value
89
+ }
90
+
91
+ /** Re-exported so a caller can name the rule shape without reaching for types. */
92
+ export type { PolicyRule }
@@ -0,0 +1,88 @@
1
+ import type { AxonTool } from "@arcforge/types"
2
+ import { isLoadable } from "@arcforge/kernel"
3
+ import { loadTool, type LoadedTool } from "./load"
4
+ import type { MediateOpts } from "./mediate"
5
+
6
+ type ToolsOpts = {
7
+ mediation: MediateOpts
8
+ }
9
+
10
+ /**
11
+ * Tools — the agent's own executable scope, loaded into its own process.
12
+ *
13
+ * This is the in-process replacement for the capsule's tool machinery: the
14
+ * guest-side `Scope()` that loaded and wrapped modules, plus the host-side
15
+ * `build/tools.ts` that sent `tool:load` and awaited a confirmation event.
16
+ * Those were one operation split across a wire; here they are one function.
17
+ *
18
+ * ── What this deletes downstream ────────────────────────────────────────────
19
+ *
20
+ * `axon.tools.foo.bar()` from a script currently serialises its arguments into
21
+ * a string, embeds them in synthesised TypeScript, ships that over JSONL, and
22
+ * evals it in another process — because the capsule's only conversation is
23
+ * `run(code)` and there is no per-function RPC. In one heap a tool call is a
24
+ * function call, so that bridge (`runtime/source/tools.ts::callTool`) has
25
+ * nothing left to do.
26
+ *
27
+ * The tool boundary is gone; the tool SCOPE is not. What the model is told it
28
+ * can call stays a curated declaration derived from the blueprint
29
+ * (kernel/src/scope.ts), never a reflection of whatever happens to be in the
30
+ * process — otherwise the model would see `require`, `globalThis` and every
31
+ * transitive dependency, and no editor `.d.ts` could ever be generated.
32
+ */
33
+ export function Tools(opts: ToolsOpts) {
34
+ const loaded = new Map<string, LoadedTool>()
35
+
36
+ return {
37
+ /**
38
+ * Load every loadable tool the blueprint declares.
39
+ *
40
+ * SEQUENTIAL, and it throws on the first failure. Both match what the
41
+ * capsule's build did: a capsule missing scope the agent was promised
42
+ * is invalid state, and continuing past a broken tool leaves the model
43
+ * holding a namespace that will fail at call time instead of at boot.
44
+ *
45
+ * `isLoadable` is the same predicate that produces the model's <scope>
46
+ * and the editor's ambient declarations — what can run, what the model
47
+ * is told it can call, and what an editor typechecks against are one
48
+ * list by construction.
49
+ */
50
+ async install(tools: AxonTool[]): Promise<void> {
51
+ for (const tool of tools.filter(isLoadable)) {
52
+ loaded.set(tool.name, await loadTool(tool, opts.mediation))
53
+ }
54
+ },
55
+
56
+ /** Drop one namespace — a hot reload removing a tool the author deleted. */
57
+ remove(namespace: string): void {
58
+ loaded.delete(namespace)
59
+ },
60
+
61
+ /** Drop everything, for a reload that rebuilds the whole set. */
62
+ clear(): void {
63
+ loaded.clear()
64
+ },
65
+
66
+ get namespaces(): string[] {
67
+ return [...loaded.keys()]
68
+ },
69
+
70
+ /**
71
+ * The globals model-emitted code and agent-authored code both execute
72
+ * against.
73
+ *
74
+ * Every export lands under its OWN name — `export function add()` is
75
+ * `add()`, `export const fs = {...}` is `fs.read()`. A tool's
76
+ * `namespace` is the file it came from, kept for diagnostics; it is
77
+ * never a prefix the caller addresses through. Same placement the
78
+ * editor's generated declarations assume.
79
+ */
80
+ globals(): Record<string, unknown> {
81
+ const globals: Record<string, unknown> = {}
82
+ for (const tool of loaded.values()) Object.assign(globals, tool.values)
83
+ return globals
84
+ },
85
+ }
86
+ }
87
+
88
+ export type ToolsT = ReturnType<typeof Tools>