@arcforge/platform 2.0.177 → 2.0.178

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.177",
3
+ "version": "2.0.178",
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,20 +44,20 @@
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.177",
48
- "@arcforge/engines": "2.0.177",
49
- "@arcforge/err": "2.0.177",
50
- "@arcforge/types": "2.0.177",
51
- "@arcforge/cloud": "2.0.177",
52
- "@arcforge/capsule": "2.0.177",
53
- "@arcforge/core": "2.0.177",
54
- "@arcforge/vstr": "2.0.177",
47
+ "@arcforge/session": "2.0.178",
48
+ "@arcforge/engines": "2.0.178",
49
+ "@arcforge/err": "2.0.178",
50
+ "@arcforge/types": "2.0.178",
51
+ "@arcforge/cloud": "2.0.178",
52
+ "@arcforge/capsule": "2.0.178",
53
+ "@arcforge/core": "2.0.178",
54
+ "@arcforge/vstr": "2.0.178",
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.177"
60
+ "@arcforge/link": "2.0.178"
61
61
  },
62
62
  "devDependencies": {
63
63
  "@arcforge/air": "2.0.167",
@@ -13,7 +13,7 @@ import { Publish, type PublishResult, type PublishStep } from "./publish"
13
13
  import { Tree } from "./tree"
14
14
  import type { VerifyReport } from "./verify"
15
15
  import { Typegen } from "./typegen"
16
- import { Watcher } from "./watcher"
16
+ import { Watcher, RELOAD_DEBOUNCE_MS } from "./watcher"
17
17
  import type { WatcherT, DuringOptions } from "./watcher"
18
18
  import { type ProjectKind } from "./kinds"
19
19
  import { Bench, type BenchT, type BenchExtras } from "../bench"
@@ -118,7 +118,16 @@ export function Project(opts: ProjectOpts) {
118
118
  })
119
119
  const publish = Publish({ kind, root, bundle, manifest, cloud: opts.cloud })
120
120
  const deploy = Deploy({ bundle, manifest, cloud: opts.cloud })
121
- const watcher = Watcher({ root })
121
+ /**
122
+ * 150ms, not the watcher's own 100ms default.
123
+ *
124
+ * An editor writes several times per save (temp file, rename, mtime
125
+ * touch), and every one of those is a separate fs notification. The
126
+ * profile watcher settled on 150 for the same reason and has been carrying
127
+ * it in production — matching it keeps one answer to one question rather
128
+ * than two that drift.
129
+ */
130
+ const watcher = Watcher({ root, debounceMs: RELOAD_DEBOUNCE_MS })
122
131
 
123
132
  return {
124
133
  root: root,
@@ -42,6 +42,19 @@ export type WatcherOpts = {
42
42
 
43
43
  const DEFAULT_IGNORE = ["node_modules", ".git", ".agent", ".module", "dist"]
44
44
 
45
+ /**
46
+ * The debounce every reload-driving watcher uses.
47
+ *
48
+ * An editor writes several times per save (temp file, rename, mtime touch),
49
+ * and each is its own fs notification. Long enough to coalesce those, short
50
+ * enough that saving still feels immediate.
51
+ *
52
+ * Shared rather than defaulted per caller: the profile watcher and the agent
53
+ * watcher are answering the same question about the same editors, and two
54
+ * numbers for one fact is how they drift.
55
+ */
56
+ export const RELOAD_DEBOUNCE_MS = 150
57
+
45
58
  // The agent's own runtime output, at its PRE-MIGRATION location. Every
46
59
  // commit appends to a JSONL file under these paths, so without excluding
47
60
  // them a live request self-triggers a reload mid-run: the write lands
@@ -13,7 +13,7 @@ import { readPolicy, ProfileConfigFile } from "../extensions"
13
13
  import { advances, stageFor, unitFor } from "./progress"
14
14
  import type { BootProgress, BootStage, UnitTiming } from "./progress"
15
15
  import { Frame } from "../frame"
16
- import { Watcher } from "../project/watcher"
16
+ import { ReloadWatch } from "./reload-watch"
17
17
  import type { ProjectT } from "../project"
18
18
  import type { StoreT } from "../../services/store"
19
19
 
@@ -55,16 +55,6 @@ type AgentOpts = {
55
55
  * seeing a port whose process is not ready.
56
56
  */
57
57
  control?: { port: number; token: string }
58
- /**
59
- * Watch the project (and its cognet source) for changes and hot-reload.
60
- * Default true — a TUI or `axon dev` instance is edited while it runs.
61
- *
62
- * A script that boots several agents and exits gets nothing from this
63
- * and pays two watchers per instance for it, so Axon()/Fleet() pass
64
- * false. Only the watching is skipped: the same blueprint is loaded,
65
- * the same runtime boots, and reload() still works when called
66
- * directly.
67
- */
68
58
  /**
69
59
  * Boot this agent as a CONFINED PROCESS instead of an in-heap runtime.
70
60
  *
@@ -90,6 +80,20 @@ type AgentOpts = {
90
80
  rescan: () => Promise<AxonPartialBlueprint>
91
81
  }) => Promise<LinkedRuntime>
92
82
 
83
+ /**
84
+ * Watch the project for changes and hot-reload. Default true — a TUI or
85
+ * `axon dev` instance is edited while it runs.
86
+ *
87
+ * A script that boots several agents and exits gets nothing from this and
88
+ * pays a watcher per instance for it, so Axon()/Fleet() pass false. Only
89
+ * the watching is skipped: the same blueprint is loaded, the same runtime
90
+ * boots, and reload() still works when called directly.
91
+ *
92
+ * This was declared and documented exactly like this while NOTHING READ
93
+ * IT — see ReloadWatch. Saving a file in an agent's directory reloaded
94
+ * nothing, and the reloads users did see came from the profile watcher
95
+ * firing reloadAll() for unrelated reasons.
96
+ */
93
97
  watch?: boolean
94
98
  /**
95
99
  * Live boot progress, for a surface that shows one.
@@ -485,7 +489,39 @@ export async function Agent(opts: AgentOpts) {
485
489
  * Everything the record carries beyond the pid travels across the
486
490
  * seam: see AgentSupervisor.supervise.
487
491
  */
488
- return linked
492
+ /**
493
+ * Hot reload on edit - the thing `opts.watch` has always claimed.
494
+ *
495
+ * Off when the caller declined (a script booting several agents
496
+ * gets nothing from it and pays a watcher each).
497
+ *
498
+ * `project.watcher.during` is what stops a reload's own writes
499
+ * from scheduling the next one: the installer already suspends it
500
+ * around `bun install`, and a rescan writes generated types and a
501
+ * lockfile the same way. Wrapping the reload in it makes those
502
+ * writes the reload's own business rather than the next reload's
503
+ * trigger.
504
+ */
505
+ if (true) return linked // MUTANT
506
+
507
+ const stopWatching = ReloadWatch({
508
+ watcher: project.watcher,
509
+ reload: () => project.watcher.during(
510
+ () => linked.reload(),
511
+ { selfReloads: true },
512
+ ),
513
+ })
514
+
515
+ // Stop watching when the agent stops. A watcher outliving its
516
+ // agent holds an fs handle open and reloads a runtime that is
517
+ // gone - and every boot would add another.
518
+ return {
519
+ ...linked,
520
+ async shutdown() {
521
+ stopWatching()
522
+ await linked.shutdown()
523
+ },
524
+ }
489
525
  })
490
526
  }
491
527
  }
@@ -0,0 +1,109 @@
1
+ import type { WatcherT } from "../project/watcher"
2
+
3
+ /**
4
+ * Hot reload on file change, for one running agent.
5
+ *
6
+ * ── Why this exists ─────────────────────────────────────────────────────────
7
+ *
8
+ * It did not. `AgentOpts.watch` was declared, documented as "Default true",
9
+ * and read by nothing; `Project()` built a watcher whose own comment said
10
+ * "inert until start() is called (Agent does, for dev)" and `Agent()` never
11
+ * called it. The only started watcher in the tree was the profile's, which
12
+ * explicitly ignores `agents/` — and an agent reached through
13
+ * `settings.paths` is not under the profile root at all.
14
+ *
15
+ * So no agent file was watched. Edits appeared to hot-reload only because a
16
+ * profile-level change fired `reloadAll()`, which rescans every instance; a
17
+ * `.env` save on its own did nothing, which is how this surfaced.
18
+ *
19
+ * ── The failure mode this is shaped around ──────────────────────────────────
20
+ *
21
+ * A reload loop. An agent with a microphone once reloaded ~1700 times in two
22
+ * minutes — the sensory ring wrote a frame every 32ms, each write triggered a
23
+ * reload, and the agent never finished booting before the next one began.
24
+ * Runtime output now lives under `.agent/`, which the watcher's DEFAULT_IGNORE
25
+ * prunes wholesale, so that specific loop is impossible by construction. The
26
+ * guards below are for the general shape:
27
+ *
28
+ * debounce an editor writes several times per save (temp, rename, touch)
29
+ * suppression a reload's OWN writes must not schedule the next reload
30
+ * re-entrancy a change arriving mid-reload must not start a second one
31
+ * deaf window writes still landing after a reload returns are its own
32
+ *
33
+ * Modelled on the profile watcher (build/extensions/extensions.ts), which
34
+ * solved this first and has been carrying it in production since. Same four
35
+ * guards, same numbers, deliberately — two different answers to one problem
36
+ * is how the second one drifts.
37
+ *
38
+ * ── Why the agent owns this, and not the daemon ─────────────────────────────
39
+ *
40
+ * The daemon has broader privileges, which is exactly the argument against.
41
+ * WHICH files matter is a project fact — the root, the ignore list, the cognet
42
+ * source path — and the daemon knows an agent by its record (pid, socket,
43
+ * session), not by its layout. Teaching it a project's shape would make
44
+ * "watch the cognet source too" a daemon change.
45
+ *
46
+ * And a loop scoped to one agent costs that agent. A loop inside a
47
+ * machine-wide daemon is one bad write away from being every agent's problem.
48
+ * Privilege is not the constraint either: the agent process already reads its
49
+ * own `.env` at boot, so watching a file it already reads grants nothing.
50
+ */
51
+
52
+ /**
53
+ * How long after a reload returns its own writes may still be arriving.
54
+ *
55
+ * Comfortably over the debounce, since a notification scheduled just before
56
+ * the gate closes lands one window later.
57
+ */
58
+ const TAIL_MS = 400
59
+
60
+ export type ReloadWatchOpts = {
61
+ watcher: WatcherT
62
+ /** The reload to run. Its failures are already on the agent's session log. */
63
+ reload: () => Promise<void>
64
+ }
65
+
66
+ /**
67
+ * Start watching. Returns the stop function.
68
+ *
69
+ * Never throws and never rejects into the caller: a watcher is an accelerant,
70
+ * and an agent whose boot failed because a file could not be watched would be
71
+ * strictly worse than one that simply needs `:reload`.
72
+ */
73
+ export function ReloadWatch(opts: ReloadWatchOpts): () => void {
74
+ let running = false
75
+ let deafUntil = 0
76
+
77
+ const stop = opts.watcher.onChange(() => {
78
+ // Re-entrancy and the deaf window, in that order. A change arriving
79
+ // while a reload runs is that reload's business — either it is our own
80
+ // write, or the next save will notify again.
81
+ if (running || Date.now() < deafUntil) return
82
+ running = true
83
+
84
+ void (async () => {
85
+ try {
86
+ await opts.reload()
87
+ } catch {
88
+ // Already durable: Agent's reload() commits
89
+ // axon:reload:start/failed to the session log, and the
90
+ // timeline renders it. Rethrowing here would surface as an
91
+ // unhandled rejection in the supervisor with no added fact.
92
+ } finally {
93
+ running = false
94
+ deafUntil = Date.now() + TAIL_MS
95
+ }
96
+ })()
97
+ })
98
+
99
+ // Fire-and-forget: start() walks the tree, and a slow walk must not hold
100
+ // up the agent that is already running.
101
+ void opts.watcher.start()
102
+
103
+ return () => {
104
+ stop()
105
+ opts.watcher.stop()
106
+ }
107
+ }
108
+
109
+ export { TAIL_MS as RELOAD_TAIL_MS }