@arcforge/platform 2.0.166 → 2.0.168

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcforge/platform",
3
- "version": "2.0.166",
3
+ "version": "2.0.168",
4
4
  "description": "The Axon developer platform — headless project discovery, blueprint scanning, typegen, agent lifecycle, registry, benches and tests. Shared by the CLI/TUI and the Fleet extension.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -44,24 +44,24 @@
44
44
  "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
45
45
  },
46
46
  "dependencies": {
47
- "@arcforge/session": "2.0.166",
48
- "@arcforge/engines": "2.0.166",
49
- "@arcforge/err": "2.0.166",
50
- "@arcforge/types": "2.0.166",
51
- "@arcforge/cloud": "2.0.166",
52
- "@arcforge/capsule": "2.0.166",
53
- "@arcforge/core": "2.0.166",
54
- "@arcforge/vstr": "2.0.166",
47
+ "@arcforge/session": "2.0.168",
48
+ "@arcforge/engines": "2.0.168",
49
+ "@arcforge/err": "2.0.168",
50
+ "@arcforge/types": "2.0.168",
51
+ "@arcforge/cloud": "2.0.168",
52
+ "@arcforge/capsule": "2.0.168",
53
+ "@arcforge/core": "2.0.168",
54
+ "@arcforge/vstr": "2.0.168",
55
55
  "fft.js": "^4.0.4",
56
56
  "h3": "^1.15.11",
57
57
  "semver": "^7.7.4",
58
58
  "sharp": "^0.35.3",
59
59
  "typescript": "5.9.2",
60
- "@arcforge/link": "2.0.166"
60
+ "@arcforge/link": "2.0.168"
61
61
  },
62
62
  "devDependencies": {
63
- "@arcforge/air": "2.0.165",
64
- "@arcforge/cognet": "2.0.165",
63
+ "@arcforge/air": "2.0.167",
64
+ "@arcforge/cognet": "2.0.167",
65
65
  "@arclabs/repo": "1.0.0",
66
66
  "@types/bun": "latest",
67
67
  "@types/semver": "^7.7.1"
@@ -1,4 +1,27 @@
1
- import ts from "typescript"
1
+ import type ts from "typescript"
2
+
3
+ /**
4
+ * The TypeScript compiler, loaded on FIRST USE rather than at import.
5
+ *
6
+ * `typescript` costs ~190-220ms to load, and it was being pulled into every
7
+ * `axon` invocation through this module's import chain — before argument
8
+ * parsing, before any command ran, before a character reached the screen.
9
+ * `axon dev` showing nothing for a second was largely this.
10
+ *
11
+ * Nothing here touches `ts` at module scope; every reference is inside a
12
+ * function body. So deferring costs the first caller the load and every
13
+ * command that parses no source file nothing at all.
14
+ *
15
+ * `require`, not `await import`: these APIs are synchronous and making them
16
+ * async would ripple through every caller for no gain. The type import above
17
+ * is erased at compile time, which keeps every `ts.X` annotation unchanged.
18
+ */
19
+ let _ts: typeof ts | undefined
20
+ function tsc(): typeof ts {
21
+ // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
22
+ return (_ts ??= require("typescript") as typeof ts)
23
+ }
24
+
2
25
  import { err } from "@arcforge/err"
3
26
  import type { BenchMeasurementDefinition, BenchMeasurementReducer, BenchMeasurementValueDefinition } from "@arcforge/types"
4
27
 
@@ -20,9 +43,9 @@ import type { BenchMeasurementDefinition, BenchMeasurementReducer, BenchMeasurem
20
43
  const COMPILER_OPTIONS: ts.CompilerOptions = {
21
44
  allowJs: false,
22
45
  noEmit: true,
23
- target: ts.ScriptTarget.ESNext,
24
- module: ts.ModuleKind.ESNext,
25
- moduleResolution: ts.ModuleResolutionKind.Bundler,
46
+ target: tsc().ScriptTarget.ESNext,
47
+ module: tsc().ModuleKind.ESNext,
48
+ moduleResolution: tsc().ModuleResolutionKind.Bundler,
26
49
  skipLibCheck: true,
27
50
  strict: true,
28
51
  }
@@ -36,7 +59,7 @@ const DEFAULT_AGGREGATE: Record<BenchMeasurementValueDefinition["kind"], BenchMe
36
59
  }
37
60
 
38
61
  export function extractBenchSchema(configPath: string): BenchMeasurementDefinition[] {
39
- const program = ts.createProgram([configPath], COMPILER_OPTIONS)
62
+ const program = tsc().createProgram([configPath], COMPILER_OPTIONS)
40
63
  const source = program.getSourceFile(configPath)
41
64
  if (!source) throw err("BENCH_SCHEMA_UNREADABLE", { detail: configPath, context: { configPath } })
42
65
 
@@ -64,13 +87,13 @@ function findDefineBenchCall(source: ts.SourceFile): ts.CallExpression | null {
64
87
  let found: ts.CallExpression | null = null
65
88
  const visit = (node: ts.Node): void => {
66
89
  if (found) return
67
- if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "defineBench") {
90
+ if (tsc().isCallExpression(node) && tsc().isIdentifier(node.expression) && node.expression.text === "defineBench") {
68
91
  found = node
69
92
  return
70
93
  }
71
- ts.forEachChild(node, visit)
94
+ tsc().forEachChild(node, visit)
72
95
  }
73
- ts.forEachChild(source, visit)
96
+ tsc().forEachChild(source, visit)
74
97
  return found
75
98
  }
76
99
 
@@ -86,9 +109,9 @@ function toMeasurement(
86
109
  : checker.getDeclaredTypeOfSymbol(property)
87
110
 
88
111
  const value = toValueDefinition(type, checker, id, configPath)
89
- const description = ts.displayPartsToString(property.getDocumentationComment(checker)).trim()
112
+ const description = tsc().displayPartsToString(property.getDocumentationComment(checker)).trim()
90
113
  const tags = Object.fromEntries(
91
- property.getJsDocTags(checker).map(tag => [tag.name, ts.displayPartsToString(tag.text).trim()]),
114
+ property.getJsDocTags(checker).map(tag => [tag.name, tsc().displayPartsToString(tag.text).trim()]),
92
115
  )
93
116
 
94
117
  return {
@@ -110,8 +133,8 @@ function toValueDefinition(
110
133
  id: string,
111
134
  configPath: string,
112
135
  ): BenchMeasurementValueDefinition {
113
- if (type.flags & ts.TypeFlags.BooleanLike) return { kind: "boolean" }
114
- if (type.flags & ts.TypeFlags.NumberLike) return { kind: "number" }
136
+ if (type.flags & tsc().TypeFlags.BooleanLike) return { kind: "boolean" }
137
+ if (type.flags & tsc().TypeFlags.NumberLike) return { kind: "number" }
115
138
 
116
139
  // A union of string literals is a category with a closed value set — the
117
140
  // natural way to write "one of these", and the reason the schema is a type.
@@ -120,10 +143,10 @@ function toValueDefinition(
120
143
  if (literals.length === type.types.length && literals.length > 0) {
121
144
  return { kind: "category", values: literals.map(member => (member as ts.StringLiteralType).value) }
122
145
  }
123
- if (type.types.every(member => member.flags & ts.TypeFlags.BooleanLike)) return { kind: "boolean" }
146
+ if (type.types.every(member => member.flags & tsc().TypeFlags.BooleanLike)) return { kind: "boolean" }
124
147
  }
125
148
 
126
- if (type.flags & ts.TypeFlags.StringLike) return { kind: "text" }
149
+ if (type.flags & tsc().TypeFlags.StringLike) return { kind: "text" }
127
150
 
128
151
  throw err("BENCH_SCHEMA_UNSUPPORTED_TYPE", {
129
152
  detail: `measurement ${JSON.stringify(id)} is ${checker.typeToString(type)} — measurements are boolean, number, a union of string literals, or string`,
@@ -1,5 +1,28 @@
1
+ import type ts from "typescript"
2
+
3
+ /**
4
+ * The TypeScript compiler, loaded on FIRST USE rather than at import.
5
+ *
6
+ * `typescript` costs ~190-220ms to load, and it was being pulled into every
7
+ * `axon` invocation through this module's import chain — before argument
8
+ * parsing, before any command ran, before a character reached the screen.
9
+ * `axon dev` showing nothing for a second was largely this.
10
+ *
11
+ * Nothing here touches `ts` at module scope; every reference is inside a
12
+ * function body. So deferring costs the first caller the load and every
13
+ * command that parses no source file nothing at all.
14
+ *
15
+ * `require`, not `await import`: these APIs are synchronous and making them
16
+ * async would ripple through every caller for no gain. The type import above
17
+ * is erased at compile time, which keeps every `ts.X` annotation unchanged.
18
+ */
19
+ let _ts: typeof ts | undefined
20
+ function tsc(): typeof ts {
21
+ // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
22
+ return (_ts ??= require("typescript") as typeof ts)
23
+ }
24
+
1
25
  import { dirname, join } from "node:path"
2
- import ts from "typescript"
3
26
  import type { ToolFnEntry } from "@arcforge/types"
4
27
  import { err } from "@arcforge/err"
5
28
  import { resolveSignatureTypes, assertNoDanglingTypes, rewriteImportPaths } from "./resolve"
@@ -14,9 +37,9 @@ export type DeclaredFile = {
14
37
  const COMPILER_OPTIONS: ts.CompilerOptions = {
15
38
  declaration: true,
16
39
  emitDeclarationOnly: true,
17
- target: ts.ScriptTarget.ESNext,
18
- module: ts.ModuleKind.ESNext,
19
- moduleResolution: ts.ModuleResolutionKind.Bundler,
40
+ target: tsc().ScriptTarget.ESNext,
41
+ module: tsc().ModuleKind.ESNext,
42
+ moduleResolution: tsc().ModuleResolutionKind.Bundler,
20
43
  strict: true,
21
44
  skipLibCheck: true,
22
45
  // Declaration emit fails loudly on an implicit any parameter otherwise —
@@ -75,7 +98,7 @@ const COMPILER_OPTIONS: ts.CompilerOptions = {
75
98
  const libFiles = new Map<string, ts.SourceFile | undefined>()
76
99
 
77
100
  /** The directory TypeScript's own lib.*.d.ts files ship in. */
78
- const libDir = normalize(ts.getDefaultLibFilePath(COMPILER_OPTIONS).replace(/[^/\\]+$/, ""))
101
+ const libDir = normalize(tsc().getDefaultLibFilePath(COMPILER_OPTIONS).replace(/[^/\\]+$/, ""))
79
102
 
80
103
  /** True for a path inside TypeScript's own lib directory. */
81
104
  function isLibFile(fileName: string): boolean {
@@ -119,7 +142,7 @@ function unshadow(path: string): string {
119
142
  export function declareTools(fileNames: string[]): Map<string, DeclaredFile> {
120
143
  const emitted = new Map<string, string>()
121
144
 
122
- const host = ts.createCompilerHost(COMPILER_OPTIONS)
145
+ const host = tsc().createCompilerHost(COMPILER_OPTIONS)
123
146
 
124
147
  // Reads follow the shadow back to the real file on disk. Everything above
125
148
  // this line thinks in shadowed paths; everything below it, and the whole
@@ -176,7 +199,7 @@ export function declareTools(fileNames: string[]): Map<string, DeclaredFile> {
176
199
  // Emitted paths are mapped back, so every caller sees real locations.
177
200
  host.writeFile = (fileName, text) => emitted.set(normalize(unshadow(fileName)), text)
178
201
 
179
- const program = ts.createProgram(fileNames.map(shadow), COMPILER_OPTIONS, host)
202
+ const program = tsc().createProgram(fileNames.map(shadow), COMPILER_OPTIONS, host)
180
203
  program.emit()
181
204
  const result = new Map<string, DeclaredFile>()
182
205
 
@@ -188,7 +211,7 @@ export function declareTools(fileNames: string[]): Map<string, DeclaredFile> {
188
211
  // the identifiers a resolver needs. See resolve.ts.
189
212
  const emittedSources = new Map<string, ts.SourceFile>()
190
213
  for (const [file, text] of emitted) {
191
- emittedSources.set(file, ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS))
214
+ emittedSources.set(file, tsc().createSourceFile(file, text, tsc().ScriptTarget.Latest, true, tsc().ScriptKind.TS))
192
215
  }
193
216
 
194
217
  for (const fileName of fileNames) {
@@ -262,18 +285,18 @@ export function declareTools(fileNames: string[]): Map<string, DeclaredFile> {
262
285
  function exportedSignatureNodes(src: ts.SourceFile): ts.Node[] {
263
286
  const nodes: ts.Node[] = []
264
287
 
265
- ts.forEachChild(src, node => {
266
- if (ts.isFunctionDeclaration(node) && hasExportModifier(node)) {
288
+ tsc().forEachChild(src, node => {
289
+ if (tsc().isFunctionDeclaration(node) && hasExportModifier(node)) {
267
290
  nodes.push(node)
268
- } else if (ts.isClassDeclaration(node) && hasExportModifier(node)) {
291
+ } else if (tsc().isClassDeclaration(node) && hasExportModifier(node)) {
269
292
  nodes.push(node)
270
- } else if (ts.isVariableStatement(node) && hasExportModifier(node)) {
293
+ } else if (tsc().isVariableStatement(node) && hasExportModifier(node)) {
271
294
  nodes.push(node)
272
- } else if (ts.isTypeAliasDeclaration(node) && hasExportModifier(node)) {
295
+ } else if (tsc().isTypeAliasDeclaration(node) && hasExportModifier(node)) {
273
296
  nodes.push(node)
274
- } else if (ts.isInterfaceDeclaration(node) && hasExportModifier(node)) {
297
+ } else if (tsc().isInterfaceDeclaration(node) && hasExportModifier(node)) {
275
298
  nodes.push(node)
276
- } else if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
299
+ } else if (tsc().isExportDeclaration(node) && node.exportClause && tsc().isNamedExports(node.exportClause)) {
277
300
  for (const element of node.exportClause.elements) nodes.push(element)
278
301
  }
279
302
  })
@@ -287,7 +310,7 @@ function exportedSignatureNodes(src: ts.SourceFile): ts.Node[] {
287
310
  * must use the same function or the lookup misses on nothing but spelling.
288
311
  */
289
312
  function normalize(path: string): string {
290
- return ts.sys.resolvePath(path.replace(/\\/g, "/"))
313
+ return tsc().sys.resolvePath(path.replace(/\\/g, "/"))
291
314
  }
292
315
 
293
316
  /** Compiler diagnostics for one file, appended to an error so the message says WHY. */
@@ -297,7 +320,7 @@ function diagnosticsFor(program: ts.Program, fileName: string): string {
297
320
  const messages = program
298
321
  .getSemanticDiagnostics(source)
299
322
  .concat(program.getSyntacticDiagnostics(source))
300
- .map(d => ts.flattenDiagnosticMessageText(d.messageText, " "))
323
+ .map(d => tsc().flattenDiagnosticMessageText(d.messageText, " "))
301
324
  return messages.length > 0 ? `:\n${messages.map(m => ` - ${m}`).join("\n")}` : ""
302
325
  }
303
326
 
@@ -310,7 +333,7 @@ function declarationPathFor(fileName: string): string {
310
333
 
311
334
 
312
335
  function hasExportModifier(node: ts.Node): boolean {
313
- return ts.canHaveModifiers(node) ? (ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false) : false
336
+ return tsc().canHaveModifiers(node) ? (tsc().getModifiers(node)?.some(m => m.kind === tsc().SyntaxKind.ExportKeyword) ?? false) : false
314
337
  }
315
338
 
316
339
  /**
@@ -337,7 +360,7 @@ function awaitable(declaration: string, node: ts.FunctionDeclaration, src: ts.So
337
360
  // not parse. Such a tool is unusable across the capsule boundary anyway
338
361
  // (the narrowing is erased by serialization), so leave the declaration
339
362
  // exactly as the author wrote it rather than emitting broken TypeScript.
340
- if (ts.isTypePredicateNode(returnType)) return declaration
363
+ if (tsc().isTypePredicateNode(returnType)) return declaration
341
364
 
342
365
  const text = returnType.getText(src)
343
366
  if (/^Promise\s*</.test(text)) return declaration
@@ -368,8 +391,8 @@ function extractJsDoc(node: ts.Node, src: ts.SourceFile): string | undefined {
368
391
  function extractFnEntries(src: ts.SourceFile): ToolFnEntry[] {
369
392
  const fns: ToolFnEntry[] = []
370
393
 
371
- ts.forEachChild(src, node => {
372
- if (ts.isFunctionDeclaration(node) && hasExportModifier(node) && node.name) {
394
+ tsc().forEachChild(src, node => {
395
+ if (tsc().isFunctionDeclaration(node) && hasExportModifier(node) && node.name) {
373
396
  const name = node.name.getText(src)
374
397
  const jsdoc = extractJsDoc(node, src)
375
398
  // tsc emits "export declare function foo(...): T;" — strip the
@@ -378,9 +401,9 @@ function extractFnEntries(src: ts.SourceFile): ToolFnEntry[] {
378
401
  // leaving a bare `function foo(...): T`.
379
402
  const declText = node.getText(src).replace(/^export\s+declare\s+/, "").replace(/;\s*$/, "")
380
403
  fns.push({ name, declaration: awaitable(declText, node, src), ...(jsdoc !== undefined ? { jsdoc } : {}) })
381
- } else if (ts.isVariableStatement(node) && hasExportModifier(node)) {
404
+ } else if (tsc().isVariableStatement(node) && hasExportModifier(node)) {
382
405
  for (const decl of node.declarationList.declarations) {
383
- if (!ts.isIdentifier(decl.name)) continue
406
+ if (!tsc().isIdentifier(decl.name)) continue
384
407
  const name = decl.name.getText(src)
385
408
  const jsdoc = extractJsDoc(node, src)
386
409
  const declText = decl.getText(src)
@@ -1,4 +1,27 @@
1
- import ts from "typescript"
1
+ import type ts from "typescript"
2
+
3
+ /**
4
+ * The TypeScript compiler, loaded on FIRST USE rather than at import.
5
+ *
6
+ * `typescript` costs ~190-220ms to load, and it was being pulled into every
7
+ * `axon` invocation through this module's import chain — before argument
8
+ * parsing, before any command ran, before a character reached the screen.
9
+ * `axon dev` showing nothing for a second was largely this.
10
+ *
11
+ * Nothing here touches `ts` at module scope; every reference is inside a
12
+ * function body. So deferring costs the first caller the load and every
13
+ * command that parses no source file nothing at all.
14
+ *
15
+ * `require`, not `await import`: these APIs are synchronous and making them
16
+ * async would ripple through every caller for no gain. The type import above
17
+ * is erased at compile time, which keeps every `ts.X` annotation unchanged.
18
+ */
19
+ let _ts: typeof ts | undefined
20
+ function tsc(): typeof ts {
21
+ // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
22
+ return (_ts ??= require("typescript") as typeof ts)
23
+ }
24
+
2
25
  import { err } from "@arcforge/err"
3
26
 
4
27
  /**
@@ -105,7 +128,7 @@ function inlineable(text: string): string {
105
128
  * what makes a re-exported package type render as its actual shape.
106
129
  */
107
130
  function targetSymbol(symbol: ts.Symbol, checker: ts.TypeChecker): ts.Symbol {
108
- if ((symbol.flags & ts.SymbolFlags.Alias) === 0) return symbol
131
+ if ((symbol.flags & tsc().SymbolFlags.Alias) === 0) return symbol
109
132
  try {
110
133
  const aliased = checker.getAliasedSymbol(symbol)
111
134
  return aliased.getDeclarations()?.length ? aliased : symbol
@@ -124,10 +147,10 @@ function declarationNode(symbol: ts.Symbol): ts.Declaration | undefined {
124
147
  const declarations = symbol.getDeclarations() ?? []
125
148
  for (const declaration of declarations) {
126
149
  if (
127
- ts.isInterfaceDeclaration(declaration)
128
- || ts.isTypeAliasDeclaration(declaration)
129
- || ts.isClassDeclaration(declaration)
130
- || ts.isEnumDeclaration(declaration)
150
+ tsc().isInterfaceDeclaration(declaration)
151
+ || tsc().isTypeAliasDeclaration(declaration)
152
+ || tsc().isClassDeclaration(declaration)
153
+ || tsc().isEnumDeclaration(declaration)
131
154
  ) {
132
155
  return declaration
133
156
  }
@@ -155,34 +178,34 @@ function referencedSymbols(node: ts.Node, checker: ts.TypeChecker): ts.Symbol[]
155
178
  // cases below never see it. This is the form an author uses to say "this
156
179
  // package type is part of what I expose", and honouring it is the whole
157
180
  // point of accepting the re-export.
158
- if (ts.isExportSpecifier(current)) {
181
+ if (tsc().isExportSpecifier(current)) {
159
182
  const symbol = checker.getSymbolAtLocation(current.name)
160
183
  if (symbol) found.push(symbol)
161
184
  return
162
185
  }
163
186
  // The NAME of the declaration itself is not a reference to anything.
164
- if (ts.isTypeReferenceNode(current)) {
165
- const name = ts.isQualifiedName(current.typeName) ? current.typeName.right : current.typeName
187
+ if (tsc().isTypeReferenceNode(current)) {
188
+ const name = tsc().isQualifiedName(current.typeName) ? current.typeName.right : current.typeName
166
189
  const symbol = checker.getSymbolAtLocation(name)
167
190
  if (symbol) found.push(symbol)
168
- } else if (ts.isExpressionWithTypeArguments(current) && ts.isIdentifier(current.expression)) {
191
+ } else if (tsc().isExpressionWithTypeArguments(current) && tsc().isIdentifier(current.expression)) {
169
192
  // `interface A extends B` / `class A implements B` — B is a real
170
193
  // reference the model needs, and it is not a TypeReferenceNode.
171
194
  const symbol = checker.getSymbolAtLocation(current.expression)
172
195
  if (symbol) found.push(symbol)
173
- } else if (ts.isTypeQueryNode(current)) {
196
+ } else if (tsc().isTypeQueryNode(current)) {
174
197
  // `typeof x` — the thing being queried is referenced.
175
- const name = ts.isQualifiedName(current.exprName) ? current.exprName.right : current.exprName
198
+ const name = tsc().isQualifiedName(current.exprName) ? current.exprName.right : current.exprName
176
199
  const symbol = checker.getSymbolAtLocation(name)
177
200
  if (symbol) found.push(symbol)
178
201
  }
179
- ts.forEachChild(current, visit)
202
+ tsc().forEachChild(current, visit)
180
203
  }
181
204
 
182
205
  // Skip the declaration's own name so `type Node = ...` does not resolve
183
206
  // itself as a reference on the first step.
184
- ts.forEachChild(node, child => {
185
- if ((ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isClassDeclaration(node) || ts.isEnumDeclaration(node)) && child === node.name) return
207
+ tsc().forEachChild(node, child => {
208
+ if ((tsc().isInterfaceDeclaration(node) || tsc().isTypeAliasDeclaration(node) || tsc().isClassDeclaration(node) || tsc().isEnumDeclaration(node)) && child === node.name) return
186
209
  visit(child)
187
210
  })
188
211
 
@@ -246,7 +269,7 @@ export function resolveSignatureTypes(nodes: ts.Node[], opts: ResolveOpts): Reso
246
269
  for (const node of nodes) {
247
270
  // An export specifier is itself the reference; everything else is a
248
271
  // container whose type positions are walked.
249
- if (ts.isExportSpecifier(node)) {
272
+ if (tsc().isExportSpecifier(node)) {
250
273
  const symbol = opts.checker.getSymbolAtLocation(node.name)
251
274
  if (symbol) collect(symbol, opts, seen, out)
252
275
  continue
@@ -342,19 +365,19 @@ export function rewriteImportPaths(declaration: string, resolved: ResolvedType[]
342
365
  * the signature carrying it, so it is resolvable without being inlined.
343
366
  */
344
367
  function typeNamesIn(declaration: string): string[] {
345
- const src = ts.createSourceFile("d.d.ts", `declare ${declaration};`, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
368
+ const src = tsc().createSourceFile("d.d.ts", `declare ${declaration};`, tsc().ScriptTarget.Latest, true, tsc().ScriptKind.TS)
346
369
  const names: string[] = []
347
370
  const bound = new Set<string>()
348
371
 
349
372
  function visit(node: ts.Node): void {
350
- if (ts.isTypeParameterDeclaration(node)) bound.add(node.name.getText(src))
351
- if (ts.isTypeReferenceNode(node)) {
373
+ if (tsc().isTypeParameterDeclaration(node)) bound.add(node.name.getText(src))
374
+ if (tsc().isTypeReferenceNode(node)) {
352
375
  // Only the LEFTMOST name of a qualified reference is a lookup;
353
376
  // `A.B` resolves B within A, so B is not independently declared.
354
- const root = ts.isQualifiedName(node.typeName) ? leftmost(node.typeName) : node.typeName
377
+ const root = tsc().isQualifiedName(node.typeName) ? leftmost(node.typeName) : node.typeName
355
378
  names.push(root.getText(src))
356
379
  }
357
- ts.forEachChild(node, visit)
380
+ tsc().forEachChild(node, visit)
358
381
  }
359
382
  visit(src)
360
383
 
@@ -363,7 +386,7 @@ function typeNamesIn(declaration: string): string[] {
363
386
 
364
387
  function leftmost(name: ts.QualifiedName): ts.Identifier {
365
388
  let current: ts.EntityName = name
366
- while (ts.isQualifiedName(current)) current = current.left
389
+ while (tsc().isQualifiedName(current)) current = current.left
367
390
  return current
368
391
  }
369
392
 
@@ -1,5 +1,34 @@
1
- import ts from "typescript"
1
+ import type ts from "typescript"
2
+
3
+ /**
4
+ * The TypeScript compiler, loaded on FIRST USE rather than at import.
5
+ *
6
+ * `typescript` costs ~223ms to load — roughly half of `@arcforge/platform`'s
7
+ * entire import time, which every `axon` invocation paid before a single line
8
+ * of any command ran. `axon dev` printing nothing for a second was mostly
9
+ * this: the progress surface could not paint because its own module graph was
10
+ * still loading a compiler it had no use for.
11
+ *
12
+ * Nothing here touches `ts` at module scope — every reference is inside a
13
+ * function body — so deferring the load costs the first caller ~223ms and
14
+ * every command that never parses a source file nothing at all.
15
+ *
16
+ * `require`, not `await import`: these are SYNCHRONOUS APIs
17
+ * (`readSettingsSync` is named for it, and is called during Platform()'s own
18
+ * settings read), so making them async would ripple through every caller for
19
+ * no gain. Bun resolves this from the same graph either way.
20
+ *
21
+ * The type import above is erased at compile time and carries no runtime cost,
22
+ * which is what keeps every `ts.SourceFile` annotation below unchanged.
23
+ */
24
+ let _ts: typeof ts | undefined
25
+ function tsc(): typeof ts {
26
+ // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
27
+ return (_ts ??= require("typescript") as typeof ts)
28
+ }
29
+
2
30
  import { readFile, writeFile } from "node:fs/promises"
31
+ import { readFileSync } from "node:fs"
3
32
  import { join } from "node:path"
4
33
  import { err } from "@arcforge/err"
5
34
  import { fsx } from "../../utils/fs"
@@ -59,21 +88,21 @@ function locate(path: string, text: string, field = "extensions"): Located | nul
59
88
  const visit = (node: ts.Node): void => {
60
89
  if (found) return
61
90
  if (
62
- ts.isCallExpression(node)
63
- && ts.isIdentifier(node.expression)
91
+ tsc().isCallExpression(node)
92
+ && tsc().isIdentifier(node.expression)
64
93
  && node.expression.text === "defineProfile"
65
94
  && node.arguments.length > 0
66
95
  ) {
67
96
  const arg = node.arguments[0]
68
- if (arg && ts.isObjectLiteralExpression(arg)) {
97
+ if (arg && tsc().isObjectLiteralExpression(arg)) {
69
98
  const value = tsast.prop(arg, field)
70
- if (value && ts.isArrayLiteralExpression(value)) {
99
+ if (value && tsc().isArrayLiteralExpression(value)) {
71
100
  found = value
72
101
  return
73
102
  }
74
103
  }
75
104
  }
76
- ts.forEachChild(node, visit)
105
+ tsc().forEachChild(node, visit)
77
106
  }
78
107
  visit(source)
79
108
 
@@ -95,7 +124,7 @@ function locateObject(path: string, text: string): { object: ts.ObjectLiteralExp
95
124
  tsast.visitCalls(source, "defineProfile", call => {
96
125
  if (found) return
97
126
  const arg = call.arguments[0]
98
- if (arg && ts.isObjectLiteralExpression(arg)) found = arg
127
+ if (arg && tsc().isObjectLiteralExpression(arg)) found = arg
99
128
  })
100
129
 
101
130
  return found ? { object: found, source } : null
@@ -103,10 +132,10 @@ function locateObject(path: string, text: string): { object: ts.ObjectLiteralExp
103
132
 
104
133
  /** The `source` string of one entry — a bare string, or the `source:` of an object form. */
105
134
  function sourceOf(element: ts.Expression): string | null {
106
- if (ts.isStringLiteralLike(element)) return element.text
107
- if (ts.isObjectLiteralExpression(element)) {
135
+ if (tsc().isStringLiteralLike(element)) return element.text
136
+ if (tsc().isObjectLiteralExpression(element)) {
108
137
  const value = tsast.prop(element, "source")
109
- return value && ts.isStringLiteralLike(value) ? value.text : null
138
+ return value && tsc().isStringLiteralLike(value) ? value.text : null
110
139
  }
111
140
  return null
112
141
  }
@@ -270,7 +299,7 @@ function indentOf(text: string, offset: number): number {
270
299
  * result that does not parse is never written.
271
300
  */
272
301
  function verified(next: string, path: string): string {
273
- const parsed = ts.createSourceFile(path, next, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
302
+ const parsed = tsc().createSourceFile(path, next, tsc().ScriptTarget.Latest, true, tsc().ScriptKind.TS)
274
303
  // `parseDiagnostics` is not on the public type but is populated by the
275
304
  // parser; an empty list is the only acceptable outcome here.
276
305
  const diagnostics = (parsed as unknown as { parseDiagnostics?: readonly unknown[] }).parseDiagnostics ?? []
@@ -300,18 +329,18 @@ function locateConfig(path: string, text: string): { object: ts.ObjectLiteralExp
300
329
  const visit = (node: ts.Node): void => {
301
330
  if (found) return
302
331
  if (
303
- ts.isCallExpression(node)
304
- && ts.isIdentifier(node.expression)
332
+ tsc().isCallExpression(node)
333
+ && tsc().isIdentifier(node.expression)
305
334
  && node.expression.text === "defineProfile"
306
335
  && node.arguments.length > 0
307
336
  ) {
308
337
  const arg = node.arguments[0]
309
- if (arg && ts.isObjectLiteralExpression(arg)) {
338
+ if (arg && tsc().isObjectLiteralExpression(arg)) {
310
339
  found = arg
311
340
  return
312
341
  }
313
342
  }
314
- ts.forEachChild(node, visit)
343
+ tsc().forEachChild(node, visit)
315
344
  }
316
345
  visit(source)
317
346
 
@@ -323,12 +352,42 @@ export async function readSettings(profileRoot: string): Promise<Record<string,
323
352
  const path = configPath(profileRoot)
324
353
  if (!fsx.exists(path)) return {}
325
354
 
326
- const text = await readFile(path, "utf-8")
355
+ return settingsOf(path, await readFile(path, "utf-8"))
356
+ }
357
+
358
+ /**
359
+ * The same read, synchronously.
360
+ *
361
+ * Exists because `extraRoots()` is synchronous and so is every caller of it —
362
+ * an agent scan, a session listing, a name resolution. Those cannot await, so
363
+ * before this the only way `paths` reached them was a cache someone had
364
+ * remembered to fill by calling `refreshSettings()` first.
365
+ *
366
+ * The TUI fills that cache inside `extensions.load()`, which is deliberately
367
+ * NOT awaited before the first frame (a cold install must not hold up the
368
+ * terminal). So there was a window — seconds, longer on a cold start — where
369
+ * every watched root was invisible: `^` reported "no past sessions" for an
370
+ * agent with 563 of them on disk, silently, because an empty list is exactly
371
+ * what a genuinely new agent looks like.
372
+ *
373
+ * This is an AST read of one file — no import, no evaluation, no lock — which
374
+ * is the same reason `readPolicy` is safe to call on every agent load. The
375
+ * cost is a file read and a parse, and it happens once per cache fill.
376
+ */
377
+ export function readSettingsSync(profileRoot: string): Record<string, unknown> {
378
+ const path = configPath(profileRoot)
379
+ if (!fsx.exists(path)) return {}
380
+
381
+ return settingsOf(path, readFileSync(path, "utf-8"))
382
+ }
383
+
384
+ /** The shared parse — one implementation, so the two readers cannot disagree. */
385
+ function settingsOf(path: string, text: string): Record<string, unknown> {
327
386
  const located = locateConfig(path, text)
328
387
  if (!located) return {}
329
388
 
330
389
  const value = tsast.prop(located.object, "settings")
331
- if (!value || !ts.isObjectLiteralExpression(value)) return {}
390
+ if (!value || !tsc().isObjectLiteralExpression(value)) return {}
332
391
  return literalOf(value) as Record<string, unknown>
333
392
  }
334
393
 
@@ -359,7 +418,7 @@ export async function readPolicy(profileRoot: string): Promise<Record<string, un
359
418
  if (!located) return {}
360
419
 
361
420
  const value = tsast.prop(located.object, "policy")
362
- if (!value || !ts.isObjectLiteralExpression(value)) return {}
421
+ if (!value || !tsc().isObjectLiteralExpression(value)) return {}
363
422
  return literalOf(value) as Record<string, unknown>
364
423
  }
365
424
 
@@ -419,13 +478,13 @@ export async function setSetting(profileRoot: string, key: string, value: unknow
419
478
  const current = await readSettings(profileRoot)
420
479
  if (JSON.stringify(current[key]) === JSON.stringify(value)) return { changed: false }
421
480
 
422
- if (settings && ts.isObjectLiteralExpression(settings)) {
481
+ if (settings && tsc().isObjectLiteralExpression(settings)) {
423
482
  const existing = settings.properties.find(
424
- prop => ts.isPropertyAssignment(prop) && nameOf(prop.name) === key,
483
+ prop => tsc().isPropertyAssignment(prop) && nameOf(prop.name) === key,
425
484
  )
426
485
  const inner = indentOf(text, settings.getStart(located.source)) + 4
427
486
 
428
- if (existing && ts.isPropertyAssignment(existing)) {
487
+ if (existing && tsc().isPropertyAssignment(existing)) {
429
488
  // Replace just the value, so the key keeps its place in the block.
430
489
  const next = text.slice(0, existing.initializer.getStart(located.source))
431
490
  + render(value, inner)
@@ -485,8 +544,8 @@ export async function setSetting(profileRoot: string, key: string, value: unknow
485
544
 
486
545
  /** A property key as written — identifier or string literal. */
487
546
  function nameOf(name: ts.PropertyName): string | null {
488
- if (ts.isIdentifier(name)) return name.text
489
- if (ts.isStringLiteralLike(name)) return name.text
547
+ if (tsc().isIdentifier(name)) return name.text
548
+ if (tsc().isStringLiteralLike(name)) return name.text
490
549
  return null
491
550
  }
492
551
 
@@ -496,15 +555,15 @@ function nameOf(name: ts.PropertyName): string | null {
496
555
  * be worse than reporting the key as unset.
497
556
  */
498
557
  function literalOf(node: ts.Expression): unknown {
499
- if (ts.isStringLiteralLike(node)) return node.text
500
- if (ts.isNumericLiteral(node)) return Number(node.text)
501
- if (node.kind === ts.SyntaxKind.TrueKeyword) return true
502
- if (node.kind === ts.SyntaxKind.FalseKeyword) return false
503
- if (ts.isArrayLiteralExpression(node)) return node.elements.map(literalOf)
504
- if (ts.isObjectLiteralExpression(node)) {
558
+ if (tsc().isStringLiteralLike(node)) return node.text
559
+ if (tsc().isNumericLiteral(node)) return Number(node.text)
560
+ if (node.kind === tsc().SyntaxKind.TrueKeyword) return true
561
+ if (node.kind === tsc().SyntaxKind.FalseKeyword) return false
562
+ if (tsc().isArrayLiteralExpression(node)) return node.elements.map(literalOf)
563
+ if (tsc().isObjectLiteralExpression(node)) {
505
564
  const out: Record<string, unknown> = {}
506
565
  for (const prop of node.properties) {
507
- if (!ts.isPropertyAssignment(prop)) continue
566
+ if (!tsc().isPropertyAssignment(prop)) continue
508
567
  const key = nameOf(prop.name)
509
568
  if (key !== null) out[key] = literalOf(prop.initializer)
510
569
  }
@@ -554,13 +613,13 @@ function render(value: unknown, indent: number): string {
554
613
  * touching it would be worse than ignoring it.
555
614
  */
556
615
  function factoryOf(element: ts.Expression): string | null {
557
- if (!ts.isCallExpression(element)) return null
558
- return ts.isIdentifier(element.expression) ? element.expression.text : null
616
+ if (!tsc().isCallExpression(element)) return null
617
+ return tsc().isIdentifier(element.expression) ? element.expression.text : null
559
618
  }
560
619
 
561
620
  /** Whether a `providers:` element was written with options — `Ollama({ url })` rather than `Ollama()`. */
562
621
  function hasOptions(element: ts.Expression): boolean {
563
- return ts.isCallExpression(element) && element.arguments.length > 0
622
+ return tsc().isCallExpression(element) && element.arguments.length > 0
564
623
  }
565
624
 
566
625
  /** The provider factories a profile declares, in order. */
@@ -5,6 +5,6 @@
5
5
 
6
6
  export { Extensions, type ExtensionsT, type ExtensionsResult, type ExtensionUpdate } from "./extensions"
7
7
  export { ProfileConfigFile, resolveEntry, type ResolvedEntry, type ProfileConfigResult } from "./config"
8
- export { addEntry, addProvider, readEntries, readPolicy, readProviders, readSettings, removeEntry, removeProvider, setSetting, type EditResult } from "./edit"
8
+ export { addEntry, addProvider, readEntries, readPolicy, readProviders, readSettings, readSettingsSync, removeEntry, removeProvider, setSetting, type EditResult } from "./edit"
9
9
  export { DisposerSink, type LoadedSource, type LoadedFile } from "./load"
10
10
  export { ExtensionStore, formatRef, parseRef, type ExtensionStoreT, type StoredExtension } from "./store"
@@ -1,4 +1,27 @@
1
- import ts from "typescript"
1
+ import type ts from "typescript"
2
+
3
+ /**
4
+ * The TypeScript compiler, loaded on FIRST USE rather than at import.
5
+ *
6
+ * `typescript` costs ~190-220ms to load, and it was being pulled into every
7
+ * `axon` invocation through this module's import chain — before argument
8
+ * parsing, before any command ran, before a character reached the screen.
9
+ * `axon dev` showing nothing for a second was largely this.
10
+ *
11
+ * Nothing here touches `ts` at module scope; every reference is inside a
12
+ * function body. So deferring costs the first caller the load and every
13
+ * command that parses no source file nothing at all.
14
+ *
15
+ * `require`, not `await import`: these APIs are synchronous and making them
16
+ * async would ripple through every caller for no gain. The type import above
17
+ * is erased at compile time, which keeps every `ts.X` annotation unchanged.
18
+ */
19
+ let _ts: typeof ts | undefined
20
+ function tsc(): typeof ts {
21
+ // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
22
+ return (_ts ??= require("typescript") as typeof ts)
23
+ }
24
+
2
25
  import { join } from "node:path"
3
26
  import { readFileSync, readdirSync } from "node:fs"
4
27
  import { fsx } from "../../utils/fs"
@@ -23,7 +46,7 @@ import { tsast } from "../../utils/tsast"
23
46
  * case, so a computed name still typechecks — it simply does not complete.
24
47
  *
25
48
  * A parse, not a program: only the shape of the call site matters, so there is
26
- * no need for `ts.createProgram` and its type checker. That keeps this fast
49
+ * no need for `tsc().createProgram` and its type checker. That keeps this fast
27
50
  * enough to run on every config reload rather than only on prepare.
28
51
  */
29
52
 
@@ -68,12 +91,12 @@ const CALLS: Record<string, keyof Registrations> = {
68
91
  * `commands.run()` addresses it.
69
92
  */
70
93
  function nameOf(arg: ts.Expression): string | null {
71
- if (ts.isStringLiteralLike(arg)) return arg.text
94
+ if (tsc().isStringLiteralLike(arg)) return arg.text
72
95
 
73
- if (ts.isArrayLiteralExpression(arg)) {
96
+ if (tsc().isArrayLiteralExpression(arg)) {
74
97
  const parts: string[] = []
75
98
  for (const element of arg.elements) {
76
- if (!ts.isStringLiteralLike(element)) return null
99
+ if (!tsc().isStringLiteralLike(element)) return null
77
100
  parts.push(element.text)
78
101
  }
79
102
  return parts.length > 0 ? parts.join(" ") : null
@@ -99,7 +122,7 @@ export function readRegistrations(filePath: string): Registrations {
99
122
  const file = tsast.parse(filePath, source)
100
123
 
101
124
  const visit = (node: ts.Node): void => {
102
- if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
125
+ if (tsc().isCallExpression(node) && tsc().isPropertyAccessExpression(node.expression)) {
103
126
  const target = `${node.expression.expression.getText(file)}.${node.expression.name.getText(file)}`
104
127
  const bucket = CALLS[target]
105
128
  const first = node.arguments[0]
@@ -119,7 +142,7 @@ export function readRegistrations(filePath: string): Registrations {
119
142
  }
120
143
  }
121
144
  }
122
- ts.forEachChild(node, visit)
145
+ tsc().forEachChild(node, visit)
123
146
  }
124
147
 
125
148
  visit(file)
@@ -129,7 +152,7 @@ export function readRegistrations(filePath: string): Registrations {
129
152
  /** Walk up to the statement a call belongs to — where its JSDoc lives. */
130
153
  function findStatement(node: ts.Node): ts.Node | undefined {
131
154
  let current: ts.Node | undefined = node
132
- while (current && !ts.isSourceFile(current.parent)) current = current.parent
155
+ while (current && !tsc().isSourceFile(current.parent)) current = current.parent
133
156
  return current
134
157
  }
135
158
 
@@ -48,13 +48,21 @@ export function Agent(opts: AgentOpts) {
48
48
 
49
49
  return {
50
50
  async build(): Promise<BundleResult> {
51
+ const loaded = await Config(root)
52
+
51
53
  // Before anything is compiled or staged. A config that reaches
52
54
  // outside the project cannot be published, and finding that out
53
55
  // after a bundle exists costs a build nobody wanted — finding it
54
56
  // out in a container costs a provisioned deployment.
55
- await assertConfigContained(root, join(root, "axon.config.ts"))
56
-
57
- const loaded = await Config(root)
57
+ //
58
+ // Runs after Config() only so the DECLARED source modules are
59
+ // known: those legitimately live outside the root and are staged in
60
+ // with their imports rebased, so they are the one escape that is
61
+ // not one. Still before any compile or stage, which is what the
62
+ // "fail cheaply" reasoning above actually requires.
63
+ await assertConfigContained(root, join(root, "axon.config.ts"), (
64
+ await flatten(loaded.modules, loaded.modulePaths)
65
+ ).flatMap(entry => (entry.kind === "source" ? [entry.configPath] : [])))
58
66
  const config = loaded.value as PublishableConfig
59
67
  const pkg = await artifacts.identity()
60
68
 
@@ -80,12 +80,34 @@ export function escapingImports(source: string, configPath: string, root: string
80
80
  return found
81
81
  }
82
82
 
83
- /** Throw if the project's config imports anything from outside `root`. */
84
- export async function assertConfigContained(root: string, configPath: string): Promise<void> {
83
+ /**
84
+ * Throw if the project's config imports anything from outside `root`.
85
+ *
86
+ * `staged` names the config paths of DECLARED SOURCE MODULES — the one kind of
87
+ * outside-the-root import that is legitimate. A source module lives outside the
88
+ * agent tree by definition, and the bundler copies it into `modules/<name>/`
89
+ * and rebases every import that reaches it (see stageSourceModules). So its
90
+ * specifier escapes the root as written and does not escape the BUNDLE, which
91
+ * is what this guard is actually about.
92
+ *
93
+ * Without the exemption the two features were mutually exclusive: this runs
94
+ * before staging, could not tell a staged module from a genuine escape, and
95
+ * rejected every agent that used one.
96
+ */
97
+ export async function assertConfigContained(root: string, configPath: string, staged: readonly string[] = []): Promise<void> {
85
98
  const source = await readFile(configPath, "utf-8").catch(() => null)
86
99
  if (source === null) return
87
100
 
101
+ // Compared as RESOLVED paths, never as written specifiers: the same module
102
+ // is `../mod/module.config` from one config and `../../mod/module.config`
103
+ // from another, and only the resolved form is the same string in both.
104
+ // Extension-insensitive on both sides: a config path is absolute and
105
+ // carries `.ts`, while the specifier that names it is extensionless
106
+ // (`../mod/module.config`), which is how TypeScript is written.
107
+ const bare = (path: string): string => path.replace(/\.[cm]?tsx?$/, "")
108
+ const exempt = new Set(staged.map(path => bare(resolve(path))))
88
109
  const escaping = escapingImports(source, configPath, root)
110
+ .filter(entry => !exempt.has(bare(resolve(dirname(configPath), entry.specifier))))
89
111
  if (escaping.length === 0) return
90
112
 
91
113
  const where = escaping
@@ -1,6 +1,29 @@
1
+ import type ts from "typescript"
2
+
3
+ /**
4
+ * The TypeScript compiler, loaded on FIRST USE rather than at import.
5
+ *
6
+ * `typescript` costs ~190-220ms to load, and it was being pulled into every
7
+ * `axon` invocation through this module's import chain — before argument
8
+ * parsing, before any command ran, before a character reached the screen.
9
+ * `axon dev` showing nothing for a second was largely this.
10
+ *
11
+ * Nothing here touches `ts` at module scope; every reference is inside a
12
+ * function body. So deferring costs the first caller the load and every
13
+ * command that parses no source file nothing at all.
14
+ *
15
+ * `require`, not `await import`: these APIs are synchronous and making them
16
+ * async would ripple through every caller for no gain. The type import above
17
+ * is erased at compile time, which keeps every `ts.X` annotation unchanged.
18
+ */
19
+ let _ts: typeof ts | undefined
20
+ function tsc(): typeof ts {
21
+ // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
22
+ return (_ts ??= require("typescript") as typeof ts)
23
+ }
24
+
1
25
  import { readFile, writeFile } from "node:fs/promises"
2
26
  import { join } from "node:path"
3
- import ts from "typescript"
4
27
  import { err } from "@arcforge/err"
5
28
  import { tsast } from "../../../utils/tsast"
6
29
 
@@ -40,7 +63,7 @@ export function Model(opts: ModelOpts) {
40
63
  tsast.visitCalls(source, "defineAgent", call => {
41
64
  if (found) return
42
65
  const argument = call.arguments[0]
43
- if (argument && ts.isObjectLiteralExpression(argument)) found = argument
66
+ if (argument && tsc().isObjectLiteralExpression(argument)) found = argument
44
67
  })
45
68
 
46
69
  return found
@@ -59,9 +82,9 @@ export function Model(opts: ModelOpts) {
59
82
  if (!object) return null
60
83
 
61
84
  for (const property of object.properties) {
62
- if (!ts.isPropertyAssignment(property)) continue
85
+ if (!tsc().isPropertyAssignment(property)) continue
63
86
  if (property.name.getText(source) !== "model") continue
64
- if (!ts.isStringLiteral(property.initializer)) continue
87
+ if (!tsc().isStringLiteral(property.initializer)) continue
65
88
  return property.initializer.text
66
89
  }
67
90
  return null
@@ -87,10 +110,10 @@ export function Model(opts: ModelOpts) {
87
110
  }
88
111
 
89
112
  for (const property of object.properties) {
90
- if (!ts.isPropertyAssignment(property)) continue
113
+ if (!tsc().isPropertyAssignment(property)) continue
91
114
  if (property.name.getText(source) !== "model") continue
92
115
 
93
- if (ts.isStringLiteral(property.initializer) && property.initializer.text === model) {
116
+ if (tsc().isStringLiteral(property.initializer) && property.initializer.text === model) {
94
117
  return { changed: false }
95
118
  }
96
119
 
@@ -182,7 +182,27 @@ export function Package(opts: PackageOpts) {
182
182
  const path = join(opts.root, "package.json")
183
183
 
184
184
  async function read(): Promise<PackageJson> {
185
- return JSON.parse(await readFile(path, "utf-8")) as PackageJson
185
+ // A missing or unparseable manifest is a legible PROJECT failure, and
186
+ // this is the single reader — so the translation happens once, here,
187
+ // rather than at each of the dozen call sites.
188
+ //
189
+ // It used to escape raw. `bundle()` runs `prepare()` first, which
190
+ // reaches this through `dependencies.ensure()`, so a project with no
191
+ // package.json failed with `ENOENT ... open '/tmp/.../package.json'`
192
+ // long before Artifacts.identity() — which raises a proper
193
+ // BUNDLE_INVALID naming the root — ever ran. The careful error existed
194
+ // and was simply unreachable.
195
+ let source: string
196
+ try {
197
+ source = await readFile(path, "utf-8")
198
+ } catch (cause) {
199
+ throw err("BUNDLE_INVALID", { detail: `no package.json at ${opts.root}`, context: { root: opts.root, path }, cause })
200
+ }
201
+ try {
202
+ return JSON.parse(source) as PackageJson
203
+ } catch (cause) {
204
+ throw err("BUNDLE_INVALID", { detail: `package.json at ${opts.root} is not valid JSON`, context: { root: opts.root, path }, cause })
205
+ }
186
206
  }
187
207
 
188
208
  async function write(pkg: PackageJson): Promise<void> {
@@ -430,6 +430,22 @@ export async function Agent(opts: AgentOpts) {
430
430
  async function bootLinked(confined: NonNullable<AgentOpts["confined"]>): Promise<LinkedRuntime> {
431
431
  return span(recorder, "build", { root: project.root }, async () => {
432
432
  const loaded = await build()
433
+
434
+ /**
435
+ * The build is done; the runtime is coming up.
436
+ *
437
+ * Raised HERE because there is no build event to map it from —
438
+ * `axon:boot:start` is committed by Axon()'s own session, inside
439
+ * the agent, and never reaches this recorder. `stageFor` says as
440
+ * much and expects Agent() to raise it directly at this exact
441
+ * moment. Nothing did, so `booting` was a stage the type declared,
442
+ * the display ordered, and no code ever emitted: a surface showing
443
+ * it had a row that could only ever read as skipped, and the time
444
+ * the runtime took to come up was silently attributed to whatever
445
+ * ran before it.
446
+ */
447
+ raise({ stage: "booting" })
448
+
433
449
  const linked = await confined({
434
450
  blueprint: { ...loaded, session: { id: sessionId } },
435
451
  sessionId,
@@ -370,7 +370,44 @@ export function Instances(opts: InstancesOpts) {
370
370
  * it.
371
371
  */
372
372
  async reload(): Promise<void> {
373
- current = await rescan()
373
+ /**
374
+ * The rescan half is the PLATFORM'S, so its failure is
375
+ * recorded here.
376
+ *
377
+ * `axon:reload:*` is emitted by the agent's own
378
+ * runtime.update() — but a reload that dies in the
379
+ * rescan never reaches the agent, so nothing emitted
380
+ * anything at all. A caller got a rejected promise and
381
+ * a session log with no record of what broke, which is
382
+ * exactly the untraced path the span exists to close:
383
+ * "I saved a typo in axon.config.ts and the agent went
384
+ * quiet" left no evidence on the durable record.
385
+ *
386
+ * The span is OPENED AND CLOSED together on this path.
387
+ * A bare `:failed` is its own ontology break — it
388
+ * leaves an unpaired bracket for anything that counts
389
+ * span depth, the same defect as a close with no open.
390
+ * On the SUCCESS path nothing is emitted here: the
391
+ * rescan simply continues into the agent, which opens
392
+ * and closes the span itself, so emitting a start here
393
+ * too would double every successful reload.
394
+ */
395
+ const started = Date.now()
396
+ let next: unknown
397
+ try {
398
+ next = await rescan()
399
+ } catch (cause) {
400
+ const failure = err(cause)
401
+ // Revision 0: the agent numbers revisions, and a
402
+ // rescan that never reached it was never assigned
403
+ // one. Claiming a number the agent did not issue
404
+ // would put two different reloads on the same
405
+ // revision; 0 reads as "before any of the agent's".
406
+ await live.session.commit("axon:reload:start", { revision: 0 })
407
+ await live.session.commit("axon:reload:failed", { error: failure, durationMs: Date.now() - started })
408
+ throw failure
409
+ }
410
+ current = next as typeof current
374
411
  await live.link.update(current as never)
375
412
  },
376
413
  async shutdown(): Promise<void> {
@@ -4,7 +4,21 @@ import { ENTRY_EVENT_PREFIXES } from "@arcforge/types"
4
4
  /** One resumable session on disk — the durable record of a past (or current) conversation. */
5
5
  export type SessionRecord = {
6
6
  sessionId: string
7
- /** the agent project's name — where sessions/<id>.jsonl lives */
7
+ /**
8
+ * The agent's IDENTITY — `package.json`'s name (`@cody/barry.mk3`),
9
+ * falling back to the directory name when there is no readable manifest.
10
+ *
11
+ * Not the folder. It used to be, and the doc said "the agent project's
12
+ * name" — a phrase true of both readings, which is how a consumer came to
13
+ * compare it against a directory name and match nothing. `^` filtered
14
+ * `record.agent === "barry.mk3"` against `"@cody/barry.mk3"` and reported
15
+ * "no past sessions" for an agent with 216 of them; the unscoped agents on
16
+ * the same machine matched fine, so it looked intermittent rather than
17
+ * broken.
18
+ *
19
+ * This is the one true name for an agent: compare it against another
20
+ * identity (`project.name`), never against a directory.
21
+ */
8
22
  agent: string
9
23
  /** absolute path to the session's <id>.jsonl — read directly to preview without booting */
10
24
  filePath: string
package/src/platform.ts CHANGED
@@ -8,7 +8,7 @@ import { Deployments } from "./services/deployments"
8
8
  import { Projects } from "./build/project"
9
9
  import { Profile, Runtime } from "./build/runtime"
10
10
  import type { AgentSupervisor } from "./build/runtime/instances"
11
- import { Extensions, ProfileConfigFile } from "./build/extensions"
11
+ import { Extensions, ProfileConfigFile, readSettingsSync } from "./build/extensions"
12
12
  import { Resources } from "./services/resources"
13
13
 
14
14
  import { TestRunner } from "./services/test"
@@ -52,12 +52,40 @@ export function Platform(opts: PlatformOpts) {
52
52
  * A cached synchronous snapshot, because `extraRoots()` is synchronous and
53
53
  * every caller of it is: parsing TypeScript per call, on a path resolved
54
54
  * during an agent scan, is not something to do lazily.
55
+ *
56
+ * `null` means UNREAD, which is not the same as "declares nothing" — and
57
+ * conflating them is the bug this distinction exists to kill. It began as
58
+ * `{}`, so every read before someone called `refreshSettings()` answered
59
+ * "no watched roots" with total confidence. The TUI fills the cache inside
60
+ * `extensions.load()`, which is deliberately not awaited before the first
61
+ * frame, so that window was seconds wide on a warm boot and longer on a
62
+ * cold one: `^` listed nothing for an agent with hundreds of sessions on
63
+ * disk, and an agent resolved by a watched path could not be found at all.
64
+ */
65
+ let settingsCache: { paths?: string[] } | null = null
66
+
67
+ /**
68
+ * The settings, filling the cache on first read.
69
+ *
70
+ * Lazy rather than eager because construction is WIRING — a factory does
71
+ * no fs work — but a synchronous reader that cannot await still has to get
72
+ * a real answer. The read is one file and an AST parse, no evaluation and
73
+ * no lock (see readSettingsSync), and it happens once.
55
74
  */
56
- let settingsCache: { paths?: string[] } = {}
75
+ function settings(): { paths?: string[] } {
76
+ if (settingsCache) return settingsCache
77
+ const profile = store.profiles.active()
78
+ // No profile yet (a first boot before login) genuinely declares
79
+ // nothing. NOT cached: a profile appearing later must be read then,
80
+ // and caching {} here would pin the empty answer for the process.
81
+ if (!profile) return {}
82
+ settingsCache = readSettingsSync(profile.root) as { paths?: string[] }
83
+ return settingsCache
84
+ }
57
85
 
58
86
  const store = Store({
59
87
  root: opts.store ?? storeRoot(distribution),
60
- settings: () => settingsCache,
88
+ settings: settings,
61
89
  setSetting: async (key, value) => {
62
90
  const result = await extensions.setSetting(key, value)
63
91
  await refreshSettings()
@@ -176,9 +204,11 @@ export function Platform(opts: PlatformOpts) {
176
204
  */
177
205
  async function refreshSettings(): Promise<void> {
178
206
  // No profile yet (a first boot before login) is a real "nothing is
179
- // declared", not a failure — there is no config to read.
207
+ // declared", not a failure — there is no config to read. Cleared to
208
+ // null rather than {}: unread and empty are different answers, and
209
+ // a profile appearing later must be read rather than assumed empty.
180
210
  if (!store.profiles.active()) {
181
- settingsCache = {}
211
+ settingsCache = null
182
212
  return
183
213
  }
184
214
  // Deliberately NOT caught. An unreadable profile.config.ts used to
package/src/procs/tree.ts CHANGED
@@ -11,6 +11,13 @@ import type { AxonEventMap, CapsuleEventMap } from "@arcforge/types"
11
11
  * process that is down was alive when its agent stopped reporting. A remote
12
12
  * agent that goes unreachable leaves rows in exactly that state, and calling
13
13
  * them "exited" would invent an exit nobody observed.
14
+ *
15
+ * "pending" is the fourth: a spawn that was asked for but has not yet been
16
+ * mediated or launched. No row reaches this fold in that state — the log only
17
+ * learns about a process once `process:proc:start` carries a real pid — but
18
+ * the type admits it because a LIVE handle does, and a surface rendering both
19
+ * a folded row and a live one must not have two vocabularies for one
20
+ * lifecycle.
14
21
  */
15
22
  export type ProcNode = {
16
23
  procId: string
@@ -18,7 +25,7 @@ export type ProcNode = {
18
25
  command: string
19
26
  pid?: number
20
27
  cwd?: string
21
- status: "running" | "exited" | "down"
28
+ status: "pending" | "running" | "exited" | "down"
22
29
  exitCode?: number
23
30
  startedAt: number
24
31
  endedAt?: number
@@ -129,7 +129,12 @@ export type CapsuleRunOutcome = {
129
129
  ok: boolean
130
130
  value?: unknown
131
131
  stdout: string[]
132
- error?: { kind: "timeout" | "interrupt" | "exception"; message: string }
132
+ /**
133
+ * `policy` means the run was REFUSED, not that it broke — an editor
134
+ * surfacing this should say so rather than reporting a failure, for the
135
+ * same reason the TUI does not paint a denial red.
136
+ */
137
+ error?: { kind: "timeout" | "policy" | "interrupt" | "exception"; message: string }
133
138
  }
134
139
 
135
140
  /** Called BY the editor extension, implemented BY the tui. */
@@ -1,4 +1,32 @@
1
- import ts from "typescript"
1
+ import type ts from "typescript"
2
+
3
+ /**
4
+ * The TypeScript compiler, loaded on FIRST USE rather than at import.
5
+ *
6
+ * `typescript` costs ~223ms to load — roughly half of `@arcforge/platform`'s
7
+ * entire import time, which every `axon` invocation paid before a single line
8
+ * of any command ran. `axon dev` printing nothing for a second was mostly
9
+ * this: the progress surface could not paint because its own module graph was
10
+ * still loading a compiler it had no use for.
11
+ *
12
+ * Nothing here touches `ts` at module scope — every reference is inside a
13
+ * function body — so deferring the load costs the first caller ~223ms and
14
+ * every command that never parses a source file nothing at all.
15
+ *
16
+ * `require`, not `await import`: these are SYNCHRONOUS APIs
17
+ * (`readSettingsSync` is named for it, and is called during Platform()'s own
18
+ * settings read), so making them async would ripple through every caller for
19
+ * no gain. Bun resolves this from the same graph either way.
20
+ *
21
+ * The type import above is erased at compile time and carries no runtime cost,
22
+ * which is what keeps every `ts.SourceFile` annotation below unchanged.
23
+ */
24
+ let _ts: typeof ts | undefined
25
+ function tsc(): typeof ts {
26
+ // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
27
+ return (_ts ??= require("typescript") as typeof ts)
28
+ }
29
+
2
30
 
3
31
  /**
4
32
  * Shared TypeScript AST introspection tools — the one place source files
@@ -7,13 +35,13 @@ import ts from "typescript"
7
35
  */
8
36
  export const tsast = {
9
37
  parse(filePath: string, source: string): ts.SourceFile {
10
- return ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
38
+ return tsc().createSourceFile(filePath, source, tsc().ScriptTarget.Latest, true, tsc().ScriptKind.TS)
11
39
  },
12
40
 
13
41
  hasExportModifier(node: ts.Node): boolean {
14
- if (ts.canHaveModifiers(node)) {
15
- const mods = ts.getModifiers(node)
16
- return mods?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
42
+ if (tsc().canHaveModifiers(node)) {
43
+ const mods = tsc().getModifiers(node)
44
+ return mods?.some(m => m.kind === tsc().SyntaxKind.ExportKeyword) ?? false
17
45
  }
18
46
  return false
19
47
  },
@@ -55,7 +83,7 @@ export const tsast = {
55
83
 
56
84
  prop(obj: ts.ObjectLiteralExpression, key: string): ts.Expression | null {
57
85
  for (const p of obj.properties) {
58
- if (ts.isPropertyAssignment(p) && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) && p.name.text === key) {
86
+ if (tsc().isPropertyAssignment(p) && (tsc().isIdentifier(p.name) || tsc().isStringLiteral(p.name)) && p.name.text === key) {
59
87
  return p.initializer
60
88
  }
61
89
  }
@@ -64,39 +92,39 @@ export const tsast = {
64
92
 
65
93
  stringProp(obj: ts.ObjectLiteralExpression, key: string): string | null {
66
94
  const init = tsast.prop(obj, key)
67
- return init && ts.isStringLiteral(init) ? init.text : null
95
+ return init && tsc().isStringLiteral(init) ? init.text : null
68
96
  },
69
97
 
70
98
  boolProp(obj: ts.ObjectLiteralExpression, key: string): boolean | null {
71
99
  const init = tsast.prop(obj, key)
72
100
  if (!init) return null
73
- if (init.kind === ts.SyntaxKind.TrueKeyword) return true
74
- if (init.kind === ts.SyntaxKind.FalseKeyword) return false
101
+ if (init.kind === tsc().SyntaxKind.TrueKeyword) return true
102
+ if (init.kind === tsc().SyntaxKind.FalseKeyword) return false
75
103
  return null
76
104
  },
77
105
 
78
106
  objectProp(obj: ts.ObjectLiteralExpression, key: string): ts.ObjectLiteralExpression | null {
79
107
  const init = tsast.prop(obj, key)
80
- return init && ts.isObjectLiteralExpression(init) ? init : null
108
+ return init && tsc().isObjectLiteralExpression(init) ? init : null
81
109
  },
82
110
 
83
111
  /** Extract a primitive literal value (string/number/boolean), or undefined. */
84
112
  literal(node: ts.Expression): string | number | boolean | undefined {
85
- if (ts.isStringLiteral(node)) return node.text
86
- if (ts.isNumericLiteral(node)) return Number(node.text)
87
- if (node.kind === ts.SyntaxKind.TrueKeyword) return true
88
- if (node.kind === ts.SyntaxKind.FalseKeyword) return false
113
+ if (tsc().isStringLiteral(node)) return node.text
114
+ if (tsc().isNumericLiteral(node)) return Number(node.text)
115
+ if (node.kind === tsc().SyntaxKind.TrueKeyword) return true
116
+ if (node.kind === tsc().SyntaxKind.FalseKeyword) return false
89
117
  return undefined
90
118
  },
91
119
 
92
120
  /** Visit every call expression `name(...)` in a source file. */
93
121
  visitCalls(src: ts.SourceFile, name: string, visit: (call: ts.CallExpression) => void): void {
94
122
  function walk(node: ts.Node) {
95
- if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === name) {
123
+ if (tsc().isCallExpression(node) && tsc().isIdentifier(node.expression) && node.expression.text === name) {
96
124
  visit(node)
97
125
  }
98
- ts.forEachChild(node, walk)
126
+ tsc().forEachChild(node, walk)
99
127
  }
100
- ts.forEachChild(src, walk)
128
+ tsc().forEachChild(src, walk)
101
129
  },
102
130
  }