@phren/cli 0.1.45 → 0.1.47

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 (52) hide show
  1. package/dist/agents/providers/herdr.d.ts +18 -0
  2. package/dist/agents/providers/herdr.js +94 -0
  3. package/dist/agents/providers/spawner.d.ts +13 -0
  4. package/dist/agents/providers/spawner.js +63 -0
  5. package/dist/agents/registry.d.ts +28 -0
  6. package/dist/agents/registry.js +82 -0
  7. package/dist/agents/types.d.ts +51 -0
  8. package/dist/agents/types.js +42 -0
  9. package/dist/cli/namespaces-utils.d.ts +5 -0
  10. package/dist/cli/namespaces-utils.js +12 -12
  11. package/dist/cli/search.js +29 -0
  12. package/dist/cli-registry.d.ts +1 -1
  13. package/dist/cli-registry.js +1 -0
  14. package/dist/content/learning.js +24 -1
  15. package/dist/editor/buffer.d.ts +48 -0
  16. package/dist/editor/buffer.js +312 -0
  17. package/dist/editor/launch.d.ts +41 -0
  18. package/dist/editor/launch.js +92 -0
  19. package/dist/editor/save.d.ts +15 -0
  20. package/dist/editor/save.js +70 -0
  21. package/dist/generated/memory-ui-graph.browser.js +69 -69
  22. package/dist/graph-core/model.js +99 -9
  23. package/dist/memory-ui-graph.runtime.js +69 -69
  24. package/dist/phren-art.d.ts +7 -0
  25. package/dist/phren-art.js +6 -41
  26. package/dist/shared/lookup-tail.d.ts +35 -0
  27. package/dist/shared/lookup-tail.js +100 -0
  28. package/dist/shell/editor-view.d.ts +8 -0
  29. package/dist/shell/editor-view.js +67 -0
  30. package/dist/shell/entry.js +31 -4
  31. package/dist/shell/graph/agents.d.ts +48 -0
  32. package/dist/shell/graph/agents.js +152 -0
  33. package/dist/shell/graph/controller.d.ts +40 -2
  34. package/dist/shell/graph/controller.js +149 -12
  35. package/dist/shell/graph/graph-view.d.ts +7 -0
  36. package/dist/shell/graph/graph-view.js +227 -50
  37. package/dist/shell/graph/layout.d.ts +21 -2
  38. package/dist/shell/graph/layout.js +79 -11
  39. package/dist/shell/graph/watch.d.ts +71 -0
  40. package/dist/shell/graph/watch.js +153 -0
  41. package/dist/shell/input.d.ts +24 -0
  42. package/dist/shell/input.js +76 -7
  43. package/dist/shell/render-api.js +1 -0
  44. package/dist/shell/render.js +12 -2
  45. package/dist/shell/shell.d.ts +25 -1
  46. package/dist/shell/shell.js +134 -5
  47. package/dist/shell/startup.d.ts +3 -0
  48. package/dist/shell/startup.js +8 -0
  49. package/dist/shell/view.d.ts +5 -1
  50. package/dist/shell/view.js +80 -75
  51. package/dist/ui/server.js +6 -56
  52. package/package.json +1 -1
@@ -11,6 +11,13 @@
11
11
  */
12
12
  export declare const PHREN_ART: string[];
13
13
  export declare const PHREN_ART_RIGHT: string[];
14
+ /**
15
+ * The mascot holds still: it sits at a fixed position beside the wordmark and
16
+ * only its eyes and the sparkle above its head change. Whole-body motion (the
17
+ * vertical bob and the sideways lean) shifted the art by a full cell, which
18
+ * reads as blocky jitter at terminal resolution, so it is gone. Every frame has
19
+ * the same line count and the same display width as `PHREN_ART`.
20
+ */
14
21
  export interface PhrenAnimator {
15
22
  getFrame(): string[];
16
23
  start(): void;
package/dist/phren-art.js CHANGED
@@ -83,36 +83,19 @@ function applySparkleToLine(line, frame, active) {
83
83
  }
84
84
  return line.replace(/(\x1b\[38;2;\d+;2\d\d;2\d\dm)[\u2580\u2584](\x1b\[0m)/g, `$1${sparkleChar}$2`);
85
85
  }
86
- function applyLean(line, offset) {
87
- if (offset === 0)
88
- return line;
89
- if (offset > 0) {
90
- return " ".repeat(offset) + line;
91
- }
92
- const trimCount = Math.min(-offset, line.match(/^( *)/)[1].length);
93
- return line.slice(trimCount);
94
- }
95
86
  export function createPhrenAnimator(options) {
96
87
  const facing = options?.facing ?? "left";
97
88
  const baseArt = facing === "right" ? PHREN_ART_RIGHT : PHREN_ART;
98
89
  const state = {
99
- bobUp: false,
100
90
  isBlinking: false,
101
91
  sparkleFrame: 0,
102
92
  sparkleActive: false,
103
- leanOffset: 0,
104
93
  };
105
94
  const timers = [];
106
95
  function scheduleTimer(fn, ms) {
107
96
  const t = setTimeout(fn, ms);
108
97
  timers.push(t);
109
98
  }
110
- function scheduleBob() {
111
- scheduleTimer(() => {
112
- state.bobUp = !state.bobUp;
113
- scheduleBob();
114
- }, 500);
115
- }
116
99
  function scheduleBlink() {
117
100
  const interval = randInt(2000, 8000);
118
101
  scheduleTimer(() => {
@@ -153,41 +136,23 @@ export function createPhrenAnimator(options) {
153
136
  sparkleStep(step + 1);
154
137
  }, 200);
155
138
  }
156
- function scheduleLean() {
157
- const interval = randInt(4000, 10000);
158
- scheduleTimer(() => {
159
- const direction = Math.random() < 0.5 ? -1 : 1;
160
- state.leanOffset = direction;
161
- const holdTime = randInt(1000, 2000);
162
- scheduleTimer(() => {
163
- state.leanOffset = 0;
164
- scheduleLean();
165
- }, holdTime);
166
- }, interval);
167
- }
168
139
  return {
169
140
  getFrame() {
170
- let lines = baseArt.map((line, i) => {
171
- let result = line;
141
+ // In-place substitutions only: the art grid is never shifted or padded,
142
+ // so the frame keeps its line count and its width.
143
+ return baseArt.map((line, i) => {
172
144
  if (state.isBlinking && i === EYE_ROW) {
173
- result = applyBlinkToLine(result);
145
+ return applyBlinkToLine(line);
174
146
  }
175
147
  if (i === SPARKLE_ROW) {
176
- result = applySparkleToLine(result, state.sparkleFrame, state.sparkleActive);
148
+ return applySparkleToLine(line, state.sparkleFrame, state.sparkleActive);
177
149
  }
178
- result = applyLean(result, state.leanOffset);
179
- return result;
150
+ return line;
180
151
  });
181
- if (state.bobUp) {
182
- lines = ["", ...lines.slice(0, -1)];
183
- }
184
- return lines;
185
152
  },
186
153
  start() {
187
- scheduleBob();
188
154
  scheduleBlink();
189
155
  scheduleSparkle();
190
- scheduleLean();
191
156
  },
192
157
  stop() {
193
158
  for (const t of timers) {
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Tail the live lookup-events log.
3
+ *
4
+ * `.runtime/lookup-events.jsonl` is append-only: every memory phren lands on
5
+ * during a search, and every memory a hook injects, is written as one JSON
6
+ * line. Two hosts follow it live — the web UI's Activity stream and the
7
+ * shell's graph watch mode — so the read-only tailing logic lives here once.
8
+ *
9
+ * Reads only the bytes appended since the last poll, which is far more robust
10
+ * across platforms than fs.watch, and survives the file being rotated or
11
+ * truncated underneath it.
12
+ */
13
+ import type { LookupEvent } from "../governance/activity.js";
14
+ export interface LookupTailOptions {
15
+ /**
16
+ * Start at the current end of the file so only events appended after
17
+ * construction are delivered. Callers wanting history use
18
+ * `readRecentLookups` for the backfill. Default true.
19
+ */
20
+ fromEnd?: boolean;
21
+ }
22
+ export declare class LookupTail {
23
+ private readonly logPath;
24
+ private offset;
25
+ private carry;
26
+ constructor(logPath: string, opts?: LookupTailOptions);
27
+ /**
28
+ * Raw JSON lines appended since the last poll, each already validated as
29
+ * parseable. Never throws: a logging or read failure yields nothing rather
30
+ * than breaking the caller's render or stream.
31
+ */
32
+ pollLines(): string[];
33
+ /** Parsed events appended since the last poll. */
34
+ poll(): LookupEvent[];
35
+ }
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Tail the live lookup-events log.
3
+ *
4
+ * `.runtime/lookup-events.jsonl` is append-only: every memory phren lands on
5
+ * during a search, and every memory a hook injects, is written as one JSON
6
+ * line. Two hosts follow it live — the web UI's Activity stream and the
7
+ * shell's graph watch mode — so the read-only tailing logic lives here once.
8
+ *
9
+ * Reads only the bytes appended since the last poll, which is far more robust
10
+ * across platforms than fs.watch, and survives the file being rotated or
11
+ * truncated underneath it.
12
+ */
13
+ import * as fs from "fs";
14
+ export class LookupTail {
15
+ logPath;
16
+ offset = 0;
17
+ carry = "";
18
+ constructor(logPath, opts = {}) {
19
+ this.logPath = logPath;
20
+ if (opts.fromEnd !== false) {
21
+ try {
22
+ this.offset = fs.existsSync(logPath) ? fs.statSync(logPath).size : 0;
23
+ }
24
+ catch {
25
+ this.offset = 0;
26
+ }
27
+ }
28
+ }
29
+ /**
30
+ * Raw JSON lines appended since the last poll, each already validated as
31
+ * parseable. Never throws: a logging or read failure yields nothing rather
32
+ * than breaking the caller's render or stream.
33
+ */
34
+ pollLines() {
35
+ let size;
36
+ try {
37
+ if (!fs.existsSync(this.logPath))
38
+ return [];
39
+ size = fs.statSync(this.logPath).size;
40
+ }
41
+ catch {
42
+ return [];
43
+ }
44
+ if (size < this.offset) {
45
+ // Rotated or truncated: start over rather than read garbage.
46
+ this.offset = 0;
47
+ this.carry = "";
48
+ }
49
+ if (size <= this.offset)
50
+ return [];
51
+ let chunk = "";
52
+ try {
53
+ const fd = fs.openSync(this.logPath, "r");
54
+ try {
55
+ const buf = Buffer.alloc(size - this.offset);
56
+ fs.readSync(fd, buf, 0, buf.length, this.offset);
57
+ chunk = buf.toString("utf8");
58
+ }
59
+ finally {
60
+ fs.closeSync(fd);
61
+ }
62
+ }
63
+ catch {
64
+ return [];
65
+ }
66
+ this.offset = size;
67
+ const lines = (this.carry + chunk).split("\n");
68
+ // A trailing partial line is kept until the writer finishes it.
69
+ this.carry = lines.pop() ?? "";
70
+ const out = [];
71
+ for (const line of lines) {
72
+ const trimmed = line.trim();
73
+ if (!trimmed)
74
+ continue;
75
+ try {
76
+ JSON.parse(trimmed);
77
+ out.push(trimmed);
78
+ }
79
+ catch {
80
+ // Skip malformed lines rather than failing the whole poll.
81
+ }
82
+ }
83
+ return out;
84
+ }
85
+ /** Parsed events appended since the last poll. */
86
+ poll() {
87
+ const out = [];
88
+ for (const line of this.pollLines()) {
89
+ try {
90
+ const parsed = JSON.parse(line);
91
+ if (parsed && typeof parsed.at === "string")
92
+ out.push(parsed);
93
+ }
94
+ catch {
95
+ // Already validated in pollLines; defensive only.
96
+ }
97
+ }
98
+ return out;
99
+ }
100
+ }
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Drawing for the shell's modal editor.
3
+ *
4
+ * The frame is painted whole on every key, so there is no real terminal cursor
5
+ * to move: the character under the cursor is drawn inverted instead.
6
+ */
7
+ import type { EditorState } from "../editor/buffer.js";
8
+ export declare function renderEditor(state: EditorState, width: number, height: number): string[];
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Drawing for the shell's modal editor.
3
+ *
4
+ * The frame is painted whole on every key, so there is no real terminal cursor
5
+ * to move: the character under the cursor is drawn inverted instead.
6
+ */
7
+ import { displayWidth, lineViewport, padToWidth, style, truncateLine } from "./render.js";
8
+ const GUTTER = 5;
9
+ function modeBadge(state) {
10
+ switch (state.mode) {
11
+ case "insert": return style.boldGreen(" INSERT ");
12
+ case "command": return style.boldYellow(" COMMAND ");
13
+ default: return style.boldCyan(" NORMAL ");
14
+ }
15
+ }
16
+ /** The line with the cursor drawn on it, as inverse video. */
17
+ function withCursor(text, col, active) {
18
+ if (!active)
19
+ return text;
20
+ const chars = [...text];
21
+ const at = Math.min(col, chars.length);
22
+ const before = chars.slice(0, at).join("");
23
+ const under = chars[at] ?? " ";
24
+ const after = chars.slice(at + 1).join("");
25
+ return `${before}${style.invert(under)}${after}`;
26
+ }
27
+ export function renderEditor(state, width, height) {
28
+ const out = [];
29
+ const bodyHeight = Math.max(1, height - 2);
30
+ // Header: what is open, which mode, and whether it is unsaved.
31
+ const dirty = state.dirty ? style.boldYellow(" ●") : "";
32
+ const header = ` ${style.bold(state.label)}${dirty} ${modeBadge(state)}`;
33
+ out.push(padToWidth(truncateLine(header, width), width));
34
+ // Body, scrolled to keep the cursor in view.
35
+ const numbered = state.lines.map((text, i) => {
36
+ const active = i === state.cursor.line;
37
+ const gutter = active
38
+ ? style.boldCyan(String(i + 1).padStart(GUTTER - 1) + " ")
39
+ : style.dim(String(i + 1).padStart(GUTTER - 1) + " ");
40
+ const shown = withCursor(text, state.cursor.col, active && state.mode !== "command");
41
+ return `${gutter}${shown}`;
42
+ });
43
+ const vp = lineViewport(numbered, state.cursor.line, state.cursor.line, bodyHeight, 0);
44
+ for (const line of vp.lines)
45
+ out.push(padToWidth(truncateLine(line, width), width));
46
+ while (out.length < height - 1)
47
+ out.push(padToWidth("", width));
48
+ // Status: the command being typed wins, then a message, then position.
49
+ const position = `${state.cursor.line + 1},${state.cursor.col + 1}`;
50
+ let status;
51
+ if (state.mode === "command") {
52
+ status = ` ${style.boldCyan(state.command)}${style.cyan("█")}`;
53
+ }
54
+ else if (state.message) {
55
+ status = ` ${style.yellow(state.message)}`;
56
+ }
57
+ else {
58
+ const hint = state.mode === "insert"
59
+ ? style.dim("esc normal mode")
60
+ : style.dim(":w write · :q quit · i insert · / search");
61
+ status = ` ${hint}`;
62
+ }
63
+ const right = style.dim(position);
64
+ const pad = Math.max(1, width - displayWidth(status) - displayWidth(right) - 2);
65
+ out.push(padToWidth(truncateLine(`${status}${" ".repeat(pad)}${right}`, width), width));
66
+ return out.slice(0, height);
67
+ }
@@ -107,10 +107,16 @@ export async function startShell(phrenPath, profile, startup = {}) {
107
107
  await new Promise((resolve) => { rl.on("close", () => { shell.close(); resolve(); }); });
108
108
  return;
109
109
  }
110
- process.stdin.setRawMode(true);
111
- process.stdin.resume();
112
- process.stdin.setEncoding("utf8");
113
- enterFullscreen();
110
+ // Taking and releasing the terminal is written once and used twice: at
111
+ // startup and shutdown, and again either side of handing the terminal to an
112
+ // editor. Two copies of this would drift.
113
+ const grabTerminal = () => {
114
+ process.stdin.setRawMode(true);
115
+ process.stdin.resume();
116
+ process.stdin.setEncoding("utf8");
117
+ enterFullscreen();
118
+ };
119
+ grabTerminal();
114
120
  let exiting = false;
115
121
  let cleanedUp = false;
116
122
  // ── Painting ────────────────────────────────────────────────────────────
@@ -268,6 +274,27 @@ export async function startShell(phrenPath, profile, startup = {}) {
268
274
  process.once("SIGINT", onSignal);
269
275
  process.once("SIGTERM", onSignal);
270
276
  process.once("exit", onProcessExit);
277
+ // Hand the terminal to a child process (an editor) and take it back. The
278
+ // shell owns raw mode, the alternate screen and the stdin listener, so all
279
+ // three have to be unwound or the child and the key pump fight over input.
280
+ shell.setSuspendHandler(async (run) => {
281
+ if (exiting)
282
+ return;
283
+ process.stdin.removeListener("data", onData);
284
+ restoreTerminal();
285
+ try {
286
+ await run();
287
+ }
288
+ finally {
289
+ if (!exiting) {
290
+ grabTerminal();
291
+ process.stdin.on("data", onData);
292
+ // Anything typed at the child after it exited is not for us.
293
+ decoder.flush();
294
+ await repaint();
295
+ }
296
+ }
297
+ });
271
298
  try {
272
299
  await playStartupIntro(phrenPath, resolveStartupIntroPlan(phrenPath), waitForIntroKeypress);
273
300
  introKeyWaiter = undefined;
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Live coding agents on the knowledge graph.
3
+ *
4
+ * Watch mode shows what phren's memory is doing; this shows who is doing it.
5
+ * Agents are transient runtime state rather than memory, so they decorate the
6
+ * project nodes they are working in instead of becoming graph nodes of their
7
+ * own — the same shape `GraphWatch` uses, and it keeps `graph-core` (which is
8
+ * bundled for the browser) untouched.
9
+ */
10
+ import type { JoinedAgent } from "../../agents/types.js";
11
+ export interface GraphAgentsOptions {
12
+ pollMs?: number;
13
+ /** Injected in tests so nothing shells out and no timer runs. */
14
+ collect?: () => JoinedAgent[];
15
+ runFocus?: (argv: string[]) => boolean;
16
+ enabled?: boolean;
17
+ }
18
+ /** Run a provider-supplied focus command. Never throws. */
19
+ export declare function runFocusCommand(argv: string[]): boolean;
20
+ export declare class GraphAgents {
21
+ readonly phrenPath: string;
22
+ readonly profile: string;
23
+ agents: JoinedAgent[];
24
+ /** Index into `agents`; -1 when nothing is highlighted. */
25
+ highlighted: number;
26
+ enabled: boolean;
27
+ private timer;
28
+ private onUpdate;
29
+ private readonly pollMs;
30
+ private readonly collectFn;
31
+ private readonly runFocus;
32
+ constructor(phrenPath: string, profile: string, opts?: GraphAgentsOptions);
33
+ get running(): boolean;
34
+ private polledOnce;
35
+ start(onUpdate: () => void): void;
36
+ stop(): void;
37
+ toggle(): boolean;
38
+ /** Refresh the list. Never throws; a failing provider just yields nothing. */
39
+ poll(): JoinedAgent[];
40
+ /** Agents grouped by the project they are working in. */
41
+ byProject(): Map<string, JoinedAgent[]>;
42
+ get current(): JoinedAgent | null;
43
+ /** Move the highlight; wraps, and starts from the first agent. */
44
+ cycle(delta: number): JoinedAgent | null;
45
+ clearHighlight(): void;
46
+ /** Bring the highlighted agent to the front in whatever is hosting it. */
47
+ focusCurrent(): JoinedAgent | null;
48
+ }
@@ -0,0 +1,152 @@
1
+ /**
2
+ * Live coding agents on the knowledge graph.
3
+ *
4
+ * Watch mode shows what phren's memory is doing; this shows who is doing it.
5
+ * Agents are transient runtime state rather than memory, so they decorate the
6
+ * project nodes they are working in instead of becoming graph nodes of their
7
+ * own — the same shape `GraphWatch` uses, and it keeps `graph-core` (which is
8
+ * bundled for the browser) untouched.
9
+ */
10
+ import { execFileSync } from "child_process";
11
+ import { commandExists } from "../../hooks.js";
12
+ import { detectProject } from "../../shared/index.js";
13
+ import { debugLog } from "../../shared.js";
14
+ import { errorMessage } from "../../utils.js";
15
+ import { agentsEnabled, collectAgents, joinAgents, sortAgents } from "../../agents/registry.js";
16
+ import { createHerdrProvider } from "../../agents/providers/herdr.js";
17
+ import { createSpawnerProvider } from "../../agents/providers/spawner.js";
18
+ const DEFAULT_POLL_MS = 2000;
19
+ const FOCUS_TIMEOUT_MS = 5000;
20
+ /** Run a provider-supplied focus command. Never throws. */
21
+ export function runFocusCommand(argv) {
22
+ if (!argv.length)
23
+ return false;
24
+ const [command, ...args] = argv;
25
+ try {
26
+ execFileSync(command, args, { stdio: ["ignore", "ignore", "ignore"], timeout: FOCUS_TIMEOUT_MS });
27
+ return true;
28
+ }
29
+ catch (err) {
30
+ debugLog(`agent focus: ${errorMessage(err)}`);
31
+ return false;
32
+ }
33
+ }
34
+ export class GraphAgents {
35
+ phrenPath;
36
+ profile;
37
+ agents = [];
38
+ /** Index into `agents`; -1 when nothing is highlighted. */
39
+ highlighted = -1;
40
+ enabled;
41
+ timer = null;
42
+ onUpdate = null;
43
+ pollMs;
44
+ collectFn;
45
+ runFocus;
46
+ constructor(phrenPath, profile, opts = {}) {
47
+ this.phrenPath = phrenPath;
48
+ this.profile = profile;
49
+ this.pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
50
+ this.runFocus = opts.runFocus ?? runFocusCommand;
51
+ this.enabled = opts.enabled ?? agentsEnabled();
52
+ this.collectFn = opts.collect ?? (() => {
53
+ const providers = [createHerdrProvider(commandExists), createSpawnerProvider(phrenPath)];
54
+ return joinAgents(collectAgents(providers), (cwd) => detectProject(phrenPath, cwd, profile));
55
+ });
56
+ }
57
+ get running() {
58
+ return this.timer !== null || this.polledOnce;
59
+ }
60
+ polledOnce = false;
61
+ start(onUpdate) {
62
+ if (!this.enabled || this.timer)
63
+ return;
64
+ this.onUpdate = onUpdate;
65
+ this.poll();
66
+ this.timer = setInterval(() => {
67
+ const before = signature(this.agents);
68
+ this.poll();
69
+ if (signature(this.agents) !== before)
70
+ this.onUpdate?.();
71
+ }, this.pollMs);
72
+ this.timer.unref?.();
73
+ }
74
+ stop() {
75
+ if (this.timer) {
76
+ clearInterval(this.timer);
77
+ this.timer = null;
78
+ }
79
+ this.onUpdate = null;
80
+ this.polledOnce = false;
81
+ this.agents = [];
82
+ this.highlighted = -1;
83
+ }
84
+ toggle() {
85
+ this.enabled = !this.enabled;
86
+ if (!this.enabled) {
87
+ this.stop();
88
+ this.enabled = false;
89
+ }
90
+ return this.enabled;
91
+ }
92
+ /** Refresh the list. Never throws; a failing provider just yields nothing. */
93
+ poll() {
94
+ let next = [];
95
+ try {
96
+ next = sortAgents(this.collectFn());
97
+ }
98
+ catch (err) {
99
+ debugLog(`graph agents poll: ${errorMessage(err)}`);
100
+ next = [];
101
+ }
102
+ const previousId = this.highlighted >= 0 ? this.agents[this.highlighted]?.id : undefined;
103
+ this.agents = next;
104
+ this.polledOnce = true;
105
+ // Keep the highlight on the same agent across a refresh where possible.
106
+ this.highlighted = previousId ? next.findIndex((a) => a.id === previousId) : -1;
107
+ return next;
108
+ }
109
+ /** Agents grouped by the project they are working in. */
110
+ byProject() {
111
+ const map = new Map();
112
+ for (const agent of this.agents) {
113
+ if (!agent.project)
114
+ continue;
115
+ const list = map.get(agent.project);
116
+ if (list)
117
+ list.push(agent);
118
+ else
119
+ map.set(agent.project, [agent]);
120
+ }
121
+ return map;
122
+ }
123
+ get current() {
124
+ return this.highlighted >= 0 ? this.agents[this.highlighted] ?? null : null;
125
+ }
126
+ /** Move the highlight; wraps, and starts from the first agent. */
127
+ cycle(delta) {
128
+ if (!this.agents.length) {
129
+ this.highlighted = -1;
130
+ return null;
131
+ }
132
+ const next = this.highlighted < 0
133
+ ? (delta >= 0 ? 0 : this.agents.length - 1)
134
+ : (this.highlighted + delta + this.agents.length) % this.agents.length;
135
+ this.highlighted = next;
136
+ return this.agents[next] ?? null;
137
+ }
138
+ clearHighlight() {
139
+ this.highlighted = -1;
140
+ }
141
+ /** Bring the highlighted agent to the front in whatever is hosting it. */
142
+ focusCurrent() {
143
+ const agent = this.current;
144
+ if (!agent?.focus?.length)
145
+ return null;
146
+ return this.runFocus(agent.focus) ? agent : null;
147
+ }
148
+ }
149
+ /** Cheap change detector, so a poll that found nothing new costs no repaint. */
150
+ function signature(agents) {
151
+ return agents.map((a) => `${a.id}:${a.status}:${a.focused ? 1 : 0}:${a.project ?? ""}`).join("|");
152
+ }
@@ -10,6 +10,8 @@
10
10
  import type { GraphFilters, GraphModel, VisibleData } from "../../graph-core/model.js";
11
11
  import type { GraphPayload, NodeDetail, NodeKind, RuntimeNode } from "../../graph-core/types.js";
12
12
  import { type Point } from "./layout.js";
13
+ import { GraphWatch } from "./watch.js";
14
+ import { GraphAgents } from "./agents.js";
13
15
  /** Nodes drawn at once. Terminals have far fewer pixels than a browser tab. */
14
16
  export declare const TUI_NODE_LIMIT = 350;
15
17
  export type GraphStatus = "idle" | "loading" | "ready" | "empty" | "error";
@@ -23,8 +25,14 @@ export interface Camera {
23
25
  /** World coordinates at the centre of the viewport. */
24
26
  cx: number;
25
27
  cy: number;
26
- /** Braille dots per world unit. */
27
- scale: number;
28
+ /**
29
+ * Braille dots per world unit, per axis. A terminal canvas is much wider
30
+ * than it is tall, so fitting a roughly round graph to the shorter axis
31
+ * would waste most of the width. The two scales are allowed to diverge up
32
+ * to MAX_STRETCH, which fills the screen while keeping the shape readable.
33
+ */
34
+ scaleX: number;
35
+ scaleY: number;
28
36
  }
29
37
  export interface SearchState {
30
38
  query: string;
@@ -45,6 +53,12 @@ export interface GraphControllerOptions {
45
53
  tokenOf?: (phrenPath: string) => string;
46
54
  /** Animation frame period; the tests shrink it. */
47
55
  frameMs?: number;
56
+ /** Injected watch, so tests can feed events without a log file or timers. */
57
+ watch?: GraphWatch;
58
+ /** Injected agents poller, so tests never shell out. */
59
+ agents?: GraphAgents;
60
+ /** Start with watch mode off (`--no-live`). */
61
+ watchEnabled?: boolean;
48
62
  }
49
63
  declare const DIRECTIONS: Record<string, Point>;
50
64
  export declare class GraphController {
@@ -79,7 +93,31 @@ export declare class GraphController {
79
93
  private readonly builder;
80
94
  private readonly tokenOf;
81
95
  private readonly frameMs;
96
+ /** Live tail of what phren is landing on, in this or any other terminal. */
97
+ readonly watch: GraphWatch;
98
+ /** Coding agents running on this machine, joined onto their projects. */
99
+ readonly agents: GraphAgents;
100
+ watchEnabled: boolean;
101
+ /**
102
+ * Wall-clock ms of the last navigation keypress. While the user is driving,
103
+ * incoming events still pulse and feed but do not steal the camera.
104
+ */
105
+ private lastUserInputAt;
82
106
  constructor(phrenPath: string, profile: string, opts?: GraphControllerOptions);
107
+ /** Idempotent; called every render so the tail starts with the view. */
108
+ startWatch(): void;
109
+ stopWatch(): void;
110
+ /** Idempotent; the poller only runs while the Graph view is open. */
111
+ startAgents(): void;
112
+ toggleAgents(): boolean;
113
+ toggleWatch(): boolean;
114
+ /** True while the user is actively driving, so the camera is left alone. */
115
+ private get userDriving();
116
+ /**
117
+ * New events landed. Light every node they touch, then follow the newest
118
+ * one that is actually on screen — unless the user is mid-navigation.
119
+ */
120
+ private onWatchEvents;
83
121
  /**
84
122
  * Let the shell trigger a repaint on its own (settle animation, fly-to,
85
123
  * a build finishing). Without it the controller blocks the first render on