@point-seven-studio/jq-agents 0.1.0 → 0.1.1
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/dist/jq-agents.mjs +1 -1
- package/dist/types/agent-history.d.ts +61 -0
- package/dist/types/agent-status.d.ts +148 -0
- package/dist/types/cli.d.ts +15 -0
- package/dist/types/collect.d.ts +30 -0
- package/dist/types/host-metrics.d.ts +140 -0
- package/dist/types/host-sampler.d.ts +43 -0
- package/dist/types/index.d.ts +6 -0
- package/dist/types/main.d.ts +1 -0
- package/dist/types/page.d.ts +23 -0
- package/package.json +8 -3
package/dist/jq-agents.mjs
CHANGED
|
@@ -692,7 +692,7 @@ async function run2(argv) {
|
|
|
692
692
|
}
|
|
693
693
|
|
|
694
694
|
// src/main.ts
|
|
695
|
-
var VERSION = true ? "0.1.
|
|
695
|
+
var VERSION = true ? "0.1.1" : "dev";
|
|
696
696
|
var HELP = `JQ Agents ${VERSION}: what every Claude Code session on this machine is doing.
|
|
697
697
|
|
|
698
698
|
jq-agents open a board at http://127.0.0.1:${DEFAULT_PORT}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* JQ Agents: turning a log of attention changes into "how long were sessions
|
|
3
|
+
* blocked on a person".
|
|
4
|
+
*
|
|
5
|
+
* A snapshot answers "what is happening now". This answers the question that
|
|
6
|
+
* decides whether a board is worth keeping: how much time do sessions spend
|
|
7
|
+
* waiting on a human, and which repo is worst? That cannot be reconstructed from
|
|
8
|
+
* current-state rows, so a host that wants it must keep the events itself (for
|
|
9
|
+
* example from `jq-agents --watch --exec`). This package stores nothing.
|
|
10
|
+
*
|
|
11
|
+
* Pure — the caller supplies the events and the clock, so it's golden-tested.
|
|
12
|
+
*/
|
|
13
|
+
export interface AttentionEvent {
|
|
14
|
+
session_id: string;
|
|
15
|
+
product: string;
|
|
16
|
+
to_attention: string;
|
|
17
|
+
occurred_at: string;
|
|
18
|
+
}
|
|
19
|
+
export interface BlockedEpisode {
|
|
20
|
+
session_id: string;
|
|
21
|
+
product: string;
|
|
22
|
+
startedAt: string;
|
|
23
|
+
/** null while the session is STILL blocked — an open episode. */
|
|
24
|
+
endedAt: string | null;
|
|
25
|
+
minutes: number;
|
|
26
|
+
open: boolean;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Pair each `needs-you` transition with the next transition away from it.
|
|
30
|
+
*
|
|
31
|
+
* Two decisions worth stating, because both change the numbers:
|
|
32
|
+
*
|
|
33
|
+
* 1. An episode with no closing event is **open**, not dropped. Dropping it
|
|
34
|
+
* would under-report exactly the case that matters most — a session
|
|
35
|
+
* blocked right now, which is the one you'd want the board to shout about.
|
|
36
|
+
* Its `minutes` is measured to `now`.
|
|
37
|
+
* 2. A repeated `needs-you` for an already-open session does NOT start a
|
|
38
|
+
* second episode. Attention tiers can re-fire (live → idle while still
|
|
39
|
+
* waiting is a state change but not a new block), and counting those as
|
|
40
|
+
* fresh episodes would inflate the count while shrinking every duration.
|
|
41
|
+
*/
|
|
42
|
+
export declare function computeBlockedEpisodes(events: AttentionEvent[], now: number): BlockedEpisode[];
|
|
43
|
+
export interface HistorySummary {
|
|
44
|
+
episodes: number;
|
|
45
|
+
openEpisodes: number;
|
|
46
|
+
/** Median rather than mean: one forgotten overnight session would drag a mean
|
|
47
|
+
* to uselessness, and the typical wait is the actionable number. */
|
|
48
|
+
medianMinutes: number;
|
|
49
|
+
longestMinutes: number;
|
|
50
|
+
longestProduct: string | null;
|
|
51
|
+
/** Cumulative session-blocked time. NOT wall-clock — sessions overlap, so
|
|
52
|
+
* this can exceed the window and legitimately does. Labelled accordingly in
|
|
53
|
+
* the UI, because "6.2h blocked in a 10h day" invites the wrong reading. */
|
|
54
|
+
totalBlockedHours: number;
|
|
55
|
+
byProduct: Array<{
|
|
56
|
+
product: string;
|
|
57
|
+
episodes: number;
|
|
58
|
+
totalMinutes: number;
|
|
59
|
+
}>;
|
|
60
|
+
}
|
|
61
|
+
export declare function summarizeHistory(episodes: BlockedEpisode[]): HistorySummary;
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* JQ Agents: the rules that turn the tail of a session transcript into one status row.
|
|
3
|
+
*
|
|
4
|
+
* Everything here is PURE (no fs, no network, no clock beyond an injected
|
|
5
|
+
* `now`), so it can be golden-tested. The I/O half is collect.ts.
|
|
6
|
+
*
|
|
7
|
+
* Read-only by design: nothing in this module or its callers ever writes back
|
|
8
|
+
* into a running session.
|
|
9
|
+
*/
|
|
10
|
+
/** One JSONL record from ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl. */
|
|
11
|
+
export interface TranscriptRecord {
|
|
12
|
+
type?: string;
|
|
13
|
+
timestamp?: string;
|
|
14
|
+
sessionId?: string;
|
|
15
|
+
cwd?: string;
|
|
16
|
+
gitBranch?: string;
|
|
17
|
+
message?: {
|
|
18
|
+
role?: string;
|
|
19
|
+
stop_reason?: string | null;
|
|
20
|
+
content?: unknown;
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
export interface AgentStatusRow {
|
|
24
|
+
machine: string;
|
|
25
|
+
product: string;
|
|
26
|
+
working_tree: string;
|
|
27
|
+
branch: string | null;
|
|
28
|
+
session_id: string;
|
|
29
|
+
pid: number | null;
|
|
30
|
+
state: 'live' | 'idle' | 'stale' | 'dead';
|
|
31
|
+
last_activity_at: string | null;
|
|
32
|
+
waiting: boolean;
|
|
33
|
+
stop_reason: string | null;
|
|
34
|
+
ends_with_question: boolean;
|
|
35
|
+
blocked_question: string | null;
|
|
36
|
+
question_redacted: boolean;
|
|
37
|
+
question_allowed: boolean;
|
|
38
|
+
cpu_pct?: number | null;
|
|
39
|
+
rss_mb?: number | null;
|
|
40
|
+
net_rx_bps?: number | null;
|
|
41
|
+
net_tx_bps?: number | null;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Record types that are METADATA, not conversation turns. Measured on
|
|
45
|
+
* 2026-08-18: reading the last *record* rather than the last *substantive* one
|
|
46
|
+
* misses 25 of 235 transcripts outright AND reads the wrong timestamp for idle
|
|
47
|
+
* time. Re-derive with:
|
|
48
|
+
* find ~/.claude/projects -name '*.jsonl' | while read -r f; do tail -1 "$f" \
|
|
49
|
+
* | python3 -c "import sys,json;print(json.load(sys.stdin).get('type'))"; done \
|
|
50
|
+
* | sort | uniq -c | sort -rn
|
|
51
|
+
*/
|
|
52
|
+
export declare const META_RECORD_TYPES: Set<string>;
|
|
53
|
+
/**
|
|
54
|
+
* Idle thresholds, in seconds, for the live → idle → stale ladder.
|
|
55
|
+
*
|
|
56
|
+
* LIVE was 5 minutes and read wrong in practice: a session records nothing to
|
|
57
|
+
* its transcript while a long tool call runs, so an actively-working session
|
|
58
|
+
* showed `idle` and the board reported "0 live" with the operator watching it
|
|
59
|
+
* work. 15 minutes matches how transcripts are actually written.
|
|
60
|
+
*/
|
|
61
|
+
export declare const LIVE_WITHIN_S: number;
|
|
62
|
+
export declare const IDLE_WITHIN_S: number;
|
|
63
|
+
/** Max characters of question text ever copied off the machine. */
|
|
64
|
+
export declare const QUESTION_MAX_CHARS = 400;
|
|
65
|
+
/** Scrub secret-shaped substrings. Returns the text and whether anything was hit. */
|
|
66
|
+
export declare function redactSecrets(text: string): {
|
|
67
|
+
text: string;
|
|
68
|
+
redacted: boolean;
|
|
69
|
+
};
|
|
70
|
+
/** Flatten a record's message content to plain text (content may be blocks). */
|
|
71
|
+
export declare function messageText(rec: TranscriptRecord): string;
|
|
72
|
+
/**
|
|
73
|
+
* Does this turn end by asking for something? Separates "wants a decision now"
|
|
74
|
+
* from "idle but not blocking" — a completion summary closing with "let me know
|
|
75
|
+
* if…" is lower-attention than "A or B?".
|
|
76
|
+
*/
|
|
77
|
+
export declare function endsWithQuestion(text: string): boolean;
|
|
78
|
+
/** The last record that is an actual conversation turn, skipping metadata types. */
|
|
79
|
+
export declare function lastSubstantive(records: TranscriptRecord[]): TranscriptRecord | null;
|
|
80
|
+
/** The last assistant turn — the only text the relay ever considers copying. */
|
|
81
|
+
export declare function lastAssistant(records: TranscriptRecord[]): TranscriptRecord | null;
|
|
82
|
+
/** Newest non-metadata timestamp — idle time must not read a meta record's clock. */
|
|
83
|
+
export declare function lastActivityAt(records: TranscriptRecord[]): string | null;
|
|
84
|
+
/**
|
|
85
|
+
* live/idle/stale/dead from process liveness + how long since real activity.
|
|
86
|
+
* A dead session isn't waiting, it's gone — the first conjunct of the
|
|
87
|
+
* waiting-vs-stopped test.
|
|
88
|
+
*/
|
|
89
|
+
export declare function deriveState(alive: boolean, lastActivityIso: string | null, now: number): AgentStatusRow['state'];
|
|
90
|
+
/**
|
|
91
|
+
* Is this session waiting on a human?
|
|
92
|
+
*
|
|
93
|
+
* alive ∧ stop_reason === 'end_turn' ∧ (ends in a question) ∧ recent
|
|
94
|
+
*
|
|
95
|
+
* Each conjunct kills a distinct false positive. Note the equality test:
|
|
96
|
+
* measured 2026-08-18, stop_reason is present on 114/114 last-substantive
|
|
97
|
+
* assistant records with values end_turn 95 / null 18 / tool_use 1. The 18
|
|
98
|
+
* nulls are interrupted turns — STOPPED, not waiting — so `!== 'tool_use'`
|
|
99
|
+
* and `=== 'end_turn'` differ on exactly the rows that matter.
|
|
100
|
+
*
|
|
101
|
+
* That measured set (end_turn / null / tool_use) turned out to be INCOMPLETE:
|
|
102
|
+
* a live dry run against real transcripts also produced `stop_sequence`. It is
|
|
103
|
+
* excluded here deliberately — the equality test errs toward *not* claiming a
|
|
104
|
+
* session wants you, and a board that under-reports is recoverable while one
|
|
105
|
+
* that nags gets ignored. Re-derive the current value set before widening it:
|
|
106
|
+
* find ~/.claude/projects -name '*.jsonl' | while read -r f; do tail -1 "$f" \
|
|
107
|
+
* | python3 -c "import sys,json;d=json.load(sys.stdin);print((d.get('message') or {}).get('stop_reason'))"; \
|
|
108
|
+
* done | sort | uniq -c | sort -rn
|
|
109
|
+
*/
|
|
110
|
+
export declare function deriveWaiting(rec: TranscriptRecord | null, alive: boolean): boolean;
|
|
111
|
+
/**
|
|
112
|
+
* What a waiting session actually deserves from you.
|
|
113
|
+
*
|
|
114
|
+
* `waiting` alone is not actionable, and shipping it as the headline number was
|
|
115
|
+
* a mistake: measured 2026-08-18, 8 of 9 "waiting" rows had last moved between
|
|
116
|
+
* 5 and 32 HOURS earlier. A session abandoned yesterday is not waiting on you in
|
|
117
|
+
* any sense you can act on — it is just stopped, holding an unanswered question.
|
|
118
|
+
* Counting those together makes the number 89% noise, and a number that is
|
|
119
|
+
* mostly noise stops being read at all.
|
|
120
|
+
*
|
|
121
|
+
* needs-you waiting AND still recent enough to matter (live/idle)
|
|
122
|
+
* abandoned waiting but stale — an old unanswered question, not a request
|
|
123
|
+
* none not waiting, or the session is gone
|
|
124
|
+
*/
|
|
125
|
+
export type Attention = 'needs-you' | 'abandoned' | 'none';
|
|
126
|
+
export declare function deriveAttention(state: AgentStatusRow['state'], waiting: boolean): Attention;
|
|
127
|
+
/** Is this working tree allowed to report question text at all? */
|
|
128
|
+
export declare function isTreeAllowed(workingTree: string, allowlist: string[]): boolean;
|
|
129
|
+
/**
|
|
130
|
+
* Build the row for one session. `records` is the transcript TAIL (newest last).
|
|
131
|
+
* Pure — the caller supplies liveness, the allowlist and the clock.
|
|
132
|
+
*/
|
|
133
|
+
export declare function buildStatusRow(opts: {
|
|
134
|
+
machine: string;
|
|
135
|
+
records: TranscriptRecord[];
|
|
136
|
+
sessionIdFallback: string;
|
|
137
|
+
alive: boolean;
|
|
138
|
+
pid: number | null;
|
|
139
|
+
allowlist: string[];
|
|
140
|
+
now: number;
|
|
141
|
+
/**
|
|
142
|
+
* The session's cwd normalized to its git repo root. A session's raw `cwd`
|
|
143
|
+
* follows it into subdirectories (a `cd apps/backend` would name the product
|
|
144
|
+
* "backend" and break the PID↔tree match), so the caller resolves the root
|
|
145
|
+
* and passes it here. Falls back to the raw cwd when not supplied.
|
|
146
|
+
*/
|
|
147
|
+
workingTreeOverride?: string;
|
|
148
|
+
}): AgentStatusRow | null;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
export declare const DEFAULT_PORT = 4319;
|
|
2
|
+
export interface Args {
|
|
3
|
+
json: boolean;
|
|
4
|
+
html: string | null;
|
|
5
|
+
watch: boolean;
|
|
6
|
+
exec: string | null;
|
|
7
|
+
intervalS: number;
|
|
8
|
+
port: number;
|
|
9
|
+
probe: boolean;
|
|
10
|
+
sample: boolean;
|
|
11
|
+
questionTrees: string[];
|
|
12
|
+
maxAgeDays: number;
|
|
13
|
+
}
|
|
14
|
+
export declare function parseArgs(argv: string[], env?: Record<string, string | undefined>): Args;
|
|
15
|
+
export declare function run(argv: string[]): Promise<void>;
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { type AgentStatusRow, type TranscriptRecord } from './agent-status.js';
|
|
2
|
+
import { type Bottleneck, type HostSample } from './host-metrics.js';
|
|
3
|
+
export interface CollectOptions {
|
|
4
|
+
/** Default ~/.claude/projects (or $CLAUDE_CONFIG_DIR/projects). */
|
|
5
|
+
projectsDir?: string;
|
|
6
|
+
/** Default /tmp/cc-socks. */
|
|
7
|
+
sockDir?: string;
|
|
8
|
+
/** Trees allowed to report question text. Default: none. */
|
|
9
|
+
questionTrees?: string[];
|
|
10
|
+
/** Skip transcripts untouched for longer than this. Default 3. */
|
|
11
|
+
maxAgeDays?: number;
|
|
12
|
+
machine?: string;
|
|
13
|
+
now?: number;
|
|
14
|
+
}
|
|
15
|
+
export declare function defaultProjectsDir(): string;
|
|
16
|
+
/** The last `n` complete JSONL records, without loading the file (trap 2). */
|
|
17
|
+
export declare function tailRecords(file: string, n?: number): Promise<TranscriptRecord[]>;
|
|
18
|
+
export declare function collectRows(opts?: CollectOptions): Promise<AgentStatusRow[]>;
|
|
19
|
+
export interface Snapshot {
|
|
20
|
+
machine: string;
|
|
21
|
+
generated_at: string;
|
|
22
|
+
sessions: AgentStatusRow[];
|
|
23
|
+
/** null when sampling was skipped or failed. */
|
|
24
|
+
host: HostSample | null;
|
|
25
|
+
bottleneck: Bottleneck | null;
|
|
26
|
+
}
|
|
27
|
+
export declare function snapshot(opts?: CollectOptions & {
|
|
28
|
+
sample?: boolean;
|
|
29
|
+
probe?: boolean;
|
|
30
|
+
}): Promise<Snapshot>;
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* JQ Agents — the deterministic core of host + per-session resource sampling.
|
|
3
|
+
*
|
|
4
|
+
* Same split as agent-status.ts: everything exported here is PURE (parsers and
|
|
5
|
+
* one judgment function), so it can be golden-tested against captured command
|
|
6
|
+
* output. The IO half — actually shelling out to ps/nettop/vm_stat/iostat —
|
|
7
|
+
* lives in host-sampler.ts.
|
|
8
|
+
*
|
|
9
|
+
* WHY THIS EXISTS. The board answers "what is each session doing". It could not
|
|
10
|
+
* answer "why is that one slow", which is the question you have when one
|
|
11
|
+
* machine crawls and another doesn't. Answering it needs numbers per session,
|
|
12
|
+
* not vibes per machine.
|
|
13
|
+
*
|
|
14
|
+
* THE HONEST DEFAULT IS "NOTHING". For an LLM session the wall clock is
|
|
15
|
+
* dominated by waiting on the API, and local resources are usually idle. A
|
|
16
|
+
* bottleneck attributor that always names a culprit is worse than useless — it
|
|
17
|
+
* teaches people to ignore it. `deriveBottleneck` returns 'none' unless a
|
|
18
|
+
* threshold is actually crossed, and every non-'none' verdict carries the
|
|
19
|
+
* measurement that triggered it so a reader can check the claim.
|
|
20
|
+
*/
|
|
21
|
+
/** Per-process resource sample, keyed by pid. */
|
|
22
|
+
export interface ProcSample {
|
|
23
|
+
cpuPct: number;
|
|
24
|
+
rssMb: number;
|
|
25
|
+
}
|
|
26
|
+
/** Per-process cumulative network counters, keyed by pid. */
|
|
27
|
+
export interface NetSample {
|
|
28
|
+
bytesIn: number;
|
|
29
|
+
bytesOut: number;
|
|
30
|
+
}
|
|
31
|
+
export interface HostSample {
|
|
32
|
+
cpuCount: number;
|
|
33
|
+
load1: number;
|
|
34
|
+
memUsedPct: number;
|
|
35
|
+
swapUsedMb: number;
|
|
36
|
+
diskReadMbs: number | null;
|
|
37
|
+
diskWriteMbs: number | null;
|
|
38
|
+
/** TLS connect time to the API endpoint, ms — see host-sampler for why not ping. */
|
|
39
|
+
rttMs: number | null;
|
|
40
|
+
jitterMs: number | null;
|
|
41
|
+
}
|
|
42
|
+
export type BottleneckKind = 'none' | 'cpu' | 'memory' | 'disk' | 'network' | 'unknown';
|
|
43
|
+
export interface Bottleneck {
|
|
44
|
+
kind: BottleneckKind;
|
|
45
|
+
/** The measurement behind the verdict, so a reader can check rather than trust. */
|
|
46
|
+
reason: string | null;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* `ps -o pid=,pcpu=,rss=` — " 1206 1.7 123520". RSS is KB.
|
|
50
|
+
*
|
|
51
|
+
* Note pcpu is an average over the process's LIFETIME, not an instantaneous
|
|
52
|
+
* reading; a session that pinned a core an hour ago still reports high. It is
|
|
53
|
+
* kept because it is nearly free, but it is deliberately NOT used to declare a
|
|
54
|
+
* CPU bottleneck — load average is, because that is a current measure.
|
|
55
|
+
*/
|
|
56
|
+
export declare function parsePs(stdout: string): Map<number, ProcSample>;
|
|
57
|
+
/**
|
|
58
|
+
* `nettop -P -x -l 1` rows look like:
|
|
59
|
+
* 16:00:06.765990 mDNSResponder.253 1012880014 47672137 0 0 0
|
|
60
|
+
* i.e. time, name.pid, bytes_in, bytes_out, rx_dupe, rx_ooo, re-tx.
|
|
61
|
+
*
|
|
62
|
+
* The re-tx column is deliberately ignored. Measured on this machine it tracks
|
|
63
|
+
* bytes_out at roughly 1:1, which cannot mean "bytes retransmitted", and a
|
|
64
|
+
* number whose units are unconfirmed has no business driving a warning.
|
|
65
|
+
*
|
|
66
|
+
* Counters are cumulative since process start, so a rate needs two samples —
|
|
67
|
+
* see `rateBps`.
|
|
68
|
+
*/
|
|
69
|
+
export declare function parseNettop(stdout: string): Map<number, NetSample>;
|
|
70
|
+
/**
|
|
71
|
+
* Bytes/second between two cumulative readings.
|
|
72
|
+
*
|
|
73
|
+
* Returns null rather than 0 when the counter went BACKWARDS: that means the
|
|
74
|
+
* pid was recycled onto a different process between ticks, and reporting the
|
|
75
|
+
* difference as a rate would invent traffic that never happened.
|
|
76
|
+
*/
|
|
77
|
+
export declare function rateBps(prev: number | null | undefined, cur: number, seconds: number): number | null;
|
|
78
|
+
/**
|
|
79
|
+
* `vm_stat`. Page size comes from its own header rather than being assumed —
|
|
80
|
+
* Apple Silicon uses 16384, Intel 4096, and hardcoding either silently
|
|
81
|
+
* quadruples or quarters every number on the other platform.
|
|
82
|
+
*
|
|
83
|
+
* "Used" counts wired + active + compressed. Inactive is deliberately excluded:
|
|
84
|
+
* macOS reclaims it on demand, so counting it makes a healthy machine look
|
|
85
|
+
* permanently full — the single most common way this metric is reported wrong.
|
|
86
|
+
*/
|
|
87
|
+
export declare function parseVmStat(stdout: string, memTotalBytes: number): number;
|
|
88
|
+
/** `sysctl -n vm.loadavg` → "{ 2.48 3.00 5.29 }". */
|
|
89
|
+
export declare function parseLoadAvg(stdout: string): number;
|
|
90
|
+
/** `sysctl -n vm.swapusage` → "total = 4096.00M used = 1234.50M free = ...". */
|
|
91
|
+
export declare function parseSwapUsedMb(stdout: string): number;
|
|
92
|
+
/**
|
|
93
|
+
* `iostat -d -w 1 -c 2` prints a since-boot row then a live one. Only the LAST
|
|
94
|
+
* row is a current rate; using the first reports the machine's lifetime average
|
|
95
|
+
* and never moves.
|
|
96
|
+
*/
|
|
97
|
+
export declare function parseIostat(stdout: string): {
|
|
98
|
+
readMbs: number;
|
|
99
|
+
writeMbs: number;
|
|
100
|
+
} | null;
|
|
101
|
+
/** Thresholds, named so the dashboard and the tests agree on one source. */
|
|
102
|
+
export declare const THRESHOLDS: {
|
|
103
|
+
/** load per core above which the machine is genuinely contended */
|
|
104
|
+
readonly loadPerCore: 1.5;
|
|
105
|
+
/** % of RAM in wired+active+compressed */
|
|
106
|
+
readonly memUsedPct: 90;
|
|
107
|
+
/**
|
|
108
|
+
* Swap in use, MB. Paired with memUsedPct because on its own it is a WEAK
|
|
109
|
+
* signal, and this machine proves it: measured 23.9 GB of swap used on 16 GB
|
|
110
|
+
* of RAM while memory sat at 67% and the machine was responsive. macOS
|
|
111
|
+
* swapusage is close to cumulative — it reflects what has been paged out at
|
|
112
|
+
* some point, not what is being paged now — so a high figure alone says
|
|
113
|
+
* little about current pressure.
|
|
114
|
+
*
|
|
115
|
+
* The RIGHT current-pressure signal is the swapin/swapout RATE, which needs
|
|
116
|
+
* two vm_stat samples the way byte counters need two nettop samples. Until
|
|
117
|
+
* that exists, this stays conservative and deliberately under-reports: a
|
|
118
|
+
* false 'memory-bound' on a healthy machine would teach people to ignore the
|
|
119
|
+
* chip, which is the failure this whole feature is trying to avoid.
|
|
120
|
+
*/
|
|
121
|
+
readonly swapUsedMb: 1024;
|
|
122
|
+
/** TLS connect jitter, ms — variance hurts an agentic loop more than latency */
|
|
123
|
+
readonly jitterMs: 60;
|
|
124
|
+
/** TLS connect time, ms */
|
|
125
|
+
readonly rttMs: 400;
|
|
126
|
+
};
|
|
127
|
+
/**
|
|
128
|
+
* Which resource, if any, is actually holding this session back.
|
|
129
|
+
*
|
|
130
|
+
* Ordered by how directly the reader can act on it, and gated so that a quiet
|
|
131
|
+
* machine reports 'none'. Memory first: swapping degrades everything else and
|
|
132
|
+
* misreads as CPU. Then CPU, then network. Disk deliberately never votes — see
|
|
133
|
+
* THRESHOLDS for the real sample that removed it.
|
|
134
|
+
*
|
|
135
|
+
* Network is judged from HOST-level link quality, not from the session's byte
|
|
136
|
+
* counters. A session moving few bytes on a bad link is still network-bound —
|
|
137
|
+
* it is waiting on round trips, not throughput — so byte volume is reported
|
|
138
|
+
* for context but never used to declare the verdict.
|
|
139
|
+
*/
|
|
140
|
+
export declare function deriveBottleneck(host: HostSample): Bottleneck;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { type HostSample, type ProcSample, type NetSample } from './host-metrics.js';
|
|
2
|
+
/**
|
|
3
|
+
* TLS connect time to the API, sampled three times.
|
|
4
|
+
*
|
|
5
|
+
* NOT ping, and this is the whole reason the function exists. Measured
|
|
6
|
+
* 2026-08-19: `ping api.anthropic.com` reports ~50% packet loss because the
|
|
7
|
+
* edge deprioritises ICMP, and `ping <default gateway>` reported 100% loss
|
|
8
|
+
* because that router drops ICMP outright. Either would have driven a
|
|
9
|
+
* permanent, confident, wrong "network is the bottleneck" verdict. A TLS
|
|
10
|
+
* handshake uses the same path, port and protocol the session does, and cannot
|
|
11
|
+
* be filtered away like that.
|
|
12
|
+
*
|
|
13
|
+
* Jitter is the spread across the samples — variance costs an agentic turn more
|
|
14
|
+
* than latency does, because one turn is dozens of sequential round trips.
|
|
15
|
+
*/
|
|
16
|
+
export declare function probeLatency(): Promise<{
|
|
17
|
+
rttMs: number | null;
|
|
18
|
+
jitterMs: number | null;
|
|
19
|
+
}>;
|
|
20
|
+
/**
|
|
21
|
+
* `probe` is off unless asked for: it is the one outbound connection this package
|
|
22
|
+
* can make (a TLS handshake to the API host, timed; nothing is sent). Without it
|
|
23
|
+
* the network columns are null and the verdict cannot name the network.
|
|
24
|
+
*/
|
|
25
|
+
export declare function sampleHost(probe?: boolean): Promise<HostSample>;
|
|
26
|
+
/**
|
|
27
|
+
* Per-process CPU/RSS and cumulative byte counters for the given pids.
|
|
28
|
+
*
|
|
29
|
+
* nettop is called ONCE for the whole process table rather than once per pid:
|
|
30
|
+
* each invocation costs about a second, so per-pid calls would make the sweep
|
|
31
|
+
* scale with fleet size — the relay would spend a minute sampling a fleet of
|
|
32
|
+
* sixty.
|
|
33
|
+
*
|
|
34
|
+
* Expect gaps. `nettop -l 1` is an instantaneous snapshot listing only sockets
|
|
35
|
+
* live in that instant — measured here, it returned 36 rows and included three
|
|
36
|
+
* claude processes while omitting two others that were plainly running. A pid
|
|
37
|
+
* absent from the snapshot yields no sample and therefore a NULL rate, which is
|
|
38
|
+
* the honest reading: "not measured this tick", not "moved no bytes".
|
|
39
|
+
*/
|
|
40
|
+
export declare function sampleProcs(pids: number[]): Promise<{
|
|
41
|
+
procs: Map<number, ProcSample>;
|
|
42
|
+
net: Map<number, NetSample>;
|
|
43
|
+
}>;
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/** The rules and the collector, for building your own board or storing snapshots. */
|
|
2
|
+
export * from './agent-status.js';
|
|
3
|
+
export * from './agent-history.js';
|
|
4
|
+
export * from './host-metrics.js';
|
|
5
|
+
export { collectRows, snapshot, tailRecords, defaultProjectsDir, type CollectOptions, type Snapshot } from './collect.js';
|
|
6
|
+
export { renderPage, totals, groupByTree, type Totals } from './page.js';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The local board: every session on this machine, grouped by working tree.
|
|
3
|
+
* One HTML string, no script, no outside request. Question text comes from a
|
|
4
|
+
* session's own output, so every value is escaped.
|
|
5
|
+
*/
|
|
6
|
+
import { type AgentStatusRow } from './agent-status.js';
|
|
7
|
+
import type { Snapshot } from './collect.js';
|
|
8
|
+
export declare function ago(iso: string | null, now: number): string;
|
|
9
|
+
export interface Totals {
|
|
10
|
+
sessions: number;
|
|
11
|
+
live: number;
|
|
12
|
+
needs_you: number;
|
|
13
|
+
abandoned: number;
|
|
14
|
+
trees: number;
|
|
15
|
+
}
|
|
16
|
+
export declare function totals(rows: AgentStatusRow[]): Totals;
|
|
17
|
+
/** Trees with a session that needs a person first, then the most recently active. */
|
|
18
|
+
export declare function groupByTree(rows: AgentStatusRow[]): {
|
|
19
|
+
tree: string;
|
|
20
|
+
product: string;
|
|
21
|
+
rows: AgentStatusRow[];
|
|
22
|
+
}[];
|
|
23
|
+
export declare function renderPage(snap: Snapshot, now?: number): string;
|
package/package.json
CHANGED
|
@@ -1,17 +1,21 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@point-seven-studio/jq-agents",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "A local, read-only board of every Claude Code session on your machine: what each is doing and which are waiting on a person. Unofficial; not affiliated with or endorsed by Anthropic.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"jq-agents": "dist/jq-agents.mjs"
|
|
7
7
|
},
|
|
8
8
|
"type": "module",
|
|
9
9
|
"exports": {
|
|
10
|
-
".":
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/types/index.d.ts",
|
|
12
|
+
"default": "./dist/index.mjs"
|
|
13
|
+
}
|
|
11
14
|
},
|
|
12
15
|
"files": [
|
|
13
16
|
"dist/jq-agents.mjs",
|
|
14
17
|
"dist/index.mjs",
|
|
18
|
+
"dist/types",
|
|
15
19
|
"README.md",
|
|
16
20
|
"LICENSE",
|
|
17
21
|
"NOTICE"
|
|
@@ -52,5 +56,6 @@
|
|
|
52
56
|
"homepage": "https://github.com/point-seven-studio/jq-tools/tree/main/packages/agents#readme",
|
|
53
57
|
"bugs": {
|
|
54
58
|
"url": "https://github.com/point-seven-studio/jq-tools/issues"
|
|
55
|
-
}
|
|
59
|
+
},
|
|
60
|
+
"types": "./dist/types/index.d.ts"
|
|
56
61
|
}
|