@arcforge/platform 2.0.218 → 2.0.244
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 +27 -19
- package/src/build/blueprint/blueprint.ts +48 -64
- package/src/build/blueprint/cognet/abi.ts +3 -257
- package/src/build/blueprint/cognet/bundle-worker.ts +11 -0
- package/src/build/blueprint/cognet/bundle.ts +294 -89
- package/src/build/blueprint/cognet/cognet.ts +8 -7
- package/src/build/blueprint/cognet/config/config.ts +52 -0
- package/src/build/blueprint/cognet/config/index.ts +4 -0
- package/src/build/blueprint/cognet/config/literal.ts +83 -0
- package/src/build/blueprint/cognet/config/provider.ts +43 -0
- package/src/build/blueprint/cognet/config/shape.ts +183 -0
- package/src/build/blueprint/cognet/index.ts +4 -2
- package/src/build/blueprint/cognet/native/cargo.ts +31 -0
- package/src/build/blueprint/cognet/native/crate.ts +126 -0
- package/src/build/blueprint/cognet/native/index.ts +2 -0
- package/src/build/blueprint/cognet/native/library.ts +125 -0
- package/src/build/blueprint/cognet/native/manifest.ts +137 -0
- package/src/build/blueprint/cognet/python/index.ts +1 -0
- package/src/build/blueprint/cognet/python/project.ts +119 -0
- package/src/build/blueprint/cognet/schema/arrays.ts +23 -0
- package/src/build/blueprint/cognet/schema/authored.ts +273 -0
- package/src/build/blueprint/cognet/schema/compile.ts +78 -0
- package/src/build/blueprint/cognet/schema/components/external.ts +15 -0
- package/src/build/blueprint/cognet/schema/components/index.ts +3 -0
- package/src/build/blueprint/cognet/schema/components/lock.ts +58 -0
- package/src/build/blueprint/cognet/schema/components/model.ts +34 -0
- package/src/build/blueprint/cognet/schema/components/python.ts +15 -0
- package/src/build/blueprint/cognet/schema/components/python_source.py +69 -0
- package/src/build/blueprint/cognet/schema/components/rust.ts +33 -0
- package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.lock +117 -0
- package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.toml +11 -0
- package/src/build/blueprint/cognet/schema/components/rust_source/src/main.rs +104 -0
- package/src/build/blueprint/cognet/schema/components/source.ts +220 -0
- package/src/build/blueprint/cognet/schema/components/tags.ts +66 -0
- package/src/build/blueprint/cognet/schema/components/typescript.ts +157 -0
- package/src/build/blueprint/cognet/schema/index.ts +5 -0
- package/src/build/blueprint/cognet/schema/interfaces/index.ts +3 -0
- package/src/build/blueprint/cognet/schema/interfaces/source.ts +218 -0
- package/src/build/blueprint/cognet/schema/python.ts +260 -0
- package/src/build/blueprint/cognet/schema/rust.ts +316 -0
- package/src/build/blueprint/cognet/schema/schema.ts +248 -0
- package/src/build/blueprint/cognet/schema/typescript.ts +352 -0
- package/src/build/blueprint/index.ts +1 -1
- package/src/build/blueprint/modules/index.ts +7 -5
- package/src/build/blueprint/modules/meta.ts +47 -3
- package/src/build/blueprint/scan/config.ts +22 -16
- package/src/build/blueprint/scan/provider-globals.ts +46 -0
- package/src/build/blueprint/scan/providers.ts +25 -0
- package/src/build/blueprint/scan/tools.ts +21 -15
- package/src/build/extensions/edit.ts +66 -2
- package/src/build/extensions/extensions.ts +16 -3
- package/src/build/extensions/index.ts +1 -1
- package/src/build/project/bundle/agent.ts +26 -17
- package/src/build/project/bundle/source.ts +2 -2
- package/src/build/project/create/cognet.ts +84 -33
- package/src/build/project/create/profile.ts +13 -3
- package/src/build/project/index.ts +1 -1
- package/src/build/project/installer.ts +6 -5
- package/src/build/project/kinds.ts +4 -0
- package/src/build/project/manifest/env.ts +10 -0
- package/src/build/project/models/blobs/blobs.ts +57 -0
- package/src/build/project/models/blobs/index.ts +1 -0
- package/src/build/project/models/fetch.ts +46 -51
- package/src/build/project/models/index.ts +2 -1
- package/src/build/project/models/models.ts +12 -38
- package/src/build/project/models/onnx.ts +82 -0
- package/src/build/project/models/specifier.ts +9 -3
- package/src/build/project/models/storage/index-store.ts +27 -0
- package/src/build/project/models/storage/index.ts +1 -0
- package/src/build/project/models/store.ts +21 -16
- package/src/build/project/prepare.ts +82 -27
- package/src/build/project/project.ts +8 -14
- package/src/build/project/projects.ts +12 -1
- package/src/build/project/tree.ts +13 -3
- package/src/build/project/treecache.ts +8 -4
- package/src/build/project/typegen/axon-dts.ts +18 -0
- package/src/build/project/typegen/cognet-dts.ts +248 -59
- package/src/build/project/typegen/prompt-dts.ts +2 -3
- package/src/build/project/typegen/registry-dts.ts +2 -2
- package/src/build/project/typegen/tsconfig.ts +13 -13
- package/src/build/project/typegen/tui-dts.ts +3 -4
- package/src/build/project/typegen/workspace-scripts.ts +8 -7
- package/src/build/project/typegen/write.ts +15 -2
- package/src/build/project/watcher.ts +27 -0
- package/src/build/runtime/agent.ts +102 -63
- package/src/build/runtime/conformance.ts +25 -0
- package/src/build/runtime/escalations.ts +3 -8
- package/src/build/runtime/index.ts +2 -0
- package/src/build/runtime/instances.ts +7 -4
- package/src/build/runtime/progress.ts +6 -2
- package/src/build/runtime/reload-watch.ts +11 -8
- package/src/debug/README.md +398 -0
- package/src/debug/debug.ts +101 -0
- package/src/debug/events.ts +156 -0
- package/src/debug/graph.ts +94 -0
- package/src/debug/index.ts +5 -0
- package/src/debug/indexer.ts +286 -0
- package/src/debug/inference.ts +53 -0
- package/src/debug/log.ts +68 -0
- package/src/debug/overview.ts +78 -0
- package/src/debug/perf.ts +75 -0
- package/src/debug/resources.ts +125 -0
- package/src/debug/ring.ts +31 -0
- package/src/debug/sessions.ts +90 -0
- package/src/debug/signs.ts +119 -0
- package/src/debug/tally.ts +44 -0
- package/src/debug/types.ts +146 -0
- package/src/index.ts +9 -0
- package/src/link/agent-main.ts +36 -10
- package/src/link/index.ts +1 -1
- package/src/link/services.ts +88 -57
- package/src/platform.ts +17 -25
- package/src/services/cloud.ts +1 -4
- package/src/services/control/client.ts +1 -1
- package/src/services/control/server.ts +1 -1
- package/src/services/index.ts +1 -0
- package/src/services/ollama/daemon.ts +23 -0
- package/src/services/ollama/http.ts +7 -1
- package/src/services/ollama/ollama.ts +8 -14
- package/src/services/probe/ask.ts +139 -0
- package/src/services/probe/index.ts +3 -0
- package/src/services/providers.ts +18 -0
- package/src/services/resources/hardware.ts +15 -18
- package/src/services/resources/resources.ts +4 -5
- package/src/services/store/types.ts +3 -0
- package/src/services/running/index.ts +0 -1
- 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"
|