@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,125 @@
1
+ import type { PartSeries, Summary } from "./types"
2
+
3
+ /** Readings before this long into a session are start-up, and are left out of a growth rate. */
4
+ const WARMUP_MS = 60_000
5
+ /** A growth rate needs at least this many readings to mean anything. */
6
+ const LEAST = 5
7
+ /**
8
+ * A rate said of "lately" needs readings spanning at least this long: a
9
+ * collector's sawtooth is a hundred megabytes, and over half a minute it reads
10
+ * as tens of megabytes a minute of growth (measured 2026-10-09: a 109s session
11
+ * of a brain that levels off at 1.1GB read "still growing, 40MB a minute").
12
+ */
13
+ const LATELY_MS = 120_000
14
+ const MB = 1024 * 1024
15
+ /** How many of the machine's busiest processes are given back. */
16
+ const BUSIEST = 8
17
+
18
+ /**
19
+ * Resources — what the agent's processes used over a session: memory and
20
+ * whether it is growing, CPU and GPU, and which threads the CPU went to —
21
+ * and, beside them, how busy the whole machine was and with what.
22
+ *
23
+ * From the usage samples in the log, so it covers the whole session, not
24
+ * the telemetry window.
25
+ */
26
+ export function Resources() {
27
+ return {
28
+ /** Each part's memory, CPU and GPU, and each thread group's CPU, busiest first. `points` is how many readings of each series to give back. */
29
+ of(summary: Summary, points: number) {
30
+ const usage = summary.log.usage
31
+ const first = usage.at[0] ?? null
32
+ const last = usage.at[usage.at.length - 1] ?? null
33
+ return {
34
+ window: { fromMs: first, toMs: last, seconds: first !== null && last !== null ? Math.round((last - first) / 1000) : 0, samples: usage.at.length },
35
+ machine: usage.machine ? {
36
+ cores: usage.machine.cores,
37
+ ramMb: Math.round(usage.machine.ramTotal / MB),
38
+ cpuPercent: series.level(usage.machine.cpu),
39
+ // Over every sample, so a process busy for a tenth of the session reads as a tenth.
40
+ busiest: Object.entries(usage.machine.busiest)
41
+ .map(([name, group]) => ({ process: name, processes: group.threads, meanCores: round(group.totalCores / usage.at.length, 2), maxCores: round(group.maxCores, 2) }))
42
+ .sort((a, b) => b.meanCores - a.meanCores)
43
+ .slice(0, BUSIEST),
44
+ } : null,
45
+ parts: Object.fromEntries(Object.entries(usage.parts).map(([name, part]) => [name, read.part(usage.at, part, points)])),
46
+ threads: Object.entries(usage.threads)
47
+ .map(([name, group]) => ({ thread: name, threads: group.threads, meanCores: group.samples ? round(group.totalCores / group.samples, 2) : null, maxCores: round(group.maxCores, 2) }))
48
+ .sort((a, b) => (b.meanCores ?? 0) - (a.meanCores ?? 0)),
49
+ }
50
+ },
51
+ }
52
+ }
53
+
54
+ export type ResourcesT = ReturnType<typeof Resources>
55
+
56
+ const read = {
57
+ part(at: number[], part: PartSeries, points: number) {
58
+ const ram = series.measured(at, part.ram)
59
+ const vram = series.measured(at, part.vram)
60
+ const settled = ram.filter(reading => reading.at - at[0]! >= WARMUP_MS)
61
+ return {
62
+ shared: part.shared,
63
+ ramMb: ram.length ? {
64
+ first: round(ram[0]!.value / MB, 1),
65
+ last: round(ram[ram.length - 1]!.value / MB, 1),
66
+ peak: round(Math.max(...ram.map(reading => reading.value)) / MB, 1),
67
+ // After start-up: memory a process takes to boot is not memory it is leaking.
68
+ perMinute: series.slope(settled, 60_000 / MB),
69
+ // Over the later half alone: memory that rose and levelled off is not rising now. Null until that half is long enough to tell.
70
+ perMinuteLately: series.lately(settled.slice(Math.floor(settled.length / 2)), 60_000 / MB),
71
+ series: series.thin(ram, points).map(reading => round(reading.value / MB, 1)),
72
+ } : null,
73
+ cpuCores: series.level(part.cpu),
74
+ gpuPercent: series.level(part.gpu),
75
+ vramMb: vram.length ? { last: round(vram[vram.length - 1]!.value / MB, 1), peak: round(Math.max(...vram.map(reading => reading.value)) / MB, 1) } : null,
76
+ }
77
+ },
78
+ }
79
+
80
+ type Reading = { at: number; value: number }
81
+
82
+ const series = {
83
+ /** The readings that were taken, each with when. */
84
+ measured(at: number[], values: Array<number | null>): Reading[] {
85
+ return values.flatMap((value, index) => (value === null ? [] : [{ at: at[index]!, value: value }]))
86
+ },
87
+
88
+ /** The mean and the most of the readings taken; null when none was. */
89
+ level(values: Array<number | null>): { mean: number; max: number } | null {
90
+ const taken = values.filter((value): value is number => value !== null)
91
+ if (taken.length === 0) return null
92
+ return { mean: round(taken.reduce((sum, value) => sum + value, 0) / taken.length, 2), max: round(Math.max(...taken), 2) }
93
+ },
94
+
95
+ /** How fast the readings rise, by a line fitted through them, times `scale` — null with too few to say. */
96
+ slope(readings: Reading[], scale: number): number | null {
97
+ if (readings.length < LEAST) return null
98
+ const meanAt = readings.reduce((sum, reading) => sum + reading.at, 0) / readings.length
99
+ const meanValue = readings.reduce((sum, reading) => sum + reading.value, 0) / readings.length
100
+ let over = 0
101
+ let under = 0
102
+ for (const reading of readings) {
103
+ over += (reading.at - meanAt) * (reading.value - meanValue)
104
+ under += (reading.at - meanAt) ** 2
105
+ }
106
+ return under === 0 ? null : round(over / under * scale, 1)
107
+ },
108
+
109
+ /** The slope of readings spanning at least LATELY_MS — null over less: too short to tell growth from the collector's sawtooth. */
110
+ lately(readings: Reading[], scale: number): number | null {
111
+ if (readings.length === 0 || readings[readings.length - 1]!.at - readings[0]!.at < LATELY_MS) return null
112
+ return series.slope(readings, scale)
113
+ },
114
+
115
+ /** At most `points` of the readings, evenly spaced, always with the first and the last. */
116
+ thin(readings: Reading[], points: number): Reading[] {
117
+ if (readings.length <= points || points < 2) return readings
118
+ return Array.from({ length: points }, (_, index) => readings[Math.round(index * (readings.length - 1) / (points - 1))]!)
119
+ },
120
+ }
121
+
122
+ function round(value: number, places: number): number {
123
+ const unit = 10 ** places
124
+ return Math.round(value * unit) / unit
125
+ }
@@ -0,0 +1,31 @@
1
+ import { readFileSync } from "node:fs"
2
+ import { basename } from "node:path"
3
+ import { Decoder, home, type Decoded } from "@arcforge/session"
4
+
5
+ /**
6
+ * Ring — reads a session's telemetry: the binary window that holds every
7
+ * tick, system run and component write (see TELEMETRY_EVENTS).
8
+ *
9
+ * A window, not a record: the oldest segments are deleted as new ones are
10
+ * written, so what is here is the last stretch of the session and nothing
11
+ * before it. A segment decodes on its own.
12
+ */
13
+ export function Ring() {
14
+ return {
15
+ /** The segments still on disk, oldest first. */
16
+ segments(data: string, id: string): Array<{ name: string; file: string; bytes: number }> {
17
+ return home.data.telemetry.existing(data, id).map(segment => ({ name: basename(segment.file), file: segment.file, bytes: segment.bytes }))
18
+ },
19
+
20
+ /**
21
+ * Every event of one segment, in order. `numbers` is how a long run
22
+ * of them comes back: `array` as the log would give it, for an
23
+ * answer; `typed` for a reader that only counts, at a third the time.
24
+ */
25
+ read(file: string, numbers: "array" | "typed"): Decoded[] {
26
+ return Decoder({ numbers: numbers }).decode(new Uint8Array(readFileSync(file))).events
27
+ },
28
+ }
29
+ }
30
+
31
+ export type RingT = ReturnType<typeof Ring>
@@ -0,0 +1,90 @@
1
+ import { existsSync, readdirSync, statSync } from "node:fs"
2
+ import { join } from "node:path"
3
+ import { err } from "@arcforge/err"
4
+ import { home, Retention } from "@arcforge/session"
5
+ import { Frame } from "../build/frame"
6
+ import type { Found, Sizes } from "./types"
7
+
8
+ /**
9
+ * Sessions — finds an agent's sessions on disk, names one, says how much
10
+ * each holds, and removes what is no longer wanted.
11
+ */
12
+ export function Sessions() {
13
+ /** Where an agent keeps its data. */
14
+ function data(agent: string): string {
15
+ return Frame({ root: agent, kind: "agent" }).path("data")
16
+ }
17
+
18
+ /** Where a session's index is kept — beside the data, apart from the sessions so nothing lists it as one. */
19
+ function index(agent: string, id: string): string {
20
+ return join(data(agent), "debug", `${id}.json`)
21
+ }
22
+
23
+ /** Every session, newest first. */
24
+ function list(agent: string): Found[] {
25
+ const dir = join(data(agent), "sessions")
26
+ if (!existsSync(dir)) return []
27
+ return readdirSync(dir)
28
+ .filter(name => name.endsWith(".jsonl"))
29
+ .map(name => ({ id: name.slice(0, -".jsonl".length), file: join(dir, name), modifiedAt: statSync(join(dir, name)).mtimeMs }))
30
+ .sort((a, b) => b.modifiedAt - a.modifiedAt)
31
+ }
32
+
33
+ function sizes(agent: string, id: string): Sizes {
34
+ const root = data(agent)
35
+ const log = bytes(home.data.sessions.path(root, id))
36
+ const telemetry = bytes(home.data.telemetry.dir(root, id))
37
+ const sensory = bytes(home.data.sensory.dir(root, id))
38
+ const media = bytes(home.data.media.dir(root, id))
39
+ return { log: log, telemetry: telemetry, sensory: sensory, media: media, total: log + telemetry + sensory + media }
40
+ }
41
+
42
+ return {
43
+ data: data,
44
+ index: index,
45
+ list: list,
46
+ sizes: sizes,
47
+
48
+ /** The session a reference names: `latest`, an id, or any prefix of one that only one session has. */
49
+ resolve(agent: string, ref: string): Found {
50
+ const all = list(agent)
51
+ if (ref === "latest") {
52
+ if (!all[0]) throw err("SESSION_NOT_FOUND", { detail: `${agent} has no sessions` })
53
+ return all[0]
54
+ }
55
+ if (ref === "live") throw err("DEBUG_NOT_WIRED", { detail: "`live` is not wired yet — a running session's files are read the same way, so name it `latest`" })
56
+ const matching = all.filter(session => session.id.startsWith(ref))
57
+ if (matching.length === 0) throw err("SESSION_NOT_FOUND", { detail: `no session of ${agent} starts with "${ref}"` })
58
+ if (matching.length > 1) throw err("DEBUG_AMBIGUOUS", { detail: `"${ref}" names ${matching.length} sessions: ${matching.slice(0, 5).map(session => session.id).join(", ")}` })
59
+ return matching[0]!
60
+ },
61
+
62
+ /**
63
+ * What the retention rule removes now — the rule every session already
64
+ * applies as it opens (see Retention in @arcforge/session) — and, with
65
+ * `apply`, removing it. `days` and `gb` tighten or loosen the rule for
66
+ * this one prune.
67
+ */
68
+ async prune(agent: string, rule: { days?: number; gb?: number; apply: boolean }, now: number): Promise<{ removed: Array<{ id: string; bytes: number; why: "age" | "budget"; conversation: boolean }>; bytes: number; kept: number; remaining: number }> {
69
+ const retention = Retention({ root: data(agent) })
70
+ const plan = await retention.plan({ now: now, ...(rule.days !== undefined ? { days: rule.days } : {}), ...(rule.gb !== undefined ? { bytes: rule.gb * 1024 ** 3 } : {}) })
71
+ if (rule.apply) await retention.apply(plan)
72
+ return {
73
+ removed: plan.going.map(going => ({ id: going.id, bytes: going.freed, why: going.why, conversation: going.conversation })),
74
+ bytes: plan.going.reduce((sum, going) => sum + going.freed, 0),
75
+ kept: plan.kept,
76
+ remaining: plan.bytes,
77
+ }
78
+ },
79
+ }
80
+ }
81
+
82
+ export type SessionsT = ReturnType<typeof Sessions>
83
+
84
+ /** Bytes under a path: a file's own, or everything beneath a directory. Nothing for a path that is not there. */
85
+ function bytes(path: string): number {
86
+ if (!existsSync(path)) return 0
87
+ const stat = statSync(path)
88
+ if (!stat.isDirectory()) return stat.size
89
+ return readdirSync(path).reduce((sum, name) => sum + bytes(join(path, name)), 0)
90
+ }
@@ -0,0 +1,119 @@
1
+ import type { Channel, Fault, Trouble } from "./types"
2
+
3
+ /**
4
+ * What counts as a sign. A mind under nine tenths of its rate is slow; one
5
+ * tick in fifty over the deadline is a deadline being missed — on the main
6
+ * thread (`deadline`), or start to end, waiting on workers and lagged runs
7
+ * included (`late`, which names what it waited on); memory still
8
+ * rising ten megabytes a minute over the later half of a session is growth
9
+ * worth a look — memory that rose and levelled off is not. A machine busy
10
+ * past ninety percent on average has nothing left to give the mind, and
11
+ * every other number here is measured under that. Model calls whose
12
+ * durations add up to nine tenths of the time they were made in are a
13
+ * worker with no slack: past that they are waiting on each other. A sense
14
+ * heard at least twenty times that then falls silent for twenty of its own
15
+ * usual gaps — and at least ten seconds — before the session ends has gone
16
+ * quiet: a body lost, a cable dropped, while the mind ran on regardless.
17
+ */
18
+ const LIMITS = { rate: 0.9, over: 0.02, growthMb: 10, machine: 90, busy: 0.9, quiet: { heard: 20, gaps: 20, leastMs: 10_000 } }
19
+
20
+ export type Sign = { sign: "faults" | "failing" | "slow" | "deadline" | "late" | "memory" | "saturated" | "inference" | "troubles" | "quiet"; detail: string }
21
+
22
+ type Seen = {
23
+ faults: { total: number; first: Fault | null }
24
+ troubles: Trouble[]
25
+ ticks: { perSecond: number; targetPerSecond: number | null; targetMs: number | null; wall: { runs: number; maxMs: number }; late: number; main: { runs: number; maxMs: number }; overTarget: number }
26
+ /** The systems ticks waited on, longest wait first. */
27
+ held: Array<{ system: string; ticks: number; totalMs: number; maxMs: number }>
28
+ systems: Array<{ system: string; runs: number; failed: number }>
29
+ parts: Record<string, { shared: boolean; ramMb: { first: number; last: number; peak: number; perMinuteLately: number | null } | null; cpuCores: { mean: number } | null }>
30
+ machine: { cores: number; cpuPercent: { mean: number } | null; busiest: Array<{ process: string; meanCores: number }> } | null
31
+ inference: { busy: number | null; calls: number; behind: Array<{ already: number; calls: number }>; roles: Array<{ role: string; perSecond: number | null; p50Ms: number; busy: number | null }> }
32
+ /** Every stimulus channel heard, and when the session's log last heard anything at all. */
33
+ senses: { channels: Record<string, Channel>; lastMs: number | null }
34
+ }
35
+
36
+ /**
37
+ * Signs — the things that say a session is not well, read off what the
38
+ * other leaves measured. Each is one line, so one command says whether to
39
+ * look further and where.
40
+ *
41
+ * `checked` is every sign that was looked for: a sign missing from `found`
42
+ * is one that was checked and was fine, not one nobody looked at.
43
+ */
44
+ export function Signs() {
45
+ return {
46
+ of(seen: Seen): { found: Sign[]; checked: Sign["sign"][] } {
47
+ const found: Sign[] = []
48
+ const { ticks } = seen
49
+
50
+ if (seen.faults.total > 0) {
51
+ const first = seen.faults.first
52
+ found.push({ sign: "faults", detail: `${seen.faults.total} faults; the first: ${first ? `${first.type}${first.message ? ` — ${first.message}` : ""}` : "not kept"}` })
53
+ }
54
+
55
+ const failing = seen.systems.filter(system => system.failed > 0)
56
+ if (failing.length) found.push({ sign: "failing", detail: failing.map(system => `${system.system} failed ${system.failed} of ${system.runs} runs`).join("; ") })
57
+
58
+ if (ticks.targetPerSecond !== null && ticks.main.runs > 0 && ticks.perSecond < ticks.targetPerSecond * LIMITS.rate) {
59
+ found.push({ sign: "slow", detail: `${ticks.perSecond} ticks a second against a target of ${ticks.targetPerSecond}` })
60
+ }
61
+
62
+ if (ticks.main.runs > 0 && ticks.overTarget / ticks.main.runs > LIMITS.over) {
63
+ found.push({ sign: "deadline", detail: `${ticks.overTarget} of ${ticks.main.runs} ticks held the main thread past ${ticks.targetMs}ms; the worst ${ticks.main.maxMs}ms` })
64
+ }
65
+
66
+ // Late by the clock, not only the main thread: a worker or a lagged run the tick waited on counts.
67
+ if (ticks.wall.runs > 0 && ticks.late / ticks.wall.runs > LIMITS.over) {
68
+ const by = seen.held.slice(0, 3).map(one => `${one.system} for ${span(one.totalMs)} over ${one.ticks} ${one.ticks === 1 ? "tick" : "ticks"} (the worst ${one.maxMs}ms)`)
69
+ found.push({ sign: "late", detail: `${ticks.late} of ${ticks.wall.runs} ticks ran past ${ticks.targetMs}ms, the worst ${ticks.wall.maxMs}ms; ${by.length ? `held by ${by.join(", ")}` : "held by no system — the time was the tick's own"}` })
70
+ }
71
+
72
+ for (const [name, part] of Object.entries(seen.parts)) {
73
+ const ram = part.ramMb
74
+ if (!ram || ram.perMinuteLately === null || ram.perMinuteLately < LIMITS.growthMb) continue
75
+ found.push({ sign: "memory", detail: `${name}${part.shared ? " (shared)" : ""} is still growing, ${ram.perMinuteLately}MB a minute: ${ram.first}MB at first, ${ram.last}MB now, ${ram.peak}MB at most` })
76
+ }
77
+
78
+ const machine = seen.machine
79
+ if (machine?.cpuPercent && machine.cpuPercent.mean >= LIMITS.machine) {
80
+ const own = Object.entries(seen.parts).flatMap(([name, part]) => (part.cpuCores ? [`${name} ${part.cpuCores.mean}`] : []))
81
+ const busiest = machine.busiest.slice(0, 4).map(process => `${process.process} ${process.meanCores}`)
82
+ found.push({ sign: "saturated", detail: `the machine was ${Math.round(machine.cpuPercent.mean)}% busy across ${machine.cores} cores; this agent's parts, in cores: ${own.join(", ") || "unmeasured"}; the busiest processes on the machine: ${busiest.join(", ") || "not recorded in this session"}` })
83
+ }
84
+
85
+ const asked = seen.inference
86
+ if (asked.busy !== null && asked.busy >= LIMITS.busy) {
87
+ const free = asked.behind.find(row => row.already === 0)?.calls ?? 0
88
+ found.push({ sign: "inference", detail: `model calls took ${asked.busy} of the time they were made in — more than one worker has; ${free} of ${asked.calls} began with the worker free; ${asked.roles.map(role => `${role.role} ${role.perSecond}/s at ${role.p50Ms}ms`).join(", ")}` })
89
+ }
90
+
91
+ const open = new Map<string, string>()
92
+ for (const trouble of seen.troubles) {
93
+ if (trouble.opened) open.set(trouble.entity, trouble.detail ?? trouble.what ?? "")
94
+ else open.delete(trouble.entity)
95
+ }
96
+ if (open.size) found.push({ sign: "troubles", detail: [...open].map(([entity, detail]) => `${entity}: ${detail}`).join("; ") })
97
+
98
+ const end = seen.senses.lastMs
99
+ const quiet = end === null ? [] : Object.entries(seen.senses.channels).flatMap(([channel, heard]) => {
100
+ if (heard.count < LIMITS.quiet.heard) return []
101
+ const gap = (heard.lastMs - heard.firstMs) / (heard.count - 1)
102
+ const silent = end - heard.lastMs
103
+ if (silent < Math.max(LIMITS.quiet.leastMs, gap * LIMITS.quiet.gaps)) return []
104
+ const rate = Math.round(1000 / gap * 10) / 10
105
+ return [`${channel} fell silent ${Math.round(silent / 1000)}s before the end, after ${heard.count} arrivals at ${rate}/s`]
106
+ })
107
+ if (quiet.length) found.push({ sign: "quiet", detail: quiet.join("; ") })
108
+
109
+ return { found: found, checked: ["faults", "failing", "slow", "deadline", "late", "memory", "saturated", "inference", "troubles", "quiet"] }
110
+ },
111
+ }
112
+ }
113
+
114
+ export type SignsT = ReturnType<typeof Signs>
115
+
116
+ /** A length of time as a reader takes it in: milliseconds under a second, seconds to a tenth above. */
117
+ function span(ms: number): string {
118
+ return ms < 1000 ? `${Math.round(ms)}ms` : `${Math.round(ms / 100) / 10}s`
119
+ }
@@ -0,0 +1,44 @@
1
+ import type { Tally } from "./types"
2
+
3
+ /** The upper edge of each bucket a duration is counted in, ms. */
4
+ export const BOUNDS = [0.5, 1, 2, 3, 5, 8, 12, 20, 30, 50, 80, 120, 200, 300, 500, 800, 1200, 2000, 5000, Infinity]
5
+
6
+ /** Durations, counted — plain functions. */
7
+ export const tally = {
8
+ start(): Tally {
9
+ return { count: 0, totalMs: 0, maxMs: 0, hist: new Array<number>(BOUNDS.length).fill(0) }
10
+ },
11
+
12
+ add(into: Tally, ms: number): void {
13
+ into.count++
14
+ into.totalMs += ms
15
+ if (ms > into.maxMs) into.maxMs = ms
16
+ into.hist[BOUNDS.findIndex(bound => ms <= bound)]!++
17
+ },
18
+
19
+ merge(into: Tally, from: Tally): void {
20
+ into.count += from.count
21
+ into.totalMs += from.totalMs
22
+ if (from.maxMs > into.maxMs) into.maxMs = from.maxMs
23
+ from.hist.forEach((count, bucket) => { into.hist[bucket]! += count })
24
+ },
25
+
26
+ /**
27
+ * The duration `share` of runs came in under — to the edge of the bucket
28
+ * it falls in, so an upper bound and not the exact figure. The slowest
29
+ * bucket has no edge; the worst run stands in for it.
30
+ */
31
+ within(of: Tally, share: number): number {
32
+ if (of.count === 0) return 0
33
+ let seen = 0
34
+ for (let bucket = 0; bucket < BOUNDS.length; bucket++) {
35
+ seen += of.hist[bucket]!
36
+ if (seen >= of.count * share) return Math.min(BOUNDS[bucket]!, of.maxMs)
37
+ }
38
+ return of.maxMs
39
+ },
40
+
41
+ mean(of: Tally): number {
42
+ return of.count === 0 ? 0 : Math.round(of.totalMs / of.count * 100) / 100
43
+ },
44
+ }
@@ -0,0 +1,146 @@
1
+ import type { CognetEventMap } from "@arcforge/types"
2
+
3
+ /** The graph a mind declares at boot: its systems in run order, and every component they touch. */
4
+ export type Declaration = CognetEventMap["cognet:schedule:declare"]
5
+
6
+ /** A session as it is found on disk. */
7
+ export type Found = {
8
+ id: string
9
+ /** The log file. */
10
+ file: string
11
+ /** When the log was last written, epoch ms. */
12
+ modifiedAt: number
13
+ }
14
+
15
+ /** Bytes a session holds, by where they are kept. */
16
+ export type Sizes = { log: number; telemetry: number; sensory: number; media: number; total: number }
17
+
18
+ /** Something that went wrong, wherever it was recorded. */
19
+ export type Fault = {
20
+ at: number
21
+ seq: number
22
+ type: string
23
+ tick?: number
24
+ system?: string
25
+ code?: string
26
+ message?: string
27
+ }
28
+
29
+ /**
30
+ * How long something took, over many runs. `hist` counts runs by duration,
31
+ * one bucket per entry of `BOUNDS` — enough to give a percentile without
32
+ * keeping every run.
33
+ */
34
+ export type Tally = { count: number; totalMs: number; maxMs: number; hist: number[] }
35
+
36
+ export type SystemTally = Tally & { failed: number; async: boolean; threads: number[] }
37
+
38
+ /** One opening or closing of a trouble: a component named `trouble`, set when it begins and removed when it ends. */
39
+ export type Trouble = { at: number; tick: number; entity: string; opened: boolean; what?: string; detail?: string }
40
+
41
+ /** What one telemetry segment holds, summed. A segment that has rolled closed never changes, so neither does this. */
42
+ export type Segment = {
43
+ bytes: number
44
+ events: number
45
+ firstMs: number
46
+ lastMs: number
47
+ firstTick: number
48
+ lastTick: number
49
+ /**
50
+ * Each tick, start to end, wall time: its own systems, the workers it
51
+ * waited for, and any lagged run it had to wait to land. What a tick
52
+ * that runs over the deadline ran over in. (A runtime from before the
53
+ * schedule owned its ticks timed each WAKE instead, merged ones and all.)
54
+ */
55
+ ticks: Tally
56
+ /** Ticks whose wall time was over the mind's own deadline. Nothing for a mind that declares no rate. */
57
+ late: number
58
+ /** By system: the ticks that waited on it — a worker the rest needed, or a lagged run landing late — and for how long. */
59
+ held: Record<string, Tally>
60
+ /**
61
+ * Each tick's time on the main thread: its systems that ran neither
62
+ * beside the tick nor on a worker. This is what a deadline is held to.
63
+ * A tick cut by the end of a segment is counted in both halves.
64
+ */
65
+ main: Tally
66
+ /** Ticks whose main-thread time was over the mind's own deadline. Nothing for a mind that declares no rate. */
67
+ over: number
68
+ systems: Record<string, SystemTally>
69
+ faults: Fault[]
70
+ faultsTotal: number
71
+ troubles: Trouble[]
72
+ }
73
+
74
+ /** One part's readings, one per sample of `Usage.at`; null where the part was absent or the reading unmeasured. */
75
+ export type PartSeries = { /** Shared with other agents — a daemon's models — so not this agent's alone. */ shared: boolean; ram: Array<number | null>; cpu: Array<number | null>; gpu: Array<number | null>; vram: Array<number | null> }
76
+
77
+ /** A group of threads' CPU over the samples: how many threads, and the cores the group kept busy. */
78
+ export type ThreadTally = { threads: number; samples: number; totalCores: number; maxCores: number }
79
+
80
+ /**
81
+ * What the agent's processes used, as sampled every couple of seconds
82
+ * (`axon:usage`). Kept whole: a session is hours at most, and growth over
83
+ * time is only visible as a series.
84
+ */
85
+ export type Usage = {
86
+ /** When each sample was taken, epoch ms. */
87
+ at: number[]
88
+ /** By part: `brain` (the agent's own processes), and whatever supervises it. */
89
+ parts: Record<string, PartSeries>
90
+ /** By thread group: `main`, `worker 0`…, and the runtime's own by name. */
91
+ threads: Record<string, ThreadTally>
92
+ /** Which worker each OS thread id is, from `cognet:thread:start`. */
93
+ workers: Record<string, number>
94
+ /** The whole machine beside the parts: how busy it was at each sample, and which processes — the agent's or not — kept it busy. */
95
+ machine: { cores: number; ramTotal: number; cpu: Array<number | null>; busiest: Record<string, ThreadTally> } | null
96
+ }
97
+
98
+ /** What the index knows of a session — everything the summary commands answer from, without reading the session again. */
99
+ export type Summary = {
100
+ version: number
101
+ id: string
102
+ agentId: string | null
103
+ startedAt: string | null
104
+ log: {
105
+ /** Bytes of the log this covers; the log only grows, so the rest is read from here. */
106
+ covered: number
107
+ events: number
108
+ /** Lines that did not parse. */
109
+ torn: number
110
+ firstMs: number | null
111
+ lastMs: number | null
112
+ /** Events by type. */
113
+ types: Record<string, number>
114
+ /** The first `FAULTS_KEPT` of them; `faultsTotal` is how many there were. */
115
+ faults: Fault[]
116
+ faultsTotal: number
117
+ declared: Declaration | null
118
+ usage: Usage
119
+ inference: Inference
120
+ /** What each stimulus channel the log carries delivered, and when it was first and last heard. */
121
+ channels: Record<string, Channel>
122
+ }
123
+ /** By segment file name. Only the segments still on disk: the ring is a window. */
124
+ segments: Record<string, Segment>
125
+ }
126
+
127
+ /**
128
+ * Calls to the model worker (`kernel:transform`), counted as they are read.
129
+ * `open` is the calls begun and not yet ended where the reading stopped —
130
+ * carried, so the next reading closes them.
131
+ */
132
+ export type Inference = {
133
+ /** By engine role. A call that failed or was interrupted is counted in `failed`, and timed like any other. */
134
+ roles: Record<string, Tally & { failed: number }>
135
+ /** Calls that began with this many others already begun and not ended, by that number; the last is "that many or more". */
136
+ behind: number[]
137
+ open: Record<string, string>
138
+ firstMs: number | null
139
+ lastMs: number | null
140
+ }
141
+
142
+ /** One stimulus channel, as heard: how often, and between when. */
143
+ export type Channel = { count: number; firstMs: number; lastMs: number }
144
+
145
+ /** One event as a command returns it. */
146
+ export type Event = { type: string; time: { ms: number; seq: number }; data?: unknown; [more: string]: unknown }
package/src/index.ts CHANGED
@@ -1,9 +1,15 @@
1
1
  export { Platform, type PlatformT } from "./platform"
2
+ // What `axon debug` asks. Promoted so the CLI names the shape its command takes.
3
+ export type { DebugT } from "./debug"
2
4
  export type { ProjectKind, ProjectT } from "./build/project"
3
5
  // Promoted deliberately: the name of the default brain is a public fact about
4
6
  // the platform, and `arc`'s release preflight now asks the registry whether a
5
7
  // version of it exists for this kernel's ABI. Two consumers, one constant.
6
8
  export { DEFAULT_COGNET } from "./build/blueprint"
9
+ // Session records are the durable conversation read model consumed by the
10
+ // TUI's session shelf. Export the deliberate listing rule with the shape so
11
+ // surfaces do not reach through Platform's runtime internals.
12
+ export { isListableSession, type SessionRecord } from "./build/runtime"
7
13
  // The `@` palette renders these rows, so the shape is part of the platform's
8
14
  // public surface rather than an internal of the walk that produces it.
9
15
  export type { FileEntry, FilesT } from "./services/files"
@@ -15,6 +21,9 @@ export { procTree, appendOutput, type ProcNode } from "./procs"
15
21
  // both render it; the ordering rules are subtle enough that a second
16
22
  // implementation would drift rather than differ.
17
23
  export { forest, childrenOf, flatten, type ForestAgent, type ForestNode, type Indented } from "./procs"
24
+ // Spawnable siblings are part of the packaged runtime contract. The TUI owns
25
+ // additional workers and must resolve them with the same split-artifact rule.
26
+ export { workerPath } from "./utils/packaged"
18
27
  // The supervisor ↔ agent transport. Moves bytes; the verbs it carries are
19
28
  // SupervisorToAgent / AgentToSupervisor in @arcforge/types.
20
29
  export { serve, connect, Channel, type LinkChannels, type SocketPaths, type ChannelT } from "./link"