@arcforge/platform 2.0.219 → 2.0.245

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 (127) hide show
  1. package/package.json +27 -19
  2. package/src/build/blueprint/blueprint.ts +48 -64
  3. package/src/build/blueprint/cognet/abi.ts +3 -257
  4. package/src/build/blueprint/cognet/bundle-worker.ts +11 -0
  5. package/src/build/blueprint/cognet/bundle.ts +294 -89
  6. package/src/build/blueprint/cognet/cognet.ts +8 -7
  7. package/src/build/blueprint/cognet/config/config.ts +52 -0
  8. package/src/build/blueprint/cognet/config/index.ts +4 -0
  9. package/src/build/blueprint/cognet/config/literal.ts +83 -0
  10. package/src/build/blueprint/cognet/config/provider.ts +43 -0
  11. package/src/build/blueprint/cognet/config/shape.ts +183 -0
  12. package/src/build/blueprint/cognet/index.ts +4 -2
  13. package/src/build/blueprint/cognet/native/cargo.ts +31 -0
  14. package/src/build/blueprint/cognet/native/crate.ts +126 -0
  15. package/src/build/blueprint/cognet/native/index.ts +2 -0
  16. package/src/build/blueprint/cognet/native/library.ts +125 -0
  17. package/src/build/blueprint/cognet/native/manifest.ts +137 -0
  18. package/src/build/blueprint/cognet/python/index.ts +1 -0
  19. package/src/build/blueprint/cognet/python/project.ts +119 -0
  20. package/src/build/blueprint/cognet/schema/arrays.ts +23 -0
  21. package/src/build/blueprint/cognet/schema/authored.ts +273 -0
  22. package/src/build/blueprint/cognet/schema/compile.ts +78 -0
  23. package/src/build/blueprint/cognet/schema/components/external.ts +15 -0
  24. package/src/build/blueprint/cognet/schema/components/index.ts +3 -0
  25. package/src/build/blueprint/cognet/schema/components/lock.ts +58 -0
  26. package/src/build/blueprint/cognet/schema/components/model.ts +34 -0
  27. package/src/build/blueprint/cognet/schema/components/python.ts +15 -0
  28. package/src/build/blueprint/cognet/schema/components/python_source.py +69 -0
  29. package/src/build/blueprint/cognet/schema/components/rust.ts +33 -0
  30. package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.lock +117 -0
  31. package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.toml +11 -0
  32. package/src/build/blueprint/cognet/schema/components/rust_source/src/main.rs +104 -0
  33. package/src/build/blueprint/cognet/schema/components/source.ts +220 -0
  34. package/src/build/blueprint/cognet/schema/components/tags.ts +66 -0
  35. package/src/build/blueprint/cognet/schema/components/typescript.ts +157 -0
  36. package/src/build/blueprint/cognet/schema/index.ts +5 -0
  37. package/src/build/blueprint/cognet/schema/interfaces/index.ts +3 -0
  38. package/src/build/blueprint/cognet/schema/interfaces/source.ts +218 -0
  39. package/src/build/blueprint/cognet/schema/python.ts +260 -0
  40. package/src/build/blueprint/cognet/schema/rust.ts +316 -0
  41. package/src/build/blueprint/cognet/schema/schema.ts +248 -0
  42. package/src/build/blueprint/cognet/schema/typescript.ts +352 -0
  43. package/src/build/blueprint/index.ts +1 -1
  44. package/src/build/blueprint/modules/index.ts +7 -5
  45. package/src/build/blueprint/modules/meta.ts +47 -3
  46. package/src/build/blueprint/scan/config.ts +22 -16
  47. package/src/build/blueprint/scan/provider-globals.ts +46 -0
  48. package/src/build/blueprint/scan/providers.ts +25 -0
  49. package/src/build/blueprint/scan/tools.ts +21 -15
  50. package/src/build/extensions/edit.ts +66 -2
  51. package/src/build/extensions/extensions.ts +16 -3
  52. package/src/build/extensions/index.ts +1 -1
  53. package/src/build/project/bundle/agent.ts +26 -17
  54. package/src/build/project/bundle/source.ts +2 -2
  55. package/src/build/project/create/cognet.ts +84 -33
  56. package/src/build/project/create/profile.ts +13 -3
  57. package/src/build/project/index.ts +1 -1
  58. package/src/build/project/installer.ts +6 -5
  59. package/src/build/project/kinds.ts +4 -0
  60. package/src/build/project/manifest/env.ts +10 -0
  61. package/src/build/project/models/blobs/blobs.ts +57 -0
  62. package/src/build/project/models/blobs/index.ts +1 -0
  63. package/src/build/project/models/fetch.ts +46 -51
  64. package/src/build/project/models/index.ts +2 -1
  65. package/src/build/project/models/models.ts +12 -38
  66. package/src/build/project/models/onnx.ts +82 -0
  67. package/src/build/project/models/specifier.ts +9 -3
  68. package/src/build/project/models/storage/index-store.ts +27 -0
  69. package/src/build/project/models/storage/index.ts +1 -0
  70. package/src/build/project/models/store.ts +21 -16
  71. package/src/build/project/prepare.ts +82 -27
  72. package/src/build/project/project.ts +8 -14
  73. package/src/build/project/projects.ts +12 -1
  74. package/src/build/project/tree.ts +13 -3
  75. package/src/build/project/treecache.ts +8 -4
  76. package/src/build/project/typegen/axon-dts.ts +18 -0
  77. package/src/build/project/typegen/cognet-dts.ts +248 -59
  78. package/src/build/project/typegen/prompt-dts.ts +2 -3
  79. package/src/build/project/typegen/registry-dts.ts +2 -2
  80. package/src/build/project/typegen/tsconfig.ts +13 -13
  81. package/src/build/project/typegen/tui-dts.ts +3 -4
  82. package/src/build/project/typegen/workspace-scripts.ts +8 -7
  83. package/src/build/project/typegen/write.ts +15 -2
  84. package/src/build/project/watcher.ts +27 -0
  85. package/src/build/runtime/agent.ts +102 -63
  86. package/src/build/runtime/conformance.ts +25 -0
  87. package/src/build/runtime/escalations.ts +3 -8
  88. package/src/build/runtime/index.ts +2 -0
  89. package/src/build/runtime/instances.ts +7 -4
  90. package/src/build/runtime/progress.ts +6 -2
  91. package/src/build/runtime/reload-watch.ts +11 -8
  92. package/src/debug/README.md +398 -0
  93. package/src/debug/debug.ts +101 -0
  94. package/src/debug/events.ts +156 -0
  95. package/src/debug/graph.ts +94 -0
  96. package/src/debug/index.ts +5 -0
  97. package/src/debug/indexer.ts +286 -0
  98. package/src/debug/inference.ts +53 -0
  99. package/src/debug/log.ts +68 -0
  100. package/src/debug/overview.ts +78 -0
  101. package/src/debug/perf.ts +75 -0
  102. package/src/debug/resources.ts +125 -0
  103. package/src/debug/ring.ts +31 -0
  104. package/src/debug/sessions.ts +90 -0
  105. package/src/debug/signs.ts +119 -0
  106. package/src/debug/tally.ts +44 -0
  107. package/src/debug/types.ts +146 -0
  108. package/src/index.ts +9 -0
  109. package/src/link/agent-main.ts +36 -10
  110. package/src/link/index.ts +1 -1
  111. package/src/link/services.ts +88 -57
  112. package/src/platform.ts +17 -25
  113. package/src/services/cloud.ts +1 -4
  114. package/src/services/control/client.ts +1 -1
  115. package/src/services/control/server.ts +1 -1
  116. package/src/services/index.ts +1 -0
  117. package/src/services/ollama/daemon.ts +23 -0
  118. package/src/services/ollama/http.ts +7 -1
  119. package/src/services/ollama/ollama.ts +8 -14
  120. package/src/services/probe/ask.ts +139 -0
  121. package/src/services/probe/index.ts +3 -0
  122. package/src/services/providers.ts +18 -0
  123. package/src/services/resources/hardware.ts +15 -18
  124. package/src/services/resources/resources.ts +4 -5
  125. package/src/services/store/types.ts +3 -0
  126. package/src/services/running/index.ts +0 -1
  127. package/src/services/running/running.ts +0 -216
@@ -0,0 +1,352 @@
1
+ import { dirname, relative } from "node:path"
2
+ import { getOption, isMessage, ScalarType, toJson, type DescEnum, type DescExtension, type DescField, type DescFile, type DescMessage, type FileRegistry, type JsonValue } from "@bufbuild/protobuf"
3
+ import { err } from "@arcforge/err"
4
+ import { arrayOf } from "./arrays"
5
+
6
+ /** What emitting one schema file needs to know beyond it. */
7
+ export type Context = {
8
+ registry: FileRegistry
9
+ /** The module generated for a schema file's types: its absolute path, without extension. */
10
+ types(file: DescFile): string
11
+ /** The module generated for a schema file's handles: its absolute path, without extension. */
12
+ handles(file: DescFile): string
13
+ /** Where the frame a schema names is defined: its module (absolute, no extension) and its export. Throws on none, or two. */
14
+ frame(name: string): { module: string; exported: string }
15
+ }
16
+
17
+ /** The header every generated module starts with — what `Schema` recognises as its own when cleaning up. */
18
+ export const HEADER = "// Generated by axon prepare from"
19
+
20
+ /**
21
+ * TypeScript — one schema file as the TypeScript a cognet is written
22
+ * against, in two modules. Its TYPES — enums as string unions with their
23
+ * values listed, messages as plain types — are plain data, importable from
24
+ * pure code and tests. Its HANDLES — components as `component<T>(...)`,
25
+ * frames as `frame(...)` — need the runtime's globals, exactly as an author's
26
+ * hand-written ones did, so discovery names them, typegen types them and the
27
+ * bundle imports them as before. Plain functions, no I/O.
28
+ *
29
+ * Values stay plain data: a `repeated double` of fixed length is a tuple, one
30
+ * marked `array` a `Float64Array`, an enum is its text, an `optional` field
31
+ * may be absent. Nothing generated
32
+ * wraps a value in a class, so a system writes `{ count: 1, at: now }`.
33
+ */
34
+ export const typescript = {
35
+ /** The modules for `file`, whose source is `named` (its path as it is imported): its types, and its handles when it declares any. */
36
+ file(file: DescFile, named: string, context: Context): { types: string; handles: string | null } {
37
+ const types = Module({ file: file, context: context, part: "types" })
38
+ const handles = Module({ file: file, context: context, part: "handles" })
39
+ const typeLines: string[] = []
40
+ const handleLines: string[] = []
41
+ for (const one of file.enums) typeLines.push(...types.enumeration(one))
42
+ for (const one of file.messages) {
43
+ typeLines.push(...types.message(one))
44
+ handleLines.push(...handles.message(one))
45
+ }
46
+ const head = (out: ReturnType<typeof Module>) => [`${HEADER} ${named} — edit the schema, not this file.`, ...out.imports(), "", ...docs.file(file)]
47
+ return {
48
+ types: [...head(types), ...typeLines].join("\n"),
49
+ handles: handleLines.length ? [...head(handles), ...handleLines].join("\n") : null,
50
+ }
51
+ },
52
+ }
53
+
54
+ /** One module being written — a file's types, or its handles: what it has to import, and how it says each thing. */
55
+ function Module(opts: { file: DescFile; context: Context; part: "types" | "handles" }) {
56
+ const { file, context } = opts
57
+ const here = opts.part === "types" ? context.types(file) : context.handles(file)
58
+ /** Imports by module, each name with whether it is only a type. */
59
+ const wanted = new Map<string, Map<string, boolean>>()
60
+ const ext = {
61
+ components: extension(context.registry, "cognet.components"),
62
+ frames: extension(context.registry, "cognet.frames"),
63
+ component: extension(context.registry, "cognet.component"),
64
+ frame: extension(context.registry, "cognet.frame"),
65
+ fixed: extension(context.registry, "cognet.fixed"),
66
+ keys: extension(context.registry, "cognet.keys"),
67
+ text: extension(context.registry, "cognet.text"),
68
+ union: extension(context.registry, "cognet.union"),
69
+ optional: extension(context.registry, "cognet.optional"),
70
+ nullable: extension(context.registry, "cognet.nullable"),
71
+ array: extension(context.registry, "cognet.array"),
72
+ }
73
+
74
+ function want(module: string, name: string, typeOnly: boolean): void {
75
+ if (module === here) return
76
+ const names = wanted.get(module) ?? new Map<string, boolean>()
77
+ names.set(name, (names.get(name) ?? true) && typeOnly)
78
+ wanted.set(module, names)
79
+ }
80
+
81
+ /** The TypeScript name of a message or enum, imported when another schema defines it. */
82
+ function named(desc: DescMessage | DescEnum): string {
83
+ const name = names.local(desc)
84
+ want(context.types(desc.file), name, true)
85
+ return name
86
+ }
87
+
88
+ function type(field: DescField): string {
89
+ if (booleanOption(field, ext.array)) return arrayOf(field, numberOption(field, ext.fixed)).typescript
90
+ switch (field.fieldKind) {
91
+ case "scalar":
92
+ return names.scalar(field.scalar, field)
93
+ case "enum":
94
+ return named(field.enum)
95
+ case "message":
96
+ return named(field.message)
97
+ case "list": {
98
+ const element = field.listKind === "scalar" ? names.scalar(field.scalar, field) : field.listKind === "enum" ? named(field.enum) : named(field.message)
99
+ const fixed = numberOption(field, ext.fixed)
100
+ return fixed > 0 ? `[${new Array<string>(fixed).fill(element).join(", ")}]` : `${element}[]`
101
+ }
102
+ case "map": {
103
+ const value = field.mapKind === "scalar" ? names.scalar(field.scalar, field) : field.mapKind === "enum" ? named(field.enum) : named(field.message)
104
+ const keys = stringOption(field, ext.keys)
105
+ if (keys) return `Partial<Record<${named(enumNamed(keys, field))}, ${value}>>`
106
+ return `Record<${field.mapKey === ScalarType.STRING ? "string" : "number"}, ${value}>`
107
+ }
108
+ }
109
+ }
110
+
111
+ function enumNamed(name: string, field: DescField): DescEnum {
112
+ const found = context.registry.getEnum(name) ?? context.registry.getEnum(`${field.parent.file.proto.package}.${name}`)
113
+ if (!found) throw invalid(field, `its keys name the enum "${name}", which no schema defines`)
114
+ return found
115
+ }
116
+
117
+ return {
118
+ imports(): string[] {
119
+ return [...wanted].sort(([a], [b]) => (a < b ? -1 : 1)).map(([module, names]) => {
120
+ const all = [...names].sort(([a], [b]) => (a < b ? -1 : 1))
121
+ const typeOnly = all.every(([, only]) => only)
122
+ const list = all.map(([name, only]) => (typeOnly || !only ? name : `type ${name}`)).join(", ")
123
+ return `import ${typeOnly ? "type " : ""}{ ${list} } from ${JSON.stringify(specifier(here, module))}`
124
+ })
125
+ },
126
+
127
+ enumeration(desc: DescEnum): string[] {
128
+ const name = names.local(desc)
129
+ const values = desc.values.filter(value => !(value.number === 0 && value.name.endsWith("_UNSPECIFIED"))).map(value => {
130
+ const text = stringOption(value, ext.text)
131
+ return text || names.text(value.name, desc.name)
132
+ })
133
+ return [...docs.of(desc), `export const ${name} = [${values.map(value => JSON.stringify(value)).join(", ")}] as const`, `export type ${name} = (typeof ${name})[number]`, ""]
134
+ },
135
+
136
+ /** A message: its type, in the types; its components or frames, in the handles. */
137
+ message(desc: DescMessage): string[] {
138
+ const lines: string[] = []
139
+ if (opts.part === "types") for (const one of desc.nestedEnums) lines.push(...this.enumeration(one))
140
+ for (const one of desc.nestedMessages) lines.push(...this.message(one))
141
+ const holds = booleanOption(desc, ext.components) || booleanOption(desc, ext.frames)
142
+ if (holds !== (opts.part === "handles")) return lines
143
+ if (booleanOption(desc, ext.components)) {
144
+ for (const field of desc.fields) lines.push(...docs.of(field), `export const ${field.jsonName} = component<${type(field)}>(${this.component(field)})`, "")
145
+ return lines
146
+ }
147
+ if (booleanOption(desc, ext.frames)) {
148
+ for (const field of desc.fields) lines.push(...docs.of(field), `export const ${field.jsonName} = frame(${this.frame(field)})`, "")
149
+ return lines
150
+ }
151
+ const tag = stringOption(desc, ext.union)
152
+ if (tag) return [...lines, ...docs.of(desc), `export type ${names.local(desc)} =`, ...this.union(desc, tag), ""]
153
+ const fields = desc.fields.map(field => {
154
+ if (field.oneof && !field.proto.proto3Optional) throw invalid(field, `a oneof is a union: mark its message with (cognet.union) = "kind", and give it nothing else`)
155
+ const maybe = field.proto.proto3Optional || booleanOption(field, ext.optional)
156
+ if (booleanOption(field, ext.optional) && field.fieldKind !== "list" && field.fieldKind !== "map") throw invalid(field, "(cognet.optional) is for repeated and map fields; any other field says `optional`")
157
+ const nullable = booleanOption(field, ext.nullable) ? " | null" : ""
158
+ return [...docs.of(field, " "), ` ${field.jsonName}${maybe ? "?" : ""}: ${type(field)}${nullable}`]
159
+ })
160
+ return [...lines, ...docs.of(desc), `export type ${names.local(desc)} = {`, ...fields.flat(), "}", ""]
161
+ },
162
+
163
+ /** A union's members: each one of its oneof's messages, tagged by the field that holds it. */
164
+ union(desc: DescMessage, tag: string): string[] {
165
+ const oneof = desc.oneofs[0]
166
+ if (desc.oneofs.length !== 1 || !oneof || desc.fields.some(field => field.oneof !== oneof)) {
167
+ throw err("COGNET_SCHEMA_INVALID", { detail: `${desc.file.name}.proto, ${desc.name}: a union holds one oneof and nothing else` })
168
+ }
169
+ return oneof.fields.map((field, at) => {
170
+ if (field.fieldKind !== "message") throw invalid(field, "a union's members are messages")
171
+ return ` ${at === 0 ? " " : "|"} ({ ${tag}: ${JSON.stringify(field.jsonName)} } & ${named(field.message)})`
172
+ })
173
+ },
174
+
175
+ /** A component's options, as the object `component()` takes. */
176
+ component(field: DescField): string {
177
+ const json = messageOption(field, ext.component)
178
+ if (!json) return ""
179
+ const opts: string[] = []
180
+ const display = json.display
181
+ if (isRecord(display)) {
182
+ const parts: string[] = []
183
+ for (const [key, value] of Object.entries(display)) {
184
+ if (key === "frame" && typeof value === "string") {
185
+ const defined = context.frame(value)
186
+ want(defined.module, defined.exported, false)
187
+ parts.push(`frame: ${defined.exported}`)
188
+ } else if (typeof value === "string" && /^[A-Z][A-Z0-9_]*$/.test(value)) {
189
+ parts.push(`${key}: ${JSON.stringify(enumText(value, key))}`)
190
+ } else {
191
+ parts.push(`${key}: ${JSON.stringify(value)}`)
192
+ }
193
+ }
194
+ opts.push(`display: { ${parts.join(", ")} }`)
195
+ }
196
+ return opts.length ? `{ ${opts.join(", ")} }` : ""
197
+ },
198
+
199
+ /** A frame's options, as the object `frame()` takes. */
200
+ frame(field: DescField): string {
201
+ const json = messageOption(field, ext.frame)
202
+ if (!json) throw invalid(field, "a frame says what space it is with (cognet.frame)")
203
+ const parts: string[] = []
204
+ for (const [key, value] of Object.entries(json)) {
205
+ if (key === "relativeTo" && typeof value === "string") {
206
+ const defined = context.frame(value)
207
+ want(defined.module, defined.exported, false)
208
+ parts.push(`relativeTo: ${defined.exported}`)
209
+ } else if (key === "kind" && typeof value === "string") {
210
+ parts.push(`kind: ${JSON.stringify(enumText(value, key))}`)
211
+ } else {
212
+ parts.push(`${key}: ${JSON.stringify(value)}`)
213
+ }
214
+ }
215
+ return `{ ${parts.join(", ")} }`
216
+ },
217
+ }
218
+
219
+ /** An enum option's value as its text: the name less its enum's prefix, in lowerCamel — or its `text` option. */
220
+ function enumText(value: string, key: string): string {
221
+ const owner = [...context.registry].find((desc): desc is DescEnum => desc.kind === "enum" && desc.file.proto.package === "cognet" && desc.values.some(one => one.name === value))
222
+ const found = owner?.values.find(one => one.name === value)
223
+ if (!owner || !found) throw err("COGNET_SCHEMA_INVALID", { detail: `${file.name}.proto: "${value}" is no value of cognet's ${key}` })
224
+ return stringOption(found, ext.text) || names.text(value, owner.name)
225
+ }
226
+ }
227
+
228
+ /** Names in TypeScript — private to the emitter. */
229
+ const names = {
230
+ /** A message's or enum's name: nested ones carry their parents', `Chart` + `Because` → `ChartBecause`. */
231
+ local(desc: DescMessage | DescEnum): string {
232
+ return desc.parent ? `${names.local(desc.parent)}${desc.name}` : desc.name
233
+ },
234
+
235
+ /** An enum value's text: its enum's prefix taken off (`BEAT_NAME_RETINA` of `BeatName` → `RETINA`), in lowerCamel. */
236
+ text(value: string, enumName: string): string {
237
+ const prefix = `${enumName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}_`
238
+ const rest = value.startsWith(prefix) ? value.slice(prefix.length) : value
239
+ return rest.toLowerCase().replace(/_([a-z0-9])/g, (_, next: string) => next.toUpperCase())
240
+ },
241
+
242
+ scalar(scalar: ScalarType, field: DescField): string {
243
+ switch (scalar) {
244
+ case ScalarType.BOOL:
245
+ return "boolean"
246
+ case ScalarType.STRING:
247
+ return "string"
248
+ case ScalarType.BYTES:
249
+ return "Uint8Array"
250
+ case ScalarType.DOUBLE:
251
+ case ScalarType.FLOAT:
252
+ case ScalarType.INT32:
253
+ case ScalarType.UINT32:
254
+ case ScalarType.SINT32:
255
+ case ScalarType.FIXED32:
256
+ case ScalarType.SFIXED32:
257
+ return "number"
258
+ default:
259
+ // 64-bit integers would need bigint to be exact: a cognet's values are JSON, where a number is a double.
260
+ throw invalid(field, "a 64-bit integer cannot cross as JSON — use double (envelope ms are doubles) or a 32-bit integer")
261
+ }
262
+ },
263
+ }
264
+
265
+ /** Doc comments, from the schema's own — private to the emitter. */
266
+ const docs = {
267
+ /** An element's leading comment as a doc comment, or nothing. */
268
+ of(desc: DescMessage | DescEnum | DescField, indent = ""): string[] {
269
+ const file = desc.kind === "field" ? desc.parent.file : desc.file
270
+ return docs.block(docs.leading(file, docs.path(desc)), indent)
271
+ },
272
+
273
+ /** The comment the schema opens with — above its `syntax` line — as the module's own. */
274
+ file(file: DescFile): string[] {
275
+ // Above `syntax` and set apart from it by a blank line, as a file's own comment is: protobuf calls that detached.
276
+ const at = docs.at(file, [12])
277
+ const block = docs.block([...(at?.leadingDetachedComments ?? []), ...(at?.leadingComments ? [at.leadingComments] : [])].join("\n"), "")
278
+ return block.length ? [...block, ""] : []
279
+ },
280
+
281
+ /** A comment as a doc comment: one line on one line, more as a block. */
282
+ block(text: string | undefined, indent: string): string[] {
283
+ if (!text) return []
284
+ const lines = text.split("\n").map(line => line.replace(/^ /, "").trimEnd())
285
+ while (lines.length && lines[0] === "") lines.shift()
286
+ while (lines.length && lines.at(-1) === "") lines.pop()
287
+ if (lines.length === 0) return []
288
+ if (lines.length === 1) return [`${indent}/** ${lines[0]} */`]
289
+ return [`${indent}/**`, ...lines.map(line => `${indent} *${line ? ` ${line}` : ""}`), `${indent} */`]
290
+ },
291
+
292
+ /** The leading comment recorded at `path` in a file's descriptor. */
293
+ leading(file: DescFile, path: number[]): string | undefined {
294
+ return docs.at(file, path)?.leadingComments
295
+ },
296
+
297
+ /** What a file's descriptor records about the element at `path`. */
298
+ at(file: DescFile, path: number[]) {
299
+ return file.proto.sourceCodeInfo?.location.find(one => one.path.length === path.length && one.path.every((step, at) => step === path[at]))
300
+ },
301
+
302
+ /** Where in its file's descriptor an element sits — the path its comments are recorded under. */
303
+ path(desc: DescMessage | DescEnum | DescField): number[] {
304
+ if (desc.kind === "field") return [...docs.path(desc.parent), 2, desc.parent.proto.field.indexOf(desc.proto)]
305
+ if (desc.kind === "enum") return desc.parent ? [...docs.path(desc.parent), 4, desc.parent.proto.enumType.indexOf(desc.proto)] : [5, desc.file.proto.enumType.indexOf(desc.proto)]
306
+ return desc.parent ? [...docs.path(desc.parent), 3, desc.parent.proto.nestedType.indexOf(desc.proto)] : [4, desc.file.proto.messageType.indexOf(desc.proto)]
307
+ },
308
+ }
309
+
310
+ /** The runtime's extension, from the image every schema was compiled with. */
311
+ function extension(registry: FileRegistry, name: string): DescExtension {
312
+ const found = registry.getExtension(name)
313
+ if (!found) throw err("COGNET_SCHEMA_INVALID", { detail: `the runtime's schema defines no ${name} — the installed @arcforge/cognet is older than this platform` })
314
+ return found
315
+ }
316
+
317
+ function booleanOption(desc: Parameters<typeof getOption>[0], option: DescExtension): boolean {
318
+ return getOption(desc, option) === true
319
+ }
320
+
321
+ function numberOption(desc: Parameters<typeof getOption>[0], option: DescExtension): number {
322
+ const value: unknown = getOption(desc, option)
323
+ return typeof value === "number" ? value : 0
324
+ }
325
+
326
+ function stringOption(desc: Parameters<typeof getOption>[0], option: DescExtension): string {
327
+ const value: unknown = getOption(desc, option)
328
+ return typeof value === "string" ? value : ""
329
+ }
330
+
331
+ /** A message option as its JSON — enum values by name, fields by their JSON names, defaults left out. Null when absent. */
332
+ function messageOption(desc: DescField, option: DescExtension): Record<string, JsonValue> | null {
333
+ if (option.fieldKind !== "message") throw err("COGNET_SCHEMA_INVALID", { detail: `${option.typeName} is not a message option` })
334
+ const value: unknown = getOption(desc, option)
335
+ if (!isMessage(value, option.message)) return null
336
+ const json = toJson(option.message, value)
337
+ return isRecord(json) && Object.keys(json).length > 0 ? json : null
338
+ }
339
+
340
+ function isRecord(value: unknown): value is Record<string, JsonValue> {
341
+ return typeof value === "object" && value !== null && !Array.isArray(value)
342
+ }
343
+
344
+ /** The import specifier from one module to another, both absolute and without extension. */
345
+ function specifier(from: string, to: string): string {
346
+ const path = relative(dirname(from), to).split("\\").join("/")
347
+ return path.startsWith(".") ? path : `./${path}`
348
+ }
349
+
350
+ function invalid(field: DescField, why: string): Error {
351
+ return err("COGNET_SCHEMA_INVALID", { detail: `${field.parent.file.name}.proto, ${field.parent.name}.${field.name}: ${why}` })
352
+ }
@@ -14,7 +14,7 @@ export { Config, withProviderGlobals, type LoadedConfig } from "./scan/config"
14
14
 
15
15
  // The brain toolchain. prepare() gates a cognet's ABI before compiling it;
16
16
  // publish() records the declared abi on the version row.
17
- export { Cognet, cognetSourceOf, inlineCognetDir, INLINE_COGNET_DIR, type CognetT, type CognetSource, type CognetArtifact, DEFAULT_COGNET, cognetName, cognetAbi, readCognetAbi, readCognetModels, readCognetEngines } from "./cognet"
17
+ export { Cognet, cognetSourceOf, inlineCognetDir, INLINE_COGNET_DIR, type CognetT, type CognetSource, type CognetArtifact, DEFAULT_COGNET, cognetName, cognetAbi, CognetConfigFile, type CognetConfigFileT } from "./cognet"
18
18
  export { flatten, sourceRoot, type NormalisedEntry } from "./modules/entries"
19
19
 
20
20
  /**
@@ -11,7 +11,7 @@ import { Scripts } from "../scan/scripts"
11
11
  import { Tools } from "../scan/tools"
12
12
  import type { ScanWarning } from "../types"
13
13
  import { flatten, sourceRoot } from "./entries"
14
- import { readMeta } from "./meta"
14
+ import { ModuleMetaCache, type ModuleMetaCacheT } from "./meta"
15
15
 
16
16
  /**
17
17
  * Modules — the one composite scanner. Resolves declared + installed modules
@@ -60,6 +60,7 @@ export async function Modules(opts: {
60
60
  /** Statically-resolved source paths, positional to `declared`. */
61
61
  modulePaths: ResolvedModulePath[]
62
62
  }): Promise<ModulesResult> {
63
+ const metadata = ModuleMetaCache({ root: opts.root })
63
64
  const entries = await flatten(opts.declared, opts.modulePaths)
64
65
  const modules: AxonModule[] = []
65
66
  const surfaces: ModuleSurface[] = []
@@ -81,7 +82,7 @@ export async function Modules(opts: {
81
82
  const root = sourceRoot(entry)
82
83
  const name = await moduleName(root)
83
84
  claimed.add(name)
84
- await scanModule({ root, name, configPath: entry.configPath, options: entry.options, modules, surfaces, warnings })
85
+ await scanModule({ root, name, configPath: entry.configPath, options: entry.options, modules, surfaces, warnings, metadata })
85
86
  }
86
87
 
87
88
  // ── 2. Unimported local modules (modules/ directory) ────────────────────
@@ -99,6 +100,7 @@ export async function Modules(opts: {
99
100
  modules,
100
101
  surfaces,
101
102
  warnings,
103
+ metadata,
102
104
  })
103
105
  }
104
106
 
@@ -128,7 +130,7 @@ export async function Modules(opts: {
128
130
  continue
129
131
  }
130
132
  claimed.add(name)
131
- await scanModule({ root, name, configPath: join(root, "module.config.ts"), options: entry.options, modules, surfaces, warnings })
133
+ await scanModule({ root, name, configPath: join(root, "module.config.ts"), options: entry.options, modules, surfaces, warnings, metadata })
132
134
  }
133
135
 
134
136
  return { modules, surfaces, warnings }
@@ -145,6 +147,7 @@ async function scanModule(opts: {
145
147
  modules: AxonModule[]
146
148
  surfaces: ModuleSurface[]
147
149
  warnings: ScanWarning[]
150
+ metadata: ModuleMetaCacheT
148
151
  }): Promise<void> {
149
152
  const { root, name, configPath } = opts
150
153
 
@@ -167,7 +170,7 @@ async function scanModule(opts: {
167
170
  */
168
171
  const alreadyScanned = opts.surfaces.some(surface => surface.name === name)
169
172
 
170
- const meta = await readMeta(configPath)
173
+ const meta = await opts.metadata.read(configPath)
171
174
 
172
175
  const [prompts, scripts, tools, routes, plugins, middleware, knowledge] = await Promise.all([
173
176
  // Every scanner degrades for a MODULE — see each scanner's `required`.
@@ -297,4 +300,3 @@ async function modulePackage(root: string): Promise<{ name?: string; version?: s
297
300
  }
298
301
  }
299
302
 
300
-
@@ -1,5 +1,8 @@
1
1
  import type TsNamespace from "typescript"
2
2
  import type { ModuleOptionSchema } from "@arcforge/types"
3
+ import { createHash } from "node:crypto"
4
+ import { existsSync, readFileSync, writeFileSync } from "node:fs"
5
+ import { Frame } from "../../frame"
3
6
  import { fsx } from "../../../utils/fs"
4
7
 
5
8
  /**
@@ -29,11 +32,52 @@ export type ModuleMeta = {
29
32
  optionsSchema: Record<string, ModuleOptionSchema>
30
33
  }
31
34
 
32
- export async function readMeta(configPath: string): Promise<ModuleMeta> {
33
- const meta: ModuleMeta = { automerge: null, env: {}, optionsSchema: {} }
35
+ type CachedMeta = Record<string, ModuleMeta>
36
+
37
+ /** ModuleMetaCache — durable AST metadata for installed module declarations. */
38
+ export function ModuleMetaCache(opts: { root: string }) {
39
+ const frame = Frame({ root: opts.root, kind: "agent" })
40
+ const path = frame.file("cache", "module-meta.json")
41
+ let entries: CachedMeta | null = null
42
+
43
+ function load(): CachedMeta {
44
+ if (entries) return entries
45
+ if (!existsSync(path)) return entries = {}
46
+ try {
47
+ return entries = JSON.parse(readFileSync(path, "utf-8")) as CachedMeta
48
+ } catch {
49
+ // Derived metadata is non-authoritative; re-parsing the authored
50
+ // module config below restores a torn cache entry.
51
+ return entries = {}
52
+ }
53
+ }
54
+
55
+ return {
56
+ async read(configPath: string): Promise<ModuleMeta> {
57
+ const content = await fsx.readText(configPath)
58
+ if (content === null) return { automerge: null, env: {}, optionsSchema: {} }
59
+ const key = createHash("sha256").update(configPath).update("\0").update(content).digest("hex")
60
+ const cached = load()[key]
61
+ if (cached) return cached
62
+ const meta = await parseMeta(configPath, content)
63
+ load()[key] = meta
64
+ frame.ensure("cache")
65
+ writeFileSync(path, JSON.stringify(load()) + "\n", "utf-8")
66
+ return meta
67
+ },
68
+ }
69
+ }
70
+
71
+ export type ModuleMetaCacheT = ReturnType<typeof ModuleMetaCache>
34
72
 
73
+ export async function readMeta(configPath: string): Promise<ModuleMeta> {
35
74
  const content = await fsx.readText(configPath)
36
- if (content === null) return meta
75
+ if (content === null) return { automerge: null, env: {}, optionsSchema: {} }
76
+ return parseMeta(configPath, content)
77
+ }
78
+
79
+ async function parseMeta(configPath: string, content: string): Promise<ModuleMeta> {
80
+ const meta: ModuleMeta = { automerge: null, env: {}, optionsSchema: {} }
37
81
 
38
82
  await loadTs()
39
83
  const src = ts.createSourceFile(configPath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
@@ -1,14 +1,12 @@
1
- import { join } from "node:path"
1
+ import { join, resolve } from "node:path"
2
2
  import { AsyncLocalStorage } from "node:async_hooks"
3
- import { defineModule, definePrompt } from "@arcforge/types"
4
- import { defineCognet } from "@arcforge/cognet"
5
3
  import type { AxonConfig, ModuleEntry } from "@arcforge/types"
6
- import { Axon, Local, Ollama, Codex, OpenRouter, HuggingFace, Mock } from "@arcforge/engines"
7
4
  import { err } from "@arcforge/err"
8
5
  import { fsx } from "../../../utils/fs"
9
6
  import { resolveModulePaths, type ResolvedModulePath } from "./moduleImports"
10
7
  import { resolveCognetPath } from "./cognetImports"
11
8
  import type { ResolvedDeclaration } from "./configImports"
9
+ import { ProviderGlobals } from "./provider-globals"
12
10
 
13
11
  /**
14
12
  * Config — loads and evaluates axon.config.ts. The ONE place in the
@@ -57,6 +55,11 @@ type ConfigEvaluation = {
57
55
  capture(config: AxonConfig): void
58
56
  }
59
57
 
58
+ const providers = ProviderGlobals()
59
+ const defineModule = <T>(config: T): T => config
60
+ const defineCognet = <T>(config: T): T => config
61
+ const definePrompt = <T>(config: T): { _kind: "prompt"; config: T } => ({ _kind: "prompt", config: config })
62
+
60
63
  const CONFIG_EVALUATION = Symbol.for("axon.config.evaluation")
61
64
  const evaluationStorage = (() => {
62
65
  const shared = globalThis as typeof globalThis & {
@@ -120,13 +123,13 @@ function installAuthoringGlobals(): void {
120
123
  // `??=` deliberately: an embedding host may have installed its own, and
121
124
  // the AUTHORITATIVE binding for the duration of an evaluation is applied
122
125
  // by withProviderGlobals() below rather than trusted from module load.
123
- g.Axon ??= Axon
124
- g.Local ??= Local
125
- g.Ollama ??= Ollama
126
- g.Codex ??= Codex
127
- g.OpenRouter ??= OpenRouter
128
- g.HuggingFace ??= HuggingFace
129
- g.Mock ??= Mock
126
+ g.Axon ??= providers.Axon
127
+ g.Local ??= providers.Local
128
+ g.Ollama ??= providers.Ollama
129
+ g.Codex ??= providers.Codex
130
+ g.OpenRouter ??= providers.OpenRouter
131
+ g.HuggingFace ??= providers.HuggingFace
132
+ g.Mock ??= providers.Mock
130
133
  }
131
134
 
132
135
  /**
@@ -150,7 +153,7 @@ function installAuthoringGlobals(): void {
150
153
  */
151
154
  export async function withProviderGlobals<T>(body: () => Promise<T>): Promise<T> {
152
155
  const g = globalThis as Record<string, unknown>
153
- const factories = { Axon, Local, Ollama, Codex, OpenRouter, HuggingFace, Mock }
156
+ const factories = providers
154
157
  const previous = Object.fromEntries(Object.keys(factories).map(name => [name, g[name]]))
155
158
  Object.assign(g, factories)
156
159
  try {
@@ -163,11 +166,13 @@ export async function withProviderGlobals<T>(body: () => Promise<T>): Promise<T>
163
166
  installAuthoringGlobals()
164
167
 
165
168
  export async function Config(root: string): Promise<LoadedConfig> {
166
- const configPath = join(root, "axon.config.ts")
169
+ const resolvedRoot = resolve(root)
170
+ const configPath = join(resolvedRoot, "axon.config.ts")
167
171
  if (!fsx.exists(configPath)) {
168
172
  throw err("CONFIG_NOT_FOUND", { context: { root } })
169
173
  }
170
-
174
+ const source = await fsx.readText(configPath)
175
+ if (source === null) throw err("CONFIG_NOT_FOUND", { context: { root } })
171
176
  let captured: AxonConfig | null = null
172
177
  const evaluation: ConfigEvaluation = { capture: config => { captured = config } }
173
178
 
@@ -221,13 +226,14 @@ export async function Config(root: string): Promise<LoadedConfig> {
221
226
  }
222
227
 
223
228
  const value: AxonConfig = captured
224
- return {
225
- root,
229
+ const loaded = {
230
+ root: resolvedRoot,
226
231
  value,
227
232
  modules: (value.modules ?? []) as ModuleEntry[],
228
233
  modulePaths: await resolveModulePaths(configPath),
229
234
  cognetPath: await resolveCognetPath(configPath),
230
235
  }
236
+ return loaded
231
237
  } finally {
232
238
  state.current = null
233
239
  release()
@@ -0,0 +1,46 @@
1
+ import type { ProviderEntry } from "@arcforge/types"
2
+
3
+ /**
4
+ * ProviderGlobals — the declaration-only factories available while evaluating
5
+ * an agent config. They deliberately do not import the engines runtime: a
6
+ * provider declaration is data, while drivers and catalogues are boot work
7
+ * for the runtime that actually uses one.
8
+ */
9
+ export function ProviderGlobals() {
10
+ type Options = { key?: string; url?: string; slots?: number }
11
+ const entry = (provider: string, options: Options = {}): ProviderEntry => ({
12
+ provider: provider,
13
+ ...(options.key !== undefined ? { key: options.key } : {}),
14
+ ...(options.url !== undefined ? { url: options.url } : {}),
15
+ ...(options.slots !== undefined ? { slots: options.slots } : {}),
16
+ })
17
+ const provider = (name: string) => (options?: Options): ProviderEntry => entry(name, options)
18
+ type MockEntry = ProviderEntry & { script?: unknown }
19
+ const mock = (script?: unknown): MockEntry => {
20
+ const isOptions = script !== undefined
21
+ && script !== null
22
+ && typeof script === "object"
23
+ && Object.keys(script).length > 0
24
+ && Object.keys(script).every(key => key === "key" || key === "url" || key === "slots")
25
+ if (script === undefined || isOptions) return entry("mock", script as Options | undefined)
26
+ return { ...entry("mock"), script: script }
27
+ }
28
+
29
+ const axon = provider("axon")
30
+ const local = provider("local")
31
+ const ollama = provider("ollama")
32
+ const codex = provider("codex")
33
+ const openRouter = provider("openrouter")
34
+ const huggingFace = provider("huggingface")
35
+ return {
36
+ Axon: axon,
37
+ Local: local,
38
+ Ollama: ollama,
39
+ Codex: codex,
40
+ OpenRouter: openRouter,
41
+ HuggingFace: huggingFace,
42
+ Mock: mock,
43
+ }
44
+ }
45
+
46
+ export type ProviderGlobalsT = ReturnType<typeof ProviderGlobals>
@@ -0,0 +1,25 @@
1
+ import { join, relative, sep } from "node:path"
2
+ import type { AxonBlueprint } from "@arcforge/types"
3
+ import { fsx } from "../../../utils/fs"
4
+ import { ProviderFile } from "../cognet"
5
+
6
+ /**
7
+ * Providers — the agent's own, `providers/**\/*.provider.ts`, each named as a
8
+ * grant names it: `providers/vision/features.provider.ts` is
9
+ * `./providers/vision/features`, with what it implements and the engines it
10
+ * needs — read, never imported: a provider is loaded by the runtime that
11
+ * grants it, on the agent's side.
12
+ */
13
+ export async function Providers(root: string): Promise<AxonBlueprint["serviceProviders"]> {
14
+ const dir = join(root, "providers")
15
+ if (!fsx.exists(dir)) return []
16
+ const found = await fsx.walk(dir, { skipDirs: ["node_modules"] })
17
+ return found
18
+ .filter(file => file.relPath.endsWith(".provider.ts"))
19
+ .map(file => ({
20
+ name: `./providers/${relative(dir, file.absPath).split(sep).join("/").slice(0, -".provider.ts".length)}`,
21
+ filePath: file.absPath,
22
+ ...ProviderFile({ filePath: file.absPath }).read(),
23
+ }))
24
+ .sort((a, b) => a.name.localeCompare(b.name))
25
+ }