repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

refactor(llmiterate): simplify marker pipeline

6c5afa016bce166ccdcd51be4fb21cb11020f217

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

- replace legacy raw markers with comment-only llmiterate markers
- split core into parser/config/state/path modules
- respect ignore files and cap directory watchers
- add worker env guard, log command, and retryable run state

Changed files (30)

pi/agent/extensions/llmiterate/README.md

Modified
1 +<!-- !llmiterate -->
1 3 # llmiterate
3 -File-save prompt markers for pi.
5 +Editor-save bridge from comments to background Pi edits.
5 7 ## Marker syntax
7 -A prompt line starts with a configured marker as the first word after whitespace.
8 -Default markers: `LLM`, `PROMPT`.
9 +One marker only:
11 +```text
12 +llmiterate:
13 +```
15 +Marker must appear after a known comment prefix. Raw markers never run.
10 17 ```java
11 18 void main(final String[] a) {
12 - LLM some prompt text
13 - if (a.length == 0)
14 - LLM deal with this
15 - LLM open ui
16 - LLM and then fix perf
18 -```
20 -Parsing result:
22 -- `LLM some prompt text` → one agent request
23 -- `LLM deal with this` → one agent request
24 -- consecutive `LLM open ui` + `LLM and then fix perf` → one multi-line agent request
26 -Comment markers are not special. Configure them explicitly if wanted:
28 -```json
30 - "llmiterate": {
31 - "markers": ["LLM", "//LLM", "/// LLM", "* LLM"]
19 + // llmiterate: implement argument validation
20 + if (a.length == 0) {
21 + // llmiterate: print usage and exit non-zero
36 -```rust
37 -fn fancy_algorithm() {
38 - //LLM implement knapsack algorithm
26 +```py
27 +def parse(src):
28 + # llmiterate: implement parser fast path
29 +```
31 +```sql
32 +-- llmiterate: add index for lookup query
42 35 Rules:
44 -- marker must be first word/token on line, modulo leading whitespace
45 -- no automatic comment-prefix stripping for matching
46 -- use configured markers like `//LLM`, `* LLM`, `/// LLM` for comments
47 -- consecutive lines with the same marker are grouped
48 -- no `:` and no `{{ }}` syntax
37 +- raw `llmiterate:` is ignored
38 +- legacy `LLM` / `PROMPT` is ignored
39 +- consecutive marker lines are grouped
49 40 - empty marker lines are ignored
50 -- fenced code blocks in Markdown are ignored
41 +- `!llmiterate` disables the whole file
43 +```md
44 +<!-- !llmiterate -->
45 +```
47 +## Comment prefixes
49 +Built in prefixes cover common languages:
51 +```text
52 +// /// //! # ## ### -- --- ; ;; ;;; % %% * *> ' :: REM rem dnl DNL <!-- /* /**
53 +```
55 +Config `commentPrefixes` appends to builtins:
57 +```json
59 + "llmiterate": {
60 + "commentPrefixes": ["COMMENT"]
61 + }
63 +```
52 65 ## Replacement behavior
54 -llmiterate instructs the agent to treat marker lines as inline prompts/TODOs and replace the whole marker span with the requested implementation/change.
67 +On save or `/llmiterate scan`, matching markers are queued. A background Pi RPC worker edits files. Success means the marker span is gone/replaced.
56 -## Rerun policy
69 +llmiterate itself does not mutate source files; only the worker uses normal Pi tools.
58 -Once queued, a marker key is recorded in the platform state dir:
71 +## State / retry policy
60 -| Platform | State path |
61 -|----------|------------|
62 -| Linux/BSD | `${XDG_STATE_HOME:-~/.local/state}/pi/llmiterate/<projectHash>/state.json` |
63 -| macOS | `~/Library/Application Support/pi/llmiterate/<projectHash>/state.json` |
64 -| Windows | `%LOCALAPPDATA%\\pi\\llmiterate\\<projectHash>\\state.json` |
73 +State lives in:
66 75 ```text
67 -file:startLine:hash(promptText)
76 +${XDG_STATE_HOME:-~/.local/state}/pi/llmiterate/<projectHash>/state.json
70 -Same marker will not rerun on later saves. To rerun, edit the prompt text or run:
79 +Statuses:
72 81 ```text
73 -/llmiterate reset
82 +queued | running | done | failed
76 -## Execution model
85 +Duplicate saves do not start duplicate queued/running jobs. Failed markers remain retryable on next save/scan. Markers are only `done` after the worker finishes and the marker no longer exists.
78 -llmiterate always runs marker work in an isolated background Pi RPC worker.
79 -It never injects marker prompts into the current chat session.
87 +## Worker
81 -The worker is launched as:
89 +Worker spawn shape:
83 91 ```bash
84 -pi --mode rpc --no-extensions --session-dir <platform-state-dir>/llmiterate/<projectHash>/sessions
92 +LLMITERATE_WORKER=1 pi \
93 + --mode rpc \
94 + --offline \
95 + --session-dir <state>/llmiterate/<projectHash>/sessions \
96 + --append-system-prompt <llmiterate worker rules> \
97 + --model <optional> \
98 + --thinking <optional>
87 -Each marker job gets a fresh RPC session. Jobs are serialized per project: one background job runs at a time, queued jobs wait.
88 -Each job revalidates the marker span before launch; stale markers are skipped.
90 -## Editor safety
92 -llmiterate never edits files itself. File mutation comes only from the isolated Pi job via normal tools.
94 -## Watch behavior
96 -- handles normal writes, atomic-save rename patterns, moves into watched dirs, and new directories
97 -- refreshes directory watchers after `rename` events
98 -- removes watchers for deleted/moved-away directories
99 -- tracks watcher errors in status
100 -- skips queued requests when their marker span changed before background agent start
101 -- watches only directories that can contain paths configured in `llmiterate.include`
102 -- treats `llmiterate.exclude` as an optional veto after the include whitelist
104 -## Singleton behavior
106 -llmiterate is a singleton per detected project root, not raw shell cwd. The first Pi process creates `<platform-state-dir>/llmiterate/<projectHash>/lock` and owns the watcher. Other Pi processes launched anywhere under the same project root go into standby and only show status.
108 -Project root detection:
110 -1. nearest ancestor containing `.pi/` or `AGENTS.md`
111 -2. else nearest ancestor containing `.git`
112 -3. else current cwd
114 -- duplicate watchers do not queue duplicate agent runs
115 -- singleton roots are canonicalized with `realpath` so symlinked launches share a lock
116 -- stale global per-project locks are recovered when the owning PID is gone
117 -- subprojects are separate when they have their own `.pi/`, `AGENTS.md`, or `.git`
101 +`LLMITERATE_WORKER=1` prevents recursive llmiterate watchers while keeping other extensions available.
119 103 ## Config
121 -All config lives under the `llmiterate` key in Pi `settings.json`.
122 -Global: `~/.pi/agent/settings.json`. Project override: `.pi/settings.json`.
124 -Default `include` is empty, so llmiterate watches nothing until explicitly enabled for paths.
105 +Default `include` is `["**/*"]`. `.gitignore` and `.ignore` files are respected, plus default metadata/build excludes.
126 107 ```json
137 118 "debounceMs": 3000,
138 119 "maxFileBytes": 1000000,
139 - "markers": ["LLM", "PROMPT"]
120 + "timeoutMs": 600000,
121 + "maxWatchDirs": 10000,
122 + "model": "zai/glm-5.1",
123 + "thinking": "high",
124 + "notify": "errors"
129 +`notify`: `off | errors | done | all`. Default: `errors`.
144 131 ## Commands
146 133 ```text
149 136 /llmiterate hide hide panel
150 137 /llmiterate status show panel
151 138 /llmiterate scan scan all matching files now
152 -/llmiterate reset forget processed marker ledger
139 +/llmiterate reset forget run state
153 140 /llmiterate reload reload config + watcher
141 +/llmiterate log open latest worker transcript as markdown in $VISUAL/$EDITOR
144 +## UI channels
146 +- source file: final edits only
147 +- footer status: idle/queued/running/done/failed
148 +- panel: queue/dashboard
149 +- notifications: errors by default
150 +- markdown log: full assistant/tool transcript
156 152 ## Demo
158 154 <!-- demo:workflow_suite:start -->

pi/agent/extensions/llmiterate/__bench__/PERF.md

Modified
2 2 # llmiterate performance notes
4 4 ## Workflow
6 -Profile command:
8 -```bash
9 -bun --cpu-prof --cpu-prof-md --cpu-prof-dir=__bench__/profiles --cpu-prof-name=baseline.cpuprofile.md __bench__/bench.ts
10 -```
12 -Benchmark command:
14 6 ```bash
7 +bun --cpu-prof --cpu-prof-md --cpu-prof-dir=__bench__/profiles --cpu-prof-name=latest.cpuprofile.md __bench__/bench.ts
15 8 bun __bench__/bench.ts
16 -/tmp/go-bin/benchstat __bench__/baseline.txt __bench__/optimized.txt
19 -## Profile findings
21 -Baseline CPU profile hotspots:
23 -- path filtering dominated scans: `shouldIncludePath`, regex excludes, and `toSlash` split/join
24 -- parser spent avoidable time rebuilding marker regexes and checking Markdown extension per line
26 -## Optimizations
28 -- compile path filters once per runtime
29 -- split simple `dir/**` excludes into `Set` root-dir checks / prefix checks before regex fallback
30 -- add `shouldIncludeCompiledPath()` for hot scan paths
31 -- make `toSlash()` allocation-free when path is already slash-normalized
32 -- cache marker regex by normalized marker list
33 -- compute Markdown-file status once per parse
35 -## Benchstat
11 +## Current benchmark
37 13 ```text
38 - │ __bench__/baseline.txt │ __bench__/optimized.txt │
39 - │ sec/op │ sec/op vs base │
40 -ParseNoMarkers 73.71µ ± ∞ ¹ 57.10µ ± ∞ ¹ ~ (p=0.333 n=1+5)
41 -ParseSomeMarkers 82.60µ ± ∞ ¹ 70.85µ ± ∞ ¹ ~ (p=0.333 n=1+5)
42 -ParseMarkdownFences 110.88µ ± ∞ ¹ 80.38µ ± ∞ ¹ ~ (p=0.333 n=1+5)
43 -PathFilterCompiled 3227.5µ ± ∞ ¹ 763.7µ ± ∞ ¹ ~ (p=0.333 n=1+5)
44 -geomean 216.1µ 125.5µ -41.90%
45 -¹ need >= 6 samples for confidence interval at level 0.95
14 +BenchmarkParseNoMarkers 65536000 5 ns/op
15 +BenchmarkParseSomeMarkers 2000 243931 ns/op
16 +BenchmarkParseMarkdownFences 2000 317309 ns/op
17 +BenchmarkPathFilterCompiled 2000 3479021 ns/op
48 -Note: baseline was captured before optimization; optimized has 5 samples. Confidence is limited but direction/magnitude is clear.
20 +Notes:
22 +- no-marker files short-circuit on missing `llmiterate`
23 +- marker parsing is comment-prefix aware and language-agnostic
24 +- path benchmark now uses non-empty include patterns; old empty-default benchmark was invalid
25 +- actual latency is dominated by worker/model/tool execution, not parser CPU

pi/agent/extensions/llmiterate/__bench__/bench.ts

Modified
1 1 import { performance } from "node:perf_hooks";
2 -import { compilePathFilter, defaultConfig, parseMarkerPrompts, shouldIncludeCompiledPath } from "../core";
2 +import { defaultConfig } from "../config";
3 +import { parseMarkerPrompts } from "../parser";
4 +import { compilePathFilter, shouldIncludeCompiledPath } from "../path-filter";
4 6 const ITERATIONS = Number(process.env.ITERATIONS ?? 2000);
5 7 const MIN_TIME_MS = Number(process.env.MIN_TIME_MS ?? 200);
8 10 const sourceSomeMarkers = makeSource(600, 20);
9 11 const markdown = makeMarkdown(900, 30);
10 12 const paths = makePaths(5000);
11 -const filter = compilePathFilter(defaultConfig());
13 +const filter = compilePathFilter({ ...defaultConfig(), include: ["**/*.{ts,tsx,rs,java,md}"] });
13 15 bench("ParseNoMarkers", () => parseMarkerPrompts("src/main.ts", sourceNoMarkers));
14 16 bench("ParseSomeMarkers", () => parseMarkerPrompts("src/main.ts", sourceSomeMarkers));
42 44 function makeSource(lines: number, markerEvery: number): string {
43 45 const out: string[] = [];
44 46 for (let i = 0; i < lines; i++) {
45 - if (markerEvery > 0 && i % markerEvery === 0) out.push(` LLM implement generated case ${i}`);
47 + if (markerEvery > 0 && i % markerEvery === 0) out.push(` // llmiterate: implement generated case ${i}`);
46 48 else out.push(` const value${i} = callThing(${i}, "${i}");`);
48 50 return out.join("\n");
53 55 for (let i = 0; i < lines; i++) {
54 56 if (i % 80 === 0) out.push("```ts");
55 57 if (i % 80 === 40) out.push("```");
56 - if (markerEvery > 0 && i % markerEvery === 0) out.push(`LLM summarize section ${i}`);
58 + if (markerEvery > 0 && i % markerEvery === 0) out.push(`<!-- llmiterate: summarize section ${i} -->`);
57 59 else out.push(`Regular prose line ${i} with enough text to be realistic.`);
59 61 return out.join("\n");

pi/agent/extensions/llmiterate/__bench__/benchstat.txt

Modified
1 - │ __bench__/baseline.txt │ __bench__/optimized.txt │
2 - │ sec/op │ sec/op vs base │
3 -ParseNoMarkers 73.71µ ± ∞ ¹ 57.10µ ± ∞ ¹ ~ (p=0.333 n=1+5)
4 -ParseSomeMarkers 82.60µ ± ∞ ¹ 70.85µ ± ∞ ¹ ~ (p=0.333 n=1+5)
5 -ParseMarkdownFences 110.88µ ± ∞ ¹ 80.38µ ± ∞ ¹ ~ (p=0.333 n=1+5)
6 -PathFilterCompiled 3227.5µ ± ∞ ¹ 763.7µ ± ∞ ¹ ~ (p=0.333 n=1+5)
7 -geomean 216.1µ 125.5µ -41.90%
8 -¹ need >= 6 samples for confidence interval at level 0.95
1 +Current single-run bench:
3 +BenchmarkParseNoMarkers 65536000 5 ns/op
4 +BenchmarkParseSomeMarkers 2000 243931 ns/op
5 +BenchmarkParseMarkdownFences 2000 317309 ns/op
6 +BenchmarkPathFilterCompiled 2000 3479021 ns/op
8 +No benchstat comparison: marker syntax/path workload changed.

pi/agent/extensions/llmiterate/__tests__/__snapshots__/core.test.ts.snap

Modified
11 11 Instructions:
12 12 - Work in/around @a.rs.
13 13 - Marker span to replace: a.rs:1-1.
14 -- Treat the marker line(s) as an inline prompt/TODO, not program code.
14 +- Treat the marker comment line(s) as an inline prompt/TODO, not program code.
15 15 - Replace the whole marker span with the requested implementation or code change.
16 16 - Do not leave the marker line(s) behind unless impossible; explain if impossible."

pi/agent/extensions/llmiterate/__tests__/__snapshots__/ui.test.ts.snap

Modified
2 2 // Bun Snapshot v1, https://bun.sh/docs/test/snapshots
4 4 exports[`llmiterate UI widget empty snapshot 1`] = `
5 5 "╭ llmiterate ──────────────────────────────────────────────╮
6 -│no prompts queued yet │
6 +│no prompts queued yet; /llmiterate log opens latest trans\x1B[0m…\x1B[0m│
7 7 ╰──────────────────────────────────────────────────────────╯"
10 10 exports[`llmiterate UI widget run snapshot 1`] = `
11 11 "╭ llmiterate ──────────────────────────────────────────────────────────────────╮
12 -│● src/main.ts:1 LLM implement foo and bar │
12 +│● src/main.ts:1 llmiterate: implement foo and bar │
13 13 │ running edit │
14 14 │ I am editing the file now and will run tests afterwards. │
15 15 ╰──────────────────────────────────────────────────────────────────────────────╯"

pi/agent/extensions/llmiterate/__tests__/core.test.ts

Modified
3 3 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
4 4 import { tmpdir } from "node:os";
5 5 import { join } from "node:path";
6 6 import { afterEach, describe, expect, test } from "bun:test";
7 7 import {
8 + BUILTIN_COMMENT_PREFIXES,
8 9 buildAgentPrompt,
9 10 compilePathFilter,
10 11 defaultConfig,
11 12 emptyState,
12 13 globToRegExp,
13 - isExcludedPath,
14 14 hashProjectRoot,
15 + isExcludedPath,
16 + isLlmiterateDisabled,
15 17 loadState,
16 18 normalizeConfig,
17 19 parseMarkerPrompts,
18 20 platformStateDir,
19 - projectStoreDir,
20 21 previewText,
22 + projectStoreDir,
21 23 saveState,
22 24 STATE_FILE,
23 25 shouldIncludeCompiledPath,
39 41 describe("llmiterate parser", () => {
40 - test("parses marker as first word on line", () => {
42 + test("parses only comment-transported canonical marker", () => {
41 43 const blocks = parseMarkerPrompts("Main.java", [
42 44 "void main(final String[] a) {",
43 - " LLM some prompt text",
45 + " // llmiterate: some prompt text",
44 46 " if (a.length == 0)",
45 - " LLM deal with this",
47 + " //llmiterate: deal with this",
47 49 ].join("\n"));
49 51 expect(blocks).toHaveLength(2);
50 - expect(blocks[0]).toMatchObject({ marker: "LLM", startLine: 2, endLine: 2, prompt: "some prompt text" });
51 - expect(blocks[1]).toMatchObject({ marker: "LLM", startLine: 4, endLine: 4, prompt: "deal with this" });
52 + expect(blocks[0]).toMatchObject({ marker: "llmiterate:", startLine: 2, endLine: 2, prompt: "some prompt text" });
53 + expect(blocks[1]).toMatchObject({ startLine: 4, prompt: "deal with this" });
54 - test("groups consecutive marker lines with same marker", () => {
55 - const blocks = parseMarkerPrompts("Main.java", [
56 - " LLM open ui",
57 - " LLM and then fix perf",
58 - " run();",
56 + test("rejects raw and legacy markers", () => {
57 + expect(parseMarkerPrompts("a.ts", "llmiterate: raw is invalid")).toHaveLength(0);
58 + expect(parseMarkerPrompts("a.ts", "LLM implement foo\nPROMPT implement bar")).toHaveLength(0);
59 + expect(parseMarkerPrompts("a.ts", "// LLM implement foo")).toHaveLength(0);
60 + });
62 + test("groups consecutive llmiterate comment lines", () => {
63 + const blocks = parseMarkerPrompts("a.ts", [
64 + "// llmiterate: open ui",
65 + "// llmiterate: and then fix perf",
66 + "run();",
59 67 ].join("\n"));
61 69 expect(blocks).toHaveLength(1);
62 70 expect(blocks[0]).toMatchObject({ startLine: 1, endLine: 2, prompt: "open ui\nand then fix perf" });
65 - test("does not group different markers", () => {
66 - const blocks = parseMarkerPrompts("a.ts", "LLM first\nPROMPT second\nLLM third");
67 - expect(blocks.map((b) => b.prompt)).toEqual(["first", "second", "third"]);
68 - expect(blocks.map((b) => b.startLine)).toEqual([1, 2, 3]);
73 + test("supports builtin popular comment prefixes", () => {
74 + const samples = [
75 + "# llmiterate: shell",
76 + "-- llmiterate: sql",
77 + ";;; llmiterate: lisp",
78 + "% llmiterate: tex",
79 + "REM llmiterate: basic",
80 + "' llmiterate: vb",
81 + "<!-- llmiterate: markdown -->",
82 + "/* llmiterate: c */",
83 + "* llmiterate: javadoc",
84 + ];
86 + expect(samples.map((line) => parseMarkerPrompts("x", line)[0]?.prompt)).toEqual([
87 + "shell",
88 + "sql",
89 + "lisp",
90 + "tex",
91 + "basic",
92 + "vb",
93 + "markdown",
94 + "c",
95 + "javadoc",
96 + ]);
71 - test("does not strip comments unless configured marker includes comment", () => {
72 - expect(parseMarkerPrompts("src/lib.rs", " // LLM implement knapsack algo")).toHaveLength(0);
74 - const blocks = parseMarkerPrompts("src/lib.rs", " //LLM implement knapsack algo", ["//LLM"]);
75 - expect(blocks).toHaveLength(1);
76 - expect(blocks[0]).toMatchObject({ marker: "//LLM", prompt: "implement knapsack algo" });
99 + test("appends configured comment prefixes to builtins", () => {
100 + const config = normalizeConfig({ commentPrefixes: ["COMMENT"] });
101 + expect(config.commentPrefixes).toContain("//");
102 + expect(config.commentPrefixes).toContain("COMMENT");
103 + expect(parseMarkerPrompts("a", "COMMENT llmiterate: custom", config.commentPrefixes)[0]?.prompt).toBe("custom");
79 - test("supports markers containing spaces", () => {
80 - const blocks = parseMarkerPrompts("a.rs", " /// LLM add tests", ["/// LLM"]);
81 - expect(blocks).toHaveLength(1);
82 - expect(blocks[0]).toMatchObject({ marker: "/// LLM", prompt: "add tests" });
83 - });
85 - test("sorts overlapping markers longest-first", () => {
86 - const [block] = parseMarkerPrompts("a.rs", "/// LLM add tests", ["LLM", "/// LLM"]);
87 - expect(block).toMatchObject({ marker: "/// LLM", prompt: "add tests" });
88 - });
90 - test("supports PROMPT marker too", () => {
91 - const blocks = parseMarkerPrompts("a.ts", "PROMPT add tests");
92 - expect(blocks).toHaveLength(1);
93 - expect(blocks[0]).toMatchObject({ marker: "PROMPT", prompt: "add tests" });
94 - });
96 - test("marker must be first word", () => {
97 - expect(parseMarkerPrompts("a.md", "some LLM receives message history")).toHaveLength(0);
98 - expect(parseMarkerPrompts("a.ts", "xLLM implement foo")).toHaveLength(0);
99 - expect(parseMarkerPrompts("a.ts", "LLMish implement foo")).toHaveLength(0);
100 - });
102 - test("ignores empty marker lines", () => {
103 - expect(parseMarkerPrompts("a.ts", "LLM\nPROMPT ")).toHaveLength(0);
104 - });
106 - test("ignores enum/string assignment false positives", () => {
107 - expect(parseMarkerPrompts("node.d.ts", 'PROMPT = "PROMPT",')).toHaveLength(0);
108 - });
110 - test("does not parse old colon or brace syntax", () => {
111 - expect(parseMarkerPrompts("a.ts", "// PROMPT: do thing")).toHaveLength(0);
112 - expect(parseMarkerPrompts("a.ts", "// PROMPT{{\n// do thing\n// }}")).toHaveLength(0);
113 - });
115 - test("ignores Markdown fenced code blocks", () => {
116 - const blocks = parseMarkerPrompts("notes.md", [
117 - "# docs",
118 - "```ts",
119 - "LLM fake inside fence",
120 - "```",
121 - "LLM real outside fence",
122 - "~~~",
123 - "PROMPT fake tilde fence",
124 - "~~~",
125 - ].join("\n"));
127 - expect(blocks).toHaveLength(1);
128 - expect(blocks[0]).toMatchObject({ startLine: 5, prompt: "real outside fence" });
106 + test("disable directive ignores whole file", () => {
107 + expect(isLlmiterateDisabled("// !llmiterate\n// llmiterate: ignored")).toBe(true);
108 + expect(parseMarkerPrompts("a.ts", "// !llmiterate\n// llmiterate: ignored")).toEqual([]);
109 + expect(parseMarkerPrompts("a.ts", "prose !llmiterate\n// llmiterate: active")).toHaveLength(1);
131 112 test("normalizes CRLF and CR line endings", () => {
132 - expect(parseMarkerPrompts("a.ts", "LLM one\r\nLLM two")[0]!.prompt).toBe("one\ntwo");
133 - expect(parseMarkerPrompts("a.ts", "LLM one\rLLM two")[0]!.prompt).toBe("one\ntwo");
113 + expect(parseMarkerPrompts("a.ts", "// llmiterate: one\r\n// llmiterate: two")[0]!.prompt).toBe("one\ntwo");
114 + expect(parseMarkerPrompts("a.ts", "// llmiterate: one\r// llmiterate: two")[0]!.prompt).toBe("one\ntwo");
115 + });
117 + test("exact marker boundary", () => {
118 + expect(parseMarkerPrompts("a.ts", "// llmiteratex: nope")).toHaveLength(0);
119 + expect(parseMarkerPrompts("a.ts", "// llmiterate : nope")).toHaveLength(0);
120 + expect(BUILTIN_COMMENT_PREFIXES.length).toBeGreaterThan(10);
137 124 describe("llmiterate config/state/path helpers", () => {
138 - test("defaults to watching nothing", () => {
125 + test("defaults to watching everything except excludes", () => {
139 126 const config = defaultConfig();
140 127 const filter = compilePathFilter(config);
141 - expect(config.include).toEqual([]);
142 - expect(shouldWatchDirectory("", filter)).toBe(false);
143 - expect(shouldIncludeCompiledPath("src/a.ts", filter)).toBe(false);
128 + expect(config.include).toEqual(["**/*"]);
129 + expect(shouldWatchDirectory("", filter)).toBe(true);
130 + expect(shouldIncludeCompiledPath("src/a.ts", filter)).toBe(true);
146 - test("normalizes valid partial config and rejects invalid values", () => {
133 + test("normalizes config", () => {
147 134 const config = normalizeConfig({
148 135 enabled: false,
149 136 include: ["src/**/*.ts"],
150 137 exclude: ["tmp/**"],
151 138 debounceMs: 12.8,
152 139 maxFileBytes: 42,
153 - markers: ["//LLM", "bad\nmarker", " PROMPT "],
140 + timeoutMs: 1000.4,
141 + maxWatchDirs: 77.7,
142 + commentPrefixes: ["COMMENT"],
143 + model: "zai/glm-5.1",
144 + thinking: "high",
145 + notify: "all",
156 148 expect(config).toMatchObject({
157 149 enabled: false,
158 150 include: ["src/**/*.ts"],
159 - exclude: ["tmp/**"],
151 + exclude: expect.arrayContaining(["tmp/**", "**/.jj/**"]),
160 152 debounceMs: 12,
161 153 maxFileBytes: 42,
162 - markers: ["//LLM", "PROMPT"],
163 - });
165 - const fallback = defaultConfig();
166 - expect(normalizeConfig({ include: [""] })).toMatchObject({
167 - include: fallback.include,
154 + timeoutMs: 1000,
155 + maxWatchDirs: 77,
156 + model: "zai/glm-5.1",
157 + thinking: "high",
158 + notify: "all",
160 + expect(config.commentPrefixes).toContain("//");
161 + expect(config.commentPrefixes).toContain("COMMENT");
171 164 test("uses platform state dir for project stores", () => {
188 181 expect(platformStateDir("darwin", {}, "/Users/me")).toBe("/Users/me/Library/Application Support/pi");
189 182 expect(platformStateDir("win32", { LOCALAPPDATA: "C:\\Users\\me\\AppData\\Local" }, "C:\\Users\\me"))
190 183 .toBe("C:\\Users\\me\\AppData\\Local\\pi");
191 - expect(platformStateDir("win32", {}, "C:\\Users\\me"))
192 - .toBe("C:\\Users\\me\\AppData\\Local\\pi");
195 186 test("saves and loads state, invalid state falls back empty", () => {
196 187 const storeDir = tempDir();
197 188 const state = emptyState();
198 - state.processed["a.ts:1:hash"] = {
189 + state.markers["a.ts:1:hash"] = {
199 190 file: "a.ts",
200 191 startLine: 1,
201 192 endLine: 1,
202 193 promptHash: "hash",
203 194 promptPreview: "preview",
195 + status: "done",
196 + attempts: 1,
204 197 queuedAt: 123,
198 + updatedAt: 456,
207 201 saveState(storeDir, state);
208 202 expect(loadState(storeDir)).toEqual(state);
209 203 expect(readFileSync(join(storeDir, STATE_FILE), "utf-8")).toEndWith("\n");
211 - writeFileSync(join(storeDir, STATE_FILE), JSON.stringify({
212 - version: 1,
213 - processed: {
214 - good: state.processed["a.ts:1:hash"],
215 - bad: { file: "missing required fields" },
216 - },
217 - }));
218 - expect(loadState(storeDir).processed).toEqual({ good: state.processed["a.ts:1:hash"] });
219 - rmSync(join(storeDir, STATE_FILE));
205 + writeFileSync(join(storeDir, STATE_FILE), JSON.stringify({ version: 1, markers: { bad: { file: "missing" } } }));
220 206 expect(loadState(storeDir)).toEqual(emptyState());
209 + test("loadState resets queued/running markers to failed", () => {
210 + const storeDir = tempDir();
211 + const state = emptyState();
212 + state.markers.a = {
213 + file: "a.ts", startLine: 1, endLine: 1, promptHash: "h", promptPreview: "p",
214 + status: "running", attempts: 1, queuedAt: 1, updatedAt: 1,
215 + };
216 + saveState(storeDir, state);
217 + expect(loadState(storeDir).markers.a!.status).toBe("failed");
218 + });
223 220 test("glob supports globstar, brace alternatives, and excludes", () => {
224 221 const re = globToRegExp("**/*.{ts,rs}");
225 222 expect(re.test("index.ts")).toBe(true);
233 230 expect(isExcludedPath("packages/pkg/dist/x.ts", filter)).toBe(true);
235 232 const defaults = compilePathFilter(defaultConfig());
236 - expect(shouldIncludeCompiledPath("extensions/devil/node_modules/pkg/index.ts", defaults)).toBe(false);
233 + expect(shouldIncludeCompiledPath(".jj/repo/store.ts", defaults)).toBe(false);
239 236 test("directory watch traversal is include-whitelisted with exclude veto", () => {
247 244 expect(shouldWatchDirectory("src/generated", filter)).toBe(false);
250 - test("globstar include watches all directories unless excluded", () => {
251 - const filter = compilePathFilter({ include: ["**/*.ts"], exclude: ["node_modules/**"] });
252 - expect(shouldWatchDirectory("any/depth", filter)).toBe(true);
253 - expect(shouldWatchDirectory("node_modules", filter)).toBe(false);
254 - });
256 247 test("toSlash and previewText are allocation-aware utility behavior", () => {
257 248 expect(toSlash("a/b/c")).toBe("a/b/c");
258 249 expect(toSlash("a\\b\\c")).toBe("a/b/c");
263 254 describe("llmiterate output snapshots", () => {
264 255 test("agent prompt snapshot", () => {
265 - const [block] = parseMarkerPrompts("a.rs", "LLM implement foo");
256 + const [block] = parseMarkerPrompts("a.rs", "// llmiterate: implement foo");
266 257 expect(buildAgentPrompt(block!)).toMatchSnapshot();

pi/agent/extensions/llmiterate/__tests__/extension.test.ts

Added
new file mode 100644
1 +import { mkdirSync, writeFileSync } from "node:fs";
2 +import { join } from "node:path";
3 +import { afterEach, describe, expect, test } from "bun:test";
4 +import { createLlmiterateExtension } from "../index";
5 +import { loadState, projectStoreDir } from "../core";
6 +import { bootLlmiterate, cleanupHarness, eventually, FakePi, FakeWorker, tempDir, tempProject } from "./harness";
8 +afterEach(cleanupHarness);
10 +describe("llmiterate extension queue/state", () => {
11 + test("uses project-relative paths when Pi cwd is subdir", async () => {
12 + const root = tempProject({ include: ["src/**/*.ts"] });
13 + mkdirSync(join(root, "src"));
14 + writeFileSync(join(root, "src", "a.ts"), "// llmiterate: implement foo\n");
16 + const worker = new FakeWorker(() => {
17 + writeFileSync(join(root, "src", "a.ts"), "export const foo = 1;\n");
18 + });
19 + const pi = bootLlmiterate(join(root, "src"), worker);
21 + await pi.command("llmiterate", "scan");
22 + await eventually(() => worker.prompts.length === 1);
24 + expect(worker.prompts[0]).toContain("@src/a.ts:1");
25 + expect(worker.prompts[0]).not.toContain("@a.ts:1");
26 + await pi.shutdown();
27 + });
29 + test("does not duplicate queued/running marker on repeated scans", async () => {
30 + const root = tempProject({ include: ["src/**/*.ts"] });
31 + mkdirSync(join(root, "src"));
32 + writeFileSync(join(root, "src", "a.ts"), "// llmiterate: implement foo\n");
34 + let release!: () => void;
35 + const blocker = new Promise<void>((resolve) => { release = resolve; });
36 + const worker = new FakeWorker(async () => blocker);
37 + const pi = bootLlmiterate(root, worker);
39 + await pi.command("llmiterate", "scan");
40 + await pi.command("llmiterate", "scan");
41 + await eventually(() => worker.started === 1);
42 + expect(worker.started).toBe(1);
44 + release();
45 + await eventually(() => worker.finished === 1);
46 + await pi.shutdown();
47 + });
49 + test("failed marker remains retryable on next scan", async () => {
50 + const root = tempProject({ include: ["src/**/*.ts"] });
51 + mkdirSync(join(root, "src"));
52 + const file = join(root, "src", "a.ts");
53 + writeFileSync(file, "// llmiterate: implement foo\n");
55 + let attempt = 0;
56 + const worker = new FakeWorker(() => {
57 + attempt++;
58 + if (attempt === 1) throw new Error("provider exploded");
59 + writeFileSync(file, "export const foo = 1;\n");
60 + });
61 + const pi = bootLlmiterate(root, worker);
63 + await pi.command("llmiterate", "scan");
64 + await eventually(() => worker.finished === 1);
65 + expect(Object.values(loadState(projectStoreDir(root)).markers)[0]!.status).toBe("failed");
67 + await pi.command("llmiterate", "scan");
68 + await eventually(() => worker.finished === 2);
69 + const state = loadState(projectStoreDir(root));
70 + expect(Object.values(state.markers).some((m) => m.status === "done" && m.attempts === 2)).toBe(true);
71 + await pi.shutdown();
72 + });
74 + test("scan does not silently drop large queues", async () => {
75 + const root = tempProject({ include: ["src/**/*.ts"] });
76 + mkdirSync(join(root, "src"));
77 + const lines = Array.from({ length: 50 }, (_, i) => `// llmiterate: implement ${i}\nconst marker_${i} = ${i};`).join("\n");
78 + writeFileSync(join(root, "src", "a.ts"), `${lines}\n`);
80 + let release!: () => void;
81 + const blocker = new Promise<void>((resolve) => { release = resolve; });
82 + const worker = new FakeWorker(async () => blocker);
83 + const pi = bootLlmiterate(root, worker);
85 + await pi.command("llmiterate", "scan");
86 + await eventually(() => Object.keys(loadState(projectStoreDir(root)).markers).length === 50);
87 + expect(Object.keys(loadState(projectStoreDir(root)).markers)).toHaveLength(50);
88 + release();
89 + await pi.shutdown();
90 + });
92 + test("notify policy defaults to errors only", async () => {
93 + const root = tempProject({ include: ["src/**/*.ts"] });
94 + mkdirSync(join(root, "src"));
95 + writeFileSync(join(root, "src", "a.ts"), "// llmiterate: implement foo\n");
97 + const worker = new FakeWorker(() => { throw new Error("bad auth"); });
98 + const pi = bootLlmiterate(root, worker);
100 + await pi.command("llmiterate", "scan");
101 + await eventually(() => pi.ui.notifications.some((n) => n.message.includes("bad auth")));
102 + expect(pi.ui.notifications.filter((n) => n.message.startsWith("llmiterate queued src/"))).toHaveLength(0);
103 + expect(pi.ui.notifications.some((n) => n.type === "error")).toBe(true);
104 + await pi.shutdown();
105 + });
107 + test("worker guard disables extension inside llmiterate worker", async () => {
108 + const pi = new FakePi(tempDir());
109 + createLlmiterateExtension({ env: { LLMITERATE_WORKER: "1" } as NodeJS.ProcessEnv })(pi.api as never);
110 + expect(pi.commands.size).toBe(0);
111 + expect(pi.handlers.size).toBe(0);
112 + });
113 +});

pi/agent/extensions/llmiterate/__tests__/fake-rpc-child.mjs

Added
new file mode 100644
1 +import { writeFileSync } from "node:fs";
2 +import { join } from "node:path";
4 +const mode = process.argv[2] ?? "ok";
5 +const root = process.argv[3] ?? process.cwd();
6 +let buffer = "";
8 +process.stdin.setEncoding("utf8");
9 +process.stdin.on("data", (chunk) => {
10 + buffer += chunk;
11 + const lines = buffer.split("\n");
12 + buffer = lines.pop() || "";
13 + for (const line of lines) handle(line);
14 +});
16 +function handle(line) {
17 + if (!line.trim()) return;
18 + const msg = JSON.parse(line);
20 + if (mode === "env" && msg.type === "new_session") {
21 + writeFileSync(join(root, "env.json"), JSON.stringify({ LLMITERATE_WORKER: process.env.LLMITERATE_WORKER }));
22 + }
24 + if (mode === "fail-new-session" && msg.type === "new_session") {
25 + send({ id: msg.id, type: "response", command: msg.type, success: false, error: "new_session denied" });
26 + return;
27 + }
29 + send({ id: msg.id, type: "response", command: msg.type, success: true });
31 + if (mode === "malformed" && msg.type === "prompt") {
32 + process.stdout.write("not json\n");
33 + return;
34 + }
36 + if (mode === "hang" && msg.type === "prompt") {
37 + send({ type: "message_update", message: { role: "assistant", content: [{ type: "text", text: "streaming forever" }] } });
38 + return;
39 + }
41 + if (msg.type === "prompt") {
42 + send({ type: "message_update", message: { role: "assistant", content: [{ type: "text", text: "streaming" }] } });
43 + send({ type: "tool_execution_start", toolName: "edit" });
44 + send({ type: "tool_execution_end", toolName: "edit", isError: false, result: { content: [{ type: "text", text: "ok" }] } });
45 + send({ type: "agent_end" });
46 + }
49 +function send(value) {
50 + process.stdout.write(JSON.stringify(value) + "\n");

pi/agent/extensions/llmiterate/__tests__/harness.ts

Added
new file mode 100644
1 +import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
2 +import { tmpdir } from "node:os";
3 +import { join } from "node:path";
4 +import { expect } from "bun:test";
5 +import { createLlmiterateExtension } from "../index";
6 +import type { CompiledPathFilter, LlmiterateConfig } from "../core";
7 +import type { PiRpcWorker } from "../rpc";
8 +import type { ProjectWatcher } from "../watcher";
10 +const tempDirs: string[] = [];
11 +const oldXdg = process.env.XDG_STATE_HOME;
13 +export function cleanupHarness(): void {
14 + process.env.XDG_STATE_HOME = oldXdg;
15 + while (tempDirs.length) rmSync(tempDirs.pop()!, { recursive: true, force: true });
18 +export class FakeWorker {
19 + prompts: string[] = [];
20 + started = 0;
21 + finished = 0;
23 + constructor(private readonly handler: (prompt: string) => unknown | Promise<unknown>) {}
25 + async runPrompt(prompt: string): Promise<void> {
26 + this.started++;
27 + this.prompts.push(prompt);
28 + try {
29 + await this.handler(prompt);
30 + } finally {
31 + this.finished++;
32 + }
33 + }
35 + dispose(): void {}
38 +export class FakeWatcher {
39 + errorCount = 0;
40 + watcherCount = 1;
41 + constructor(private readonly root: string, private readonly onFileReady: (absolutePath: string) => void) {}
42 + start(): void {}
43 + stop(): void {}
44 + scanAll(onFile: (absolutePath: string) => number): number {
45 + let total = 0;
46 + walk(this.root, (file) => { total += onFile(file); });
47 + return total;
48 + }
49 + trigger(file: string): void { this.onFileReady(file); }
52 +export class FakePi {
53 + handlers = new Map<string, Function[]>();
54 + commands = new Map<string, Function>();
55 + ui = new FakeUi();
56 + api = {
57 + on: (event: string, handler: Function) => {
58 + const list = this.handlers.get(event) ?? [];
59 + list.push(handler);
60 + this.handlers.set(event, list);
61 + },
62 + registerCommand: (name: string, command: { handler: Function }) => {
63 + this.commands.set(name, command.handler);
64 + },
65 + };
67 + constructor(readonly cwd: string) {}
69 + async start(cwd = this.cwd): Promise<void> {
70 + for (const handler of this.handlers.get("session_start") ?? []) {
71 + await handler({}, { cwd, hasUI: true, ui: this.ui });
72 + }
73 + }
75 + async shutdown(): Promise<void> {
76 + for (const handler of this.handlers.get("session_shutdown") ?? []) await handler({});
77 + }
79 + async command(name: string, args: string): Promise<void> {
80 + await this.commands.get(name)?.(args, { cwd: this.cwd, hasUI: true, ui: this.ui });
81 + }
84 +export class FakeUi {
85 + notifications: Array<{ message: string; type: string }> = [];
86 + statuses: Array<{ key: string; value: string | undefined }> = [];
87 + theme = { fg: (_: string, text: string) => text, bold: (text: string) => text };
88 + notify(message: string, type = "info"): void { this.notifications.push({ message, type }); }
89 + setStatus(key: string, value: string | undefined): void { this.statuses.push({ key, value }); }
90 + setWidget(): void {}
93 +export function bootLlmiterate(cwd: string, worker: FakeWorker): FakePi {
94 + process.env.XDG_STATE_HOME = tempDir();
95 + const pi = new FakePi(cwd);
96 + createLlmiterateExtension({
97 + makeWorker: () => worker as unknown as PiRpcWorker,
98 + makeWatcher: (watchRoot: string, _config: LlmiterateConfig, _filter: CompiledPathFilter, onFileReady: (absolutePath: string) => void) =>
99 + new FakeWatcher(watchRoot, onFileReady) as unknown as ProjectWatcher,
100 + now: () => 123,
101 + openEditor: () => undefined,
102 + })(pi.api as never);
103 + void pi.start(cwd);
104 + return pi;
107 +export function tempProject(llmiterate: Record<string, unknown>): string {
108 + const root = tempDir();
109 + mkdirSync(join(root, ".pi"));
110 + writeFileSync(join(root, ".pi", "settings.json"), JSON.stringify({ llmiterate }, null, 2));
111 + return root;
114 +export function tempDir(): string {
115 + const dir = mkdtempSync(join(tmpdir(), "llmiterate-ext-"));
116 + tempDirs.push(dir);
117 + return dir;
120 +export async function eventually(predicate: () => boolean): Promise<void> {
121 + const deadline = Date.now() + 1500;
122 + while (Date.now() < deadline) {
123 + if (predicate()) return;
124 + await new Promise((resolve) => setTimeout(resolve, 10));
126 + expect(predicate()).toBe(true);
129 +function walk(dir: string, onFile: (file: string) => void): void {
130 + const entries = readdirSync(dir, { withFileTypes: true });
131 + for (const entry of entries) {
132 + const file = join(dir, entry.name);
133 + if (entry.isDirectory()) walk(file, onFile);
134 + else if (entry.isFile()) onFile(file);

pi/agent/extensions/llmiterate/__tests__/log.test.ts

Added
new file mode 100644
1 +import { mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
2 +import { tmpdir } from "node:os";
3 +import { join } from "node:path";
4 +import { afterEach, describe, expect, test } from "bun:test";
5 +import { latestSessionFile, parseEditorCommand, renderLatestSessionLog, renderSessionLogMarkdown } from "../log";
7 +const tempDirs: string[] = [];
9 +afterEach(() => {
10 + while (tempDirs.length) rmSync(tempDirs.pop()!, { recursive: true, force: true });
11 +});
13 +describe("editor command parsing", () => {
14 + test("splits VISUAL/EDITOR without shell", () => {
15 + expect(parseEditorCommand("nvim -p --cmd 'set ft=markdown'")).toEqual({
16 + command: "nvim",
17 + args: ["-p", "--cmd", "set ft=markdown"],
18 + });
19 + expect(parseEditorCommand("code --wait")).toEqual({ command: "code", args: ["--wait"] });
20 + expect(parseEditorCommand(" ")).toBeUndefined();
21 + });
22 +});
24 +describe("llmiterate log renderer", () => {
25 + test("renders session JSONL to markdown", () => {
26 + const root = tempDir();
27 + const session = join(root, "session.jsonl");
28 + writeFileSync(session, [
29 + JSON.stringify({ message: { role: "user", content: "do thing" } }),
30 + JSON.stringify({ message: { role: "assistant", content: [{ type: "text", text: "I edited it." }] } }),
31 + JSON.stringify({ type: "tool_execution_end", toolName: "edit", isError: false }),
32 + ].join("\n") + "\n");
34 + expect(renderSessionLogMarkdown(session)).toContain("## Assistant");
35 + expect(renderSessionLogMarkdown(session)).toContain("I edited it.");
36 + expect(renderSessionLogMarkdown(session)).not.toContain("{\"message\"");
37 + });
39 + test("picks newest jsonl recursively and writes latest markdown", () => {
40 + const root = tempDir();
41 + mkdirSync(join(root, "a"));
42 + const older = join(root, "old.jsonl");
43 + const newer = join(root, "a", "new.jsonl");
44 + writeFileSync(older, JSON.stringify({ message: { role: "assistant", content: "old" } }) + "\n");
45 + writeFileSync(newer, JSON.stringify({ message: { role: "assistant", content: "new" } }) + "\n");
46 + utimesSync(older, new Date(1000), new Date(1000));
47 + utimesSync(newer, new Date(2000), new Date(2000));
49 + expect(latestSessionFile(root)).toBe(newer);
50 + const target = renderLatestSessionLog(root, join(root, "logs"));
51 + expect(target?.sessionFile).toBe(newer);
52 + expect(readFileSync(target!.markdownFile, "utf-8")).toContain("new");
53 + });
54 +});
56 +function tempDir(): string {
57 + const dir = mkdtempSync(join(tmpdir(), "llmiterate-log-"));
58 + tempDirs.push(dir);
59 + return dir;

pi/agent/extensions/llmiterate/__tests__/rpc.test.ts

Modified
1 -import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
1 +import { mkdtempSync, readFileSync, rmSync } from "node:fs";
2 2 import { tmpdir } from "node:os";
3 3 import { join } from "node:path";
4 4 import { afterEach, describe, expect, test } from "bun:test";
5 -import { PiRpcWorker } from "../rpc";
5 +import { LLMITERATE_WORKER_ENV, PiRpcWorker, workerArgs } from "../rpc";
6 6 import type { RpcEvent } from "../types";
8 8 const tempDirs: string[] = [];
9 9 const workers: PiRpcWorker[] = [];
10 +const fakeRpcScript = new URL("./fake-rpc-child.mjs", import.meta.url).pathname;
12 +type FakeRpcMode = "ok" | "fail-new-session" | "malformed" | "env" | "hang";
11 14 afterEach(() => {
12 15 while (workers.length) workers.pop()!.dispose();
13 16 while (tempDirs.length) rmSync(tempDirs.pop()!, { recursive: true, force: true });
16 -function tempDir(): string {
17 - const dir = mkdtempSync(join(tmpdir(), "llmiterate-rpc-"));
18 - tempDirs.push(dir);
19 - return dir;
19 +describe("PiRpcWorker args", () => {
20 + test("builds llmiterate worker invocation", () => {
21 + expect(workerArgs({ sessionDir: "/state/sessions", model: "zai/glm-5.1", thinking: "high" })).toEqual([
22 + "--mode", "rpc",
23 + "--offline",
24 + "--session-dir", "/state/sessions",
25 + "--append-system-prompt", expect.stringContaining("llmiterate"),
26 + "--model", "zai/glm-5.1",
27 + "--thinking", "high",
28 + ]);
29 + });
31 + test("does not use no-extensions and sets worker env", async () => {
32 + const root = tempDir();
33 + const worker = fakeWorker(root, "env");
34 + workers.push(worker);
36 + await worker.runPrompt("do thing", "job name");
37 + expect(JSON.parse(readFileSync(join(root, "env.json"), "utf-8"))).toMatchObject({
38 + [LLMITERATE_WORKER_ENV]: "1",
39 + });
40 + });
41 +});
22 43 describe("PiRpcWorker integration", () => {
23 44 test("runs prompt through JSON-RPC worker and forwards events", async () => {
24 45 const root = tempDir();
25 - const fake = writeFakeRpc(root, "ok");
26 46 const events: RpcEvent[] = [];
27 - const worker = new PiRpcWorker({
28 - cwd: root,
29 - sessionDir: join(root, "sessions"),
30 - invocation: { command: process.execPath, args: [fake] },
31 - onEvent: (event) => events.push(event),
32 - });
47 + const worker = fakeWorker(root, "ok", (event) => events.push(event));
33 48 workers.push(worker);
35 50 await worker.runPrompt("do thing", "job name");
46 61 test("rejects concurrent prompts instead of corrupting current prompt", async () => {
47 - const root = tempDir();
48 - const fake = writeFakeRpc(root, "ok");
49 - const worker = new PiRpcWorker({
50 - cwd: root,
51 - sessionDir: join(root, "sessions"),
52 - invocation: { command: process.execPath, args: [fake] },
53 - onEvent: () => {},
54 - });
62 + const worker = fakeWorker(tempDir(), "ok");
55 63 workers.push(worker);
57 65 const first = worker.runPrompt("first", "first job");
62 70 test("rejects failed RPC command", async () => {
63 - const root = tempDir();
64 - const fake = writeFakeRpc(root, "fail-new-session");
65 - const worker = new PiRpcWorker({
66 - cwd: root,
67 - sessionDir: join(root, "sessions"),
68 - invocation: { command: process.execPath, args: [fake] },
69 - onEvent: () => {},
70 - });
71 + const worker = fakeWorker(tempDir(), "fail-new-session");
71 72 workers.push(worker);
73 74 await expect(worker.runPrompt("do thing", "job name")).rejects.toThrow("new_session denied");
77 + test("times out hung prompts", async () => {
78 + const worker = fakeWorker(tempDir(), "hang", () => {}, 20);
79 + workers.push(worker);
81 + await expect(worker.runPrompt("do thing", "job name")).rejects.toThrow("timed out");
82 + });
76 84 test("rejects malformed RPC stdout", async () => {
77 - const root = tempDir();
78 - const fake = writeFakeRpc(root, "malformed");
79 - const worker = new PiRpcWorker({
80 - cwd: root,
81 - sessionDir: join(root, "sessions"),
82 - invocation: { command: process.execPath, args: [fake] },
83 - onEvent: () => {},
84 - });
85 + const worker = fakeWorker(tempDir(), "malformed");
85 86 workers.push(worker);
87 88 await expect(worker.runPrompt("do thing", "job name")).rejects.toThrow();
91 -function writeFakeRpc(root: string, mode: "ok" | "fail-new-session" | "malformed"): string {
92 - const file = join(root, "fake-rpc.js");
93 - writeFileSync(file, `
94 -process.stdin.setEncoding('utf8');
95 -let buffer = '';
96 -process.stdin.on('data', chunk => {
97 - buffer += chunk;
98 - const lines = buffer.split('\\n');
99 - buffer = lines.pop() || '';
100 - for (const line of lines) handle(line);
101 -});
102 -function send(value) { process.stdout.write(JSON.stringify(value) + '\\n'); }
103 -function handle(line) {
104 - if (!line.trim()) return;
105 - const msg = JSON.parse(line);
106 - if (${JSON.stringify(mode)} === 'fail-new-session' && msg.type === 'new_session') {
107 - send({ id: msg.id, type: 'response', command: msg.type, success: false, error: 'new_session denied' });
108 - return;
109 - }
110 - send({ id: msg.id, type: 'response', command: msg.type, success: true });
111 - if (${JSON.stringify(mode)} === 'malformed' && msg.type === 'prompt') {
112 - process.stdout.write('not json\\n');
113 - return;
114 - }
115 - if (msg.type === 'prompt') {
116 - send({ type: 'message_update', message: { role: 'assistant', content: [{ type: 'text', text: 'streaming' }] } });
117 - send({ type: 'tool_execution_start', toolName: 'edit' });
118 - send({ type: 'tool_execution_end', toolName: 'edit', isError: false, result: { content: [{ type: 'text', text: 'ok' }] } });
119 - send({ type: 'agent_end' });
120 - }
92 +function fakeWorker(root: string, mode: FakeRpcMode, onEvent: (event: RpcEvent) => void = () => {}, timeoutMs?: number): PiRpcWorker {
93 + return new PiRpcWorker({
94 + cwd: root,
95 + sessionDir: join(root, "sessions"),
96 + invocation: { command: process.execPath, args: [fakeRpcScript, mode, root] },
97 + timeoutMs,
98 + onEvent,
99 + });
122 -`, "utf-8");
123 - return file;
102 +function tempDir(): string {
103 + const dir = mkdtempSync(join(tmpdir(), "llmiterate-rpc-"));
104 + tempDirs.push(dir);
105 + return dir;

pi/agent/extensions/llmiterate/__tests__/ui.test.ts

Modified
1 1 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2 2 import { describe, expect, test } from "bun:test";
3 -import { defaultConfig, parseMarkerPrompts } from "../core";
3 +import { defaultConfig, normalizeConfig, parseMarkerPrompts } from "../core";
4 4 import { LlmiterateWidget, renderLlmiterateUi } from "../ui";
5 5 import type { LlmiterateRun } from "../types";
18 18 test("status line states", () => {
19 19 const calls: UiCall[] = [];
20 20 const ctx = fakeContext({ setStatus: (key, value) => calls.push({ key, value }) });
21 + const activeConfig = normalizeConfig({ include: ["src/**/*.ts"] });
22 - renderLlmiterateUi(ctx, false, [], { config: defaultConfig(), watchErrors: 0, queuedRuns: 0 });
23 - renderLlmiterateUi(ctx, false, [], { config: defaultConfig(), lockError: "held", watchErrors: 0, queuedRuns: 0 });
24 - renderLlmiterateUi(ctx, false, [], { config: defaultConfig(), watchErrors: 2, queuedRuns: 0 });
25 - renderLlmiterateUi(ctx, false, [], { config: defaultConfig(), watchErrors: 0, queuedRuns: 3 });
23 + renderLlmiterateUi(ctx, false, [], { config: defaultConfig(), watchErrors: 0, watchDirs: 0, queuedRuns: 0 });
24 + renderLlmiterateUi(ctx, false, [], { config: activeConfig, lockError: "held", watchErrors: 0, watchDirs: 0, queuedRuns: 0 });
25 + renderLlmiterateUi(ctx, false, [], { config: activeConfig, watchErrors: 2, watchDirs: 0, queuedRuns: 0 });
26 + renderLlmiterateUi(ctx, false, [], { config: activeConfig, watchErrors: 0, watchDirs: 2, queuedRuns: 3 });
27 28 expect(calls.map((c) => c.value)).toEqual([
28 29 "llmiterate idle",
36 37 let widgetValue: unknown = "not cleared";
37 38 const ctx = fakeContext({ setWidget: (_key, value) => { widgetValue = value; } });
39 - renderLlmiterateUi(ctx, false, [], { config: defaultConfig(), watchErrors: 0, queuedRuns: 0 });
40 + renderLlmiterateUi(ctx, false, [], { config: defaultConfig(), watchErrors: 0, watchDirs: 0, queuedRuns: 0 });
40 41 expect(widgetValue).toBeUndefined();
66 67 function sampleRun(): LlmiterateRun {
67 - const [block] = parseMarkerPrompts("src/main.ts", "LLM implement foo and bar");
68 + const [block] = parseMarkerPrompts("src/main.ts", "// llmiterate: implement foo and bar");
68 69 return {
69 70 id: 1,
70 71 block: block!,

pi/agent/extensions/llmiterate/__tests__/watcher.test.ts

Modified
1 -import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
1 +import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
2 2 import { tmpdir } from "node:os";
3 3 import { join } from "node:path";
4 4 import { afterEach, describe, expect, test } from "bun:test";
22 22 describe("ProjectWatcher integration", () => {
23 - test("default config scans nothing", () => {
23 + test("default config scans normal files and excludes metadata dirs", () => {
24 24 const root = tempDir();
25 25 mkdirSync(join(root, "src"));
26 - writeFileSync(join(root, "src", "a.ts"), "LLM ignored");
26 + mkdirSync(join(root, ".jj"));
27 + writeFileSync(join(root, "src", "a.ts"), "// llmiterate: seen");
28 + writeFileSync(join(root, ".jj", "ignored.ts"), "// llmiterate: ignored");
28 30 const config = normalizeConfig({ debounceMs: 10 });
29 31 const seen: string[] = [];
30 32 const watcher = new ProjectWatcher(root, config, compilePathFilter(config), (file) => seen.push(file), () => {});
31 33 watchers.push(watcher);
33 - expect(watcher.scanAll((file) => { seen.push(file); return 1; })).toBe(0);
34 - expect(seen).toEqual([]);
35 + expect(watcher.scanAll((file) => { seen.push(file); return 1; })).toBe(1);
36 + expect(seen.map((p) => p.replace(root, ""))).toEqual(["/src/a.ts"]);
37 - test("default config starts no filesystem watchers", async () => {
39 + test("default config starts filesystem watchers", async () => {
38 40 const root = tempDir();
39 41 mkdirSync(join(root, "src"));
44 46 watchers.push(watcher);
46 48 watcher.start();
47 - writeFileSync(join(root, "src", "a.ts"), "LLM ignored");
48 - await sleep(40);
49 + writeFileSync(join(root, "src", "a.ts"), "// llmiterate: seen");
50 + await eventually(() => seen.some((p) => p.endsWith("a.ts")));
49 51 expect(watcher.errorCount).toBe(0);
50 - expect(seen).toEqual([]);
53 54 test("scanAll respects include whitelist and aggregates callback results", () => {
72 73 expect(seen.map((p) => p.replace(root, ""))).toEqual(["/src/a.ts"]);
76 + test("start watches dirs without queuing old files", async () => {
77 + const root = tempDir();
78 + mkdirSync(join(root, "src"));
79 + writeFileSync(join(root, "src", "old.ts"), "// llmiterate: old");
80 + const config = normalizeConfig({ include: ["src/**/*.ts"], exclude: [], debounceMs: 20 });
81 + const seen: string[] = [];
82 + const watcher = new ProjectWatcher(root, config, compilePathFilter(config), (file) => seen.push(file), () => {});
83 + watchers.push(watcher);
85 + watcher.start();
86 + await sleep(350);
87 + expect(watcher.watcherCount).toBeGreaterThanOrEqual(2);
88 + expect(seen).toEqual([]);
89 + });
75 91 test("watcher emits debounced file save events", async () => {
76 92 const root = tempDir();
77 93 mkdirSync(join(root, "src"));
114 130 watcher.start();
115 131 mkdirSync(join(root, "nested"));
116 132 await sleep(60);
117 - writeFileSync(join(root, "nested", "moved.ts"), "LLM hello");
133 + writeFileSync(join(root, "nested", "moved.ts"), "// llmiterate: hello");
118 134 await eventually(() => seen.some((p) => p.endsWith("moved.ts")));
137 + test("fs.watch atomic-save rename queues final path", async () => {
138 + const root = tempDir();
139 + mkdirSync(join(root, "src"));
140 + const config = normalizeConfig({ include: ["src/**/*.ts"], exclude: [], debounceMs: 20 });
141 + const seen: string[] = [];
142 + const watcher = new ProjectWatcher(root, config, compilePathFilter(config), (file) => seen.push(file), () => {});
143 + watchers.push(watcher);
145 + watcher.start();
146 + await sleep(40);
147 + writeFileSync(join(root, "src", "a.ts.tmp"), "// temp write");
148 + renameSync(join(root, "src", "a.ts.tmp"), join(root, "src", "a.ts"));
150 + await eventually(() => seen.some((p) => p.endsWith("src/a.ts")));
151 + expect(seen.every((p) => !p.endsWith(".tmp"))).toBe(true);
152 + });
154 + test("fs.watch debounce collapses save bursts", async () => {
155 + const root = tempDir();
156 + mkdirSync(join(root, "src"));
157 + const config = normalizeConfig({ include: ["src/**/*.ts"], exclude: [], debounceMs: 50 });
158 + const seen: string[] = [];
159 + const watcher = new ProjectWatcher(root, config, compilePathFilter(config), (file) => seen.push(file), () => {});
160 + watchers.push(watcher);
162 + watcher.start();
163 + await sleep(40);
164 + const file = join(root, "src", "burst.ts");
165 + writeFileSync(file, "// llmiterate: one");
166 + await sleep(10);
167 + writeFileSync(file, "// llmiterate: two");
168 + await sleep(10);
169 + writeFileSync(file, "// llmiterate: three");
171 + await eventually(() => seen.some((p) => p.endsWith("burst.ts")));
172 + await sleep(120);
173 + expect(seen.filter((p) => p.endsWith("burst.ts"))).toHaveLength(1);
174 + });
176 + test("fs.watch removes deleted directory watchers", async () => {
177 + const root = tempDir();
178 + mkdirSync(join(root, "src", "gone"), { recursive: true });
179 + const config = normalizeConfig({ include: ["src/**/*.ts"], exclude: [], debounceMs: 20 });
180 + const watcher = new ProjectWatcher(root, config, compilePathFilter(config), () => {}, () => {});
181 + watchers.push(watcher);
183 + watcher.start();
184 + await eventually(() => watcher.watcherCount >= 3);
185 + const before = watcher.watcherCount;
186 + rmSync(join(root, "src", "gone"), { recursive: true, force: true });
188 + await eventually(() => watcher.watcherCount < before);
189 + });
191 + test("respects .gitignore and .ignore during scan and watch", async () => {
192 + const root = tempDir();
193 + mkdirSync(join(root, "src", "ignored"), { recursive: true });
194 + mkdirSync(join(root, "logs"));
195 + writeFileSync(join(root, ".gitignore"), "logs/\n");
196 + writeFileSync(join(root, "src", ".ignore"), "ignored/\n*.tmp\n");
197 + writeFileSync(join(root, "logs", "a.ts"), "// llmiterate: ignored");
198 + writeFileSync(join(root, "src", "ignored", "b.ts"), "// llmiterate: ignored");
199 + writeFileSync(join(root, "src", "c.tmp"), "// llmiterate: ignored");
200 + writeFileSync(join(root, "src", "ok.ts"), "// llmiterate: seen");
202 + const config = normalizeConfig({ include: ["**/*"], exclude: [], debounceMs: 20 });
203 + const seen: string[] = [];
204 + const watcher = new ProjectWatcher(root, config, compilePathFilter(config), (file) => seen.push(file), () => {});
205 + watchers.push(watcher);
207 + expect(watcher.scanAll((file) => { seen.push(file); return 1; })).toBe(1);
208 + expect(seen.map((p) => p.replace(root, ""))).toEqual(["/src/ok.ts"]);
210 + seen.length = 0;
211 + watcher.start();
212 + await sleep(40);
213 + writeFileSync(join(root, "logs", "new.ts"), "// llmiterate: ignored");
214 + writeFileSync(join(root, "src", "ignored", "new.ts"), "// llmiterate: ignored");
215 + writeFileSync(join(root, "src", "ok2.ts"), "// llmiterate: seen");
216 + await eventually(() => seen.some((p) => p.endsWith("ok2.ts")));
217 + expect(seen.every((p) => !p.includes("ignored") && !p.includes("logs"))).toBe(true);
218 + });
220 + test("fs.watch new ignore rule unwatches newly ignored subtree", async () => {
221 + const root = tempDir();
222 + mkdirSync(join(root, "src", "noisy"), { recursive: true });
223 + const config = normalizeConfig({ include: ["**/*"], exclude: [], debounceMs: 20 });
224 + const seen: string[] = [];
225 + const watcher = new ProjectWatcher(root, config, compilePathFilter(config), (file) => seen.push(file), () => {});
226 + watchers.push(watcher);
228 + watcher.start();
229 + await eventually(() => watcher.watcherCount >= 3);
230 + const before = watcher.watcherCount;
232 + writeFileSync(join(root, ".gitignore"), "src/noisy/\n");
233 + await eventually(() => watcher.watcherCount < before);
235 + writeFileSync(join(root, "src", "noisy", "ignored.ts"), "// llmiterate: ignored");
236 + await sleep(100);
237 + expect(seen).toEqual([]);
238 + });
240 + test("fs.watch caps watcher count", async () => {
241 + const root = tempDir();
242 + for (let i = 0; i < 8; i++) mkdirSync(join(root, "dir", String(i)), { recursive: true });
243 + const config = normalizeConfig({ include: ["**/*"], exclude: [], debounceMs: 20, maxWatchDirs: 4 });
244 + const watcher = new ProjectWatcher(root, config, compilePathFilter(config), () => {}, () => {});
245 + watchers.push(watcher);
247 + watcher.start();
248 + await sleep(100);
249 + expect(watcher.watcherCount).toBeLessThanOrEqual(4);
250 + expect(watcher.errorCount).toBe(1);
251 + });
253 + test("fs.watch does not watch excluded subtrees", async () => {
254 + const root = tempDir();
255 + mkdirSync(join(root, "src"));
256 + mkdirSync(join(root, "node_modules", "pkg"), { recursive: true });
257 + const config = normalizeConfig({ include: ["**/*.ts"], exclude: ["node_modules/**"], debounceMs: 20 });
258 + const seen: string[] = [];
259 + const watcher = new ProjectWatcher(root, config, compilePathFilter(config), (file) => seen.push(file), () => {});
260 + watchers.push(watcher);
262 + watcher.start();
263 + await sleep(40);
264 + writeFileSync(join(root, "node_modules", "pkg", "ignored.ts"), "// llmiterate: ignored");
265 + await sleep(100);
266 + expect(seen).toEqual([]);
267 + expect(watcher.watcherCount).toBeLessThan(4);
268 + });
122 271 function sleep(ms: number): Promise<void> {

pi/agent/extensions/llmiterate/bun.lock

Modified
5 5 "lockfileVersion": 1,
6 6 "configVersion": 1,
7 7 "workspaces": {
8 8 "": {
9 9 "name": "@bugabinga/pi-ext-llmiterate",
10 + "dependencies": {
11 + "ignore": "^7.0.5",
12 + },
10 13 "peerDependencies": {
11 14 "@earendil-works/pi-coding-agent": "*",
12 15 "@earendil-works/pi-tui": "*",

pi/agent/extensions/llmiterate/config.ts

Added
new file mode 100644
1 +import * as fs from "node:fs";
2 +import * as path from "node:path";
3 +import { getAgentDir } from "@earendil-works/pi-coding-agent";
4 +import {
5 + BUILTIN_COMMENT_PREFIXES,
6 + DEFAULT_DEBOUNCE_MS,
7 + DEFAULT_EXCLUDE,
8 + DEFAULT_INCLUDE,
9 + DEFAULT_MAX_FILE_BYTES,
10 + DEFAULT_MAX_WATCH_DIRS,
11 + DEFAULT_TIMEOUT_MS,
12 +} from "./constants";
13 +import { isObject, positiveInt, stringArray } from "./util";
15 +export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
16 +export type NotifyPolicy = "off" | "errors" | "done" | "all";
18 +export interface LlmiterateConfig {
19 + enabled: boolean;
20 + include: string[];
21 + exclude: string[];
22 + debounceMs: number;
23 + maxFileBytes: number;
24 + timeoutMs: number;
25 + maxWatchDirs: number;
26 + commentPrefixes: string[];
27 + model?: string;
28 + thinking?: ThinkingLevel;
29 + notify: NotifyPolicy;
32 +export function defaultConfig(): LlmiterateConfig {
33 + return {
34 + enabled: true,
35 + include: [...DEFAULT_INCLUDE],
36 + exclude: [...DEFAULT_EXCLUDE],
37 + debounceMs: DEFAULT_DEBOUNCE_MS,
38 + maxFileBytes: DEFAULT_MAX_FILE_BYTES,
39 + timeoutMs: DEFAULT_TIMEOUT_MS,
40 + maxWatchDirs: DEFAULT_MAX_WATCH_DIRS,
41 + commentPrefixes: [...BUILTIN_COMMENT_PREFIXES],
42 + notify: "errors",
43 + };
46 +export function normalizeConfig(raw: unknown): LlmiterateConfig {
47 + const fallback = defaultConfig();
48 + if (!isObject(raw)) return fallback;
50 + return {
51 + enabled: typeof raw.enabled === "boolean" ? raw.enabled : fallback.enabled,
52 + include: stringArray(raw.include, fallback.include),
53 + exclude: mergeExclude(raw.exclude),
54 + debounceMs: positiveInt(raw.debounceMs, fallback.debounceMs),
55 + maxFileBytes: positiveInt(raw.maxFileBytes, fallback.maxFileBytes),
56 + timeoutMs: positiveInt(raw.timeoutMs, fallback.timeoutMs),
57 + maxWatchDirs: positiveInt(raw.maxWatchDirs, fallback.maxWatchDirs),
58 + commentPrefixes: mergeCommentPrefixes(raw.commentPrefixes),
59 + model: optionalString(raw.model),
60 + thinking: thinkingLevel(raw.thinking),
61 + notify: notifyPolicy(raw.notify, fallback.notify),
62 + };
65 +export function loadConfig(cwd: string): LlmiterateConfig {
66 + const global = readSettingsNamespace(path.join(getAgentDir(), "settings.json"));
67 + const project = readSettingsNamespace(path.join(cwd, ".pi", "settings.json"));
68 + return normalizeConfig({ ...global, ...project });
71 +function readSettingsNamespace(settingsPath: string): Record<string, unknown> {
72 + try {
73 + const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
74 + return isObject(parsed) && isObject(parsed.llmiterate) ? parsed.llmiterate : {};
75 + } catch {
76 + return {};
77 + }
80 +function optionalString(value: unknown): string | undefined {
81 + return typeof value === "string" && value.trim() ? value.trim() : undefined;
84 +function thinkingLevel(value: unknown): ThinkingLevel | undefined {
85 + return value === "off" || value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh"
86 + ? value
87 + : undefined;
90 +function notifyPolicy(value: unknown, fallback: NotifyPolicy): NotifyPolicy {
91 + return value === "off" || value === "errors" || value === "done" || value === "all" ? value : fallback;
94 +function mergeExclude(value: unknown): string[] {
95 + return [...new Set([...DEFAULT_EXCLUDE, ...stringArray(value, [])])];
98 +function mergeCommentPrefixes(value: unknown): string[] {
99 + return normalizeCommentPrefixes([...BUILTIN_COMMENT_PREFIXES, ...stringArray(value, [])]);
102 +function normalizeCommentPrefixes(prefixes: string[]): string[] {
103 + return [...new Set(prefixes.map((p) => p.trim()).filter(Boolean))].sort((a, b) => b.length - a.length);

pi/agent/extensions/llmiterate/constants.ts

Added
new file mode 100644
1 +export const DEFAULT_DEBOUNCE_MS = 3000;
2 +export const DEFAULT_MAX_FILE_BYTES = 1_000_000;
3 +export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
4 +export const DEFAULT_MAX_WATCH_DIRS = 10_000;
5 +export const DEFAULT_INCLUDE = ["**/*"];
6 +export const DEFAULT_EXCLUDE = [
7 + "**/.git/**",
8 + "**/.hg/**",
9 + "**/.svn/**",
10 + "**/.jj/**",
11 + "**/.pi/**",
12 + "**/node_modules/**",
13 + "**/vendor/**",
14 + "**/dist/**",
15 + "**/build/**",
16 + "**/coverage/**",
17 + "**/target/**",
18 + "**/.cache/**",
19 + "**/.next/**",
20 + "**/.gitignore",
21 + "**/.ignore",
22 + ".gitignore",
23 + ".ignore",
24 +];
25 +export const MARKER = "llmiterate:";
26 +export const DISABLE_MARKER = "!llmiterate";
27 +export const BUILTIN_COMMENT_PREFIXES = [
28 + "<!--",
29 + "/**",
30 + "/*",
31 + "///",
32 + "//!",
33 + "//",
34 + "###",
35 + "##",
36 + "#",
37 + "---",
38 + "--",
39 + ";;;",
40 + ";;",
41 + ";",
42 + "%%",
43 + "%",
44 + "::",
45 + "*>",
46 + "*",
47 + "REM",
48 + "rem",
49 + "'",
50 + "dnl",
51 + "DNL",
52 +];
53 +export const STORE_NAMESPACE = "llmiterate";
54 +export const STATE_FILE = "state.json";
55 +export const APP_STATE_DIR = "pi";

pi/agent/extensions/llmiterate/core.ts

Modified
1 -import * as fs from "node:fs";
2 -import * as os from "node:os";
3 -import * as path from "node:path";
4 -import { createHash } from "node:crypto";
5 -import { getAgentDir } from "@earendil-works/pi-coding-agent";
7 -export const DEFAULT_DEBOUNCE_MS = 3000;
8 -export const DEFAULT_MAX_FILE_BYTES = 1_000_000;
9 -export const DEFAULT_INCLUDE: string[] = [];
10 -export const DEFAULT_EXCLUDE = [
11 - "**/.git/**",
12 - "**/.hg/**",
13 - "**/.svn/**",
14 - "**/.pi/**",
15 - "**/node_modules/**",
16 - "**/vendor/**",
17 - "**/dist/**",
18 - "**/build/**",
19 - "**/coverage/**",
20 - "**/target/**",
21 - "**/.cache/**",
22 - "**/.next/**",
23 -];
24 -export const DEFAULT_MARKERS = ["LLM", "PROMPT"];
25 -export const STORE_NAMESPACE = "llmiterate";
26 -export const STATE_FILE = "state.json";
27 -export const APP_STATE_DIR = "pi";
29 -export interface LlmiterateConfig {
30 - enabled: boolean;
31 - include: string[];
32 - exclude: string[];
33 - debounceMs: number;
34 - maxFileBytes: number;
35 - markers: string[];
38 -export interface MarkerPrompt {
39 - marker: string;
40 - file: string;
41 - startLine: number;
42 - endLine: number;
43 - prompt: string;
44 - key: string;
45 - promptHash: string;
48 -export interface ProcessedPrompt {
49 - file: string;
50 - startLine: number;
51 - endLine: number;
52 - promptHash: string;
53 - promptPreview: string;
54 - queuedAt: number;
57 -export interface LlmiterateState {
58 - version: 1;
59 - processed: Record<string, ProcessedPrompt>;
62 -const REGEX_CHARS = /[|\\{}()[\]^$+?.]/;
63 -// File scans call the parser for every saved/scanned file. Cache marker regexes by
64 -// normalized marker list so steady-state scans do not rebuild/sort/escape regexes.
65 -const markerRegexCache = new Map<string, RegExp>();
67 -export function defaultConfig(): LlmiterateConfig {
68 - return {
69 - enabled: true,
70 - include: [...DEFAULT_INCLUDE],
71 - exclude: [...DEFAULT_EXCLUDE],
72 - debounceMs: DEFAULT_DEBOUNCE_MS,
73 - maxFileBytes: DEFAULT_MAX_FILE_BYTES,
74 - markers: [...DEFAULT_MARKERS],
75 - };
78 -export function normalizeConfig(raw: unknown): LlmiterateConfig {
79 - const fallback = defaultConfig();
80 - if (!isObject(raw)) return fallback;
82 - return {
83 - enabled: typeof raw.enabled === "boolean" ? raw.enabled : fallback.enabled,
84 - include: stringArray(raw.include, fallback.include),
85 - exclude: stringArray(raw.exclude, fallback.exclude),
86 - debounceMs: positiveInt(raw.debounceMs, fallback.debounceMs),
87 - maxFileBytes: positiveInt(raw.maxFileBytes, fallback.maxFileBytes),
88 - markers: cleanMarkers(raw.markers, fallback.markers),
89 - };
92 -export function loadConfig(cwd: string): LlmiterateConfig {
93 - const global = readSettingsNamespace(path.join(getAgentDir(), "settings.json"));
94 - const project = readSettingsNamespace(path.join(cwd, ".pi", "settings.json"));
95 - return normalizeConfig({ ...global, ...project });
98 -function readSettingsNamespace(settingsPath: string): Record<string, unknown> {
99 - try {
100 - const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
101 - return isObject(parsed) && isObject(parsed.llmiterate) ? parsed.llmiterate : {};
102 - } catch {
103 - return {};
104 - }
107 -export function projectStoreDir(root: string): string {
108 - const storeDir = path.join(platformStateDir(), STORE_NAMESPACE, hashProjectRoot(root));
109 - migrateLegacyProjectStore(root, storeDir);
110 - return storeDir;
113 -export function platformStateDir(
114 - platform: NodeJS.Platform = process.platform,
115 - env: NodeJS.ProcessEnv = process.env,
116 - home = os.homedir(),
117 -): string {
118 - const paths = platform === "win32" ? path.win32 : path.posix;
120 - if (platform === "win32") {
121 - return paths.join(env.LOCALAPPDATA ?? paths.join(home, "AppData", "Local"), APP_STATE_DIR);
122 - }
124 - if (env.XDG_STATE_HOME) return paths.join(env.XDG_STATE_HOME, APP_STATE_DIR);
126 - if (platform === "darwin") {
127 - return paths.join(home, "Library", "Application Support", APP_STATE_DIR);
128 - }
130 - return paths.join(home, ".local", "state", APP_STATE_DIR);
133 -function legacyProjectStoreDir(root: string): string {
134 - return path.join(getAgentDir(), STORE_NAMESPACE, hashProjectRoot(root));
137 -function migrateLegacyProjectStore(root: string, storeDir: string): void {
138 - const legacy = legacyProjectStoreDir(root);
139 - if (legacy === storeDir || fs.existsSync(storeDir) || !fs.existsSync(legacy)) return;
141 - fs.mkdirSync(path.dirname(storeDir), { recursive: true });
142 - fs.cpSync(legacy, storeDir, {
143 - recursive: true,
144 - filter: (source) => path.basename(source) !== "lock",
145 - });
148 -export function hashProjectRoot(root: string): string {
149 - return createHash("sha256").update(root).digest("hex");
152 -export function loadState(storeDir: string): LlmiterateState {
153 - try {
154 - const parsed = JSON.parse(fs.readFileSync(path.join(storeDir, STATE_FILE), "utf-8"));
155 - if (!isObject(parsed) || parsed.version !== 1 || !isObject(parsed.processed)) {
156 - return emptyState();
157 - }
158 - return { version: 1, processed: parseProcessedPrompts(parsed.processed) };
159 - } catch {
160 - return emptyState();
161 - }
164 -export function saveState(storeDir: string, state: LlmiterateState): void {
165 - fs.mkdirSync(storeDir, { recursive: true });
166 - fs.writeFileSync(path.join(storeDir, STATE_FILE), JSON.stringify(state, null, 2) + "\n", "utf-8");
169 -export function emptyState(): LlmiterateState {
170 - return { version: 1, processed: {} };
173 -function parseProcessedPrompts(raw: Record<string, unknown>): Record<string, ProcessedPrompt> {
174 - const processed: Record<string, ProcessedPrompt> = {};
175 - for (const [key, value] of Object.entries(raw)) {
176 - if (isProcessedPrompt(value)) processed[key] = value;
177 - }
178 - return processed;
181 -function isProcessedPrompt(value: unknown): value is ProcessedPrompt {
182 - if (!isObject(value)) return false;
183 - const keys = Object.keys(value).sort();
184 - if (keys.join("\0") !== "endLine\0file\0promptHash\0promptPreview\0queuedAt\0startLine") return false;
185 - return typeof value.file === "string"
186 - && typeof value.startLine === "number"
187 - && typeof value.endLine === "number"
188 - && typeof value.promptHash === "string"
189 - && typeof value.promptPreview === "string"
190 - && typeof value.queuedAt === "number";
193 -export function parseMarkerPrompts(file: string, text: string, markers = DEFAULT_MARKERS): MarkerPrompt[] {
194 - const markerLine = markerRegex(markers);
195 - const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
196 - const prompts: MarkerPrompt[] = [];
197 - const markdown = isMarkdownPath(file);
198 - let markdownFence: "`" | "~" | undefined;
200 - for (let i = 0; i < lines.length; i++) {
201 - const rawLine = lines[i] ?? "";
202 - const fence = markdownFenceDelimiter(markdown, rawLine);
203 - if (fence) {
204 - markdownFence = markdownFence === fence ? undefined : markdownFence ?? fence;
205 - continue;
206 - }
207 - if (markdownFence) continue;
209 - const first = markerLine.exec(rawLine.trimStart());
210 - if (!first) continue;
212 - const marker = first[1] ?? "LLM";
213 - const firstPromptLine = (first[2] ?? "").trim();
214 - if (!firstPromptLine || isCodeAssignmentPrompt(firstPromptLine)) continue;
216 - const startLine = i + 1;
217 - const body = [firstPromptLine];
218 - let endLine = startLine;
220 - for (let j = i + 1; j < lines.length; j++) {
221 - const nextRawLine = lines[j] ?? "";
222 - if (markdownFenceDelimiter(markdown, nextRawLine)) break;
223 - const next = markerLine.exec(nextRawLine.trimStart());
224 - if (!next || next[1] !== marker) break;
225 - const promptLine = (next[2] ?? "").trim();
226 - if (isCodeAssignmentPrompt(promptLine)) break;
227 - if (promptLine) body.push(promptLine);
228 - endLine = j + 1;
229 - i = j;
230 - }
232 - const prompt = body.join("\n").trim();
233 - if (prompt) prompts.push(makePrompt(file, marker, startLine, endLine, prompt));
234 - }
236 - return prompts;
239 -function makePrompt(file: string, marker: string, startLine: number, endLine: number, prompt: string): MarkerPrompt {
240 - const promptHash = hashString(prompt);
241 - return {
242 - marker,
243 - file,
244 - startLine,
245 - endLine,
246 - prompt,
247 - promptHash,
248 - key: `${file}:${startLine}:${promptHash}`,
249 - };
252 -export function buildAgentPrompt(block: MarkerPrompt): string {
253 - return [
254 - `llmiterate request from @${block.file}:${block.startLine}`,
255 - "",
256 - "Prompt marker contents:",
257 - "```text",
258 - block.prompt,
259 - "```",
260 - "",
261 - "Instructions:",
262 - `- Work in/around @${block.file}.`,
263 - `- Marker span to replace: ${block.file}:${block.startLine}-${block.endLine}.`,
264 - "- Treat the marker line(s) as an inline prompt/TODO, not program code.",
265 - "- Replace the whole marker span with the requested implementation or code change.",
266 - "- Do not leave the marker line(s) behind unless impossible; explain if impossible.",
267 - ].join("\n");
270 -export type CompiledGlobSegment = "**" | RegExp;
272 -export interface CompiledPathFilter {
273 - include: RegExp[];
274 - includeDirPatterns: CompiledGlobSegment[][];
275 - exclude: RegExp[];
276 - excludeRootDirs: Set<string>;
277 - excludePrefixes: string[];
280 -export function compilePathFilter(config: Pick<LlmiterateConfig, "include" | "exclude">): CompiledPathFilter {
281 - // Path filtering is the hottest repository-scan path. Split cheap "dir/**"
282 - // excludes into root-dir Set lookups / prefix checks before falling back to regex.
283 - const includeDirPatterns = config.include.map(compileGlobSegments);
284 - const excludeRootDirs = new Set<string>();
285 - const excludePrefixes: string[] = [];
286 - const exclude: RegExp[] = [];
288 - for (const glob of config.exclude) {
289 - const prefix = simpleGlobstarPrefix(glob);
290 - if (!prefix) {
291 - exclude.push(globToRegExp(glob));
292 - continue;
293 - }
295 - const rootDir = rootDirPrefix(prefix);
296 - if (rootDir) excludeRootDirs.add(rootDir);
297 - else excludePrefixes.push(prefix);
298 - }
300 - return { include: config.include.map(globToRegExp), includeDirPatterns, exclude, excludeRootDirs, excludePrefixes };
303 -export function shouldIncludePath(relPath: string, config: Pick<LlmiterateConfig, "include" | "exclude"> | CompiledPathFilter): boolean {
304 - const filter = isCompiledPathFilter(config) ? config : compilePathFilter(config);
305 - return shouldIncludeCompiledPath(relPath, filter);
308 -export function shouldIncludeCompiledPath(relPath: string, filter: CompiledPathFilter): boolean {
309 - const rel = toSlash(relPath);
310 - if (isExcludedPath(rel, filter)) return false;
311 - return filter.include.some((pattern) => pattern.test(rel));
314 -export function isExcludedPath(relPath: string, filter: CompiledPathFilter): boolean {
315 - const rel = toSlash(relPath);
316 - return filter.excludeRootDirs.has(firstPathSegment(rel))
317 - || filter.excludePrefixes.some((prefix) => rel.startsWith(prefix))
318 - || filter.exclude.some((pattern) => pattern.test(rel));
321 -export function shouldWatchDirectory(relPath: string, filter: CompiledPathFilter): boolean {
322 - const rel = toSlash(relPath);
323 - if (rel && (isExcludedPath(rel, filter) || isExcludedPath(`${rel}/`, filter))) return false;
324 - const segments = rel ? rel.split("/") : [];
325 - return filter.includeDirPatterns.some((include) => includeCanMatchUnderDir(include, segments));
328 -export function globToRegExp(pattern: string): RegExp {
329 - const glob = toSlash(pattern);
330 - let s = "^";
331 - for (let i = 0; i < glob.length;) {
332 - const c = glob[i];
333 - if (c === "*") {
334 - if (glob[i + 1] === "*") {
335 - i += 2;
336 - if (glob[i] === "/") {
337 - i++;
338 - s += "(?:.*/)?";
339 - } else {
340 - s += ".*";
341 - }
342 - continue;
343 - }
344 - s += "[^/]*";
345 - i++;
346 - continue;
347 - }
348 - if (c === "?") {
349 - s += "[^/]";
350 - i++;
351 - continue;
352 - }
353 - if (c === "{") {
354 - const end = glob.indexOf("}", i + 1);
355 - if (end !== -1) {
356 - const parts = glob.slice(i + 1, end).split(",").map((p) => p.trim()).filter(Boolean).map(escapeRegExp);
357 - if (parts.length) {
358 - s += `(?:${parts.join("|")})`;
359 - i = end + 1;
360 - continue;
361 - }
362 - }
363 - }
364 - s += REGEX_CHARS.test(c) ? `\\${c}` : c;
365 - i++;
366 - }
367 - return new RegExp(`${s}$`);
370 -export function toSlash(s: string): string {
371 - // Hot path during repository scans. Avoid split/join allocation when already normalized.
372 - return s.includes("\\") ? s.replace(/\\/g, "/") : s;
375 -function includeCanMatchUnderDir(pattern: CompiledGlobSegment[], dir: string[]): boolean {
376 - const memo = new Map<string, boolean>();
377 - const visit = (patternIndex: number, dirIndex: number): boolean => {
378 - const key = `${patternIndex}:${dirIndex}`;
379 - const cached = memo.get(key);
380 - if (cached !== undefined) return cached;
382 - let result: boolean;
383 - if (dirIndex >= dir.length) {
384 - result = patternIndex < pattern.length;
385 - } else if (patternIndex >= pattern.length) {
386 - result = false;
387 - } else {
388 - const segment = pattern[patternIndex]!;
389 - result = segment === "**"
390 - ? visit(patternIndex + 1, dirIndex) || visit(patternIndex, dirIndex + 1)
391 - : segment.test(dir[dirIndex]!) && visit(patternIndex + 1, dirIndex + 1);
392 - }
394 - memo.set(key, result);
395 - return result;
396 - };
397 - return visit(0, 0);
400 -function compileGlobSegments(pattern: string): CompiledGlobSegment[] {
401 - return toSlash(pattern).split("/").filter(Boolean).map((segment) => segment === "**" ? "**" : globToRegExp(segment));
404 -function hashString(input: string): string {
405 - let hash = 0x811c9dc5;
406 - for (let i = 0; i < input.length; i++) {
407 - hash ^= input.charCodeAt(i);
408 - hash = Math.imul(hash, 0x01000193);
409 - }
410 - return (hash >>> 0).toString(16).padStart(8, "0");
413 -export function previewText(text: string, maxChars: number): string {
414 - const oneLine = text.replace(/\s+/g, " ").trim();
415 - return oneLine.length > maxChars ? `${oneLine.slice(0, Math.max(0, maxChars - 1))}…` : oneLine;
418 -function markerRegex(markers: string[]): RegExp {
419 - const cleaned = cleanMarkers(markers, DEFAULT_MARKERS).sort((a, b) => b.length - a.length);
420 - const cacheKey = cleaned.join("\0");
421 - const cached = markerRegexCache.get(cacheKey);
422 - if (cached) return cached;
424 - const markerAlternatives = cleaned.map(escapeRegExp).join("|");
425 - const compiled = new RegExp(`^(${markerAlternatives})(?:\\s+(.*))?$`);
426 - markerRegexCache.set(cacheKey, compiled);
427 - return compiled;
430 -function markdownFenceDelimiter(markdown: boolean, line: string): "`" | "~" | undefined {
431 - if (!markdown) return undefined;
432 - const trimmed = line.trimStart();
433 - if (/^```/.test(trimmed)) return "`";
434 - if (/^~~~/.test(trimmed)) return "~";
435 - return undefined;
438 -function isMarkdownPath(file: string): boolean {
439 - return /(?:^|\.)(?:md|mdx|markdown)$/i.test(file);
442 -function isCodeAssignmentPrompt(prompt: string): boolean {
443 - return prompt.startsWith("=");
446 -function simpleGlobstarPrefix(glob: string): string | undefined {
447 - const normalized = toSlash(glob);
448 - if (!normalized.endsWith("/**")) return undefined;
449 - const prefix = normalized.slice(0, -2);
450 - return /[*?{[]/.test(prefix) ? undefined : prefix;
453 -function rootDirPrefix(prefix: string): string | undefined {
454 - const dir = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
455 - return dir && !dir.includes("/") ? dir : undefined;
458 -function firstPathSegment(path: string): string {
459 - const slash = path.indexOf("/");
460 - return slash === -1 ? path : path.slice(0, slash);
463 -function escapeRegExp(s: string): string {
464 - return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
467 -function isObject(value: unknown): value is Record<string, unknown> {
468 - return typeof value === "object" && value !== null && !Array.isArray(value);
471 -function stringArray(value: unknown, fallback: string[]): string[] {
472 - return Array.isArray(value) && value.every((v) => typeof v === "string" && v.trim())
473 - ? value.map((v) => v.trim())
474 - : [...fallback];
477 -function positiveInt(value: unknown, fallback: number): number {
478 - return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
481 -function cleanMarkers(value: unknown, fallback: string[]): string[] {
482 - const raw = stringArray(value, fallback);
483 - const cleaned = raw.map((m) => m.trim()).filter((m) => m.length > 0 && !/[\r\n]/.test(m));
484 - return cleaned.length ? cleaned : [...fallback];
487 -function isCompiledPathFilter(value: Pick<LlmiterateConfig, "include" | "exclude"> | CompiledPathFilter): value is CompiledPathFilter {
488 - return "includeDirPatterns" in value;
1 +export * from "./config";
2 +export * from "./constants";
3 +export * from "./parser";
4 +export * from "./path-filter";
5 +export * from "./prompt";
6 +export * from "./state";
7 +export * from "./util";

pi/agent/extensions/llmiterate/index.ts

Modified
1 1 import * as fs from "node:fs";
2 2 import * as path from "node:path";
3 3 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
4 -import {
5 - buildAgentPrompt,
6 - compilePathFilter,
7 - emptyState,
8 - loadConfig,
9 - loadState,
10 - parseMarkerPrompts,
11 - previewText,
12 - projectStoreDir,
13 - saveState,
14 - shouldIncludeCompiledPath,
15 - toSlash,
16 - type CompiledPathFilter,
17 - type LlmiterateConfig,
18 - type LlmiterateState,
19 - type MarkerPrompt,
20 -} from "./core";
4 +import { loadConfig, type LlmiterateConfig, type NotifyPolicy } from "./config";
5 +import { compilePathFilter, projectStoreDir, shouldIncludeCompiledPath, type CompiledPathFilter } from "./path-filter";
6 +import { parseMarkerPrompts, type MarkerPrompt } from "./parser";
7 +import { buildAgentPrompt } from "./prompt";
8 +import { emptyState, loadState, saveState, type LlmiterateState, type MarkerRunState } from "./state";
9 +import { previewText, toSlash } from "./util";
21 10 import { acquireLock, findProjectRoot, realPath, releaseLock, type LockHandle } from "./lock";
22 -import { PiRpcWorker } from "./rpc";
11 +import { LLMITERATE_WORKER_ENV, PiRpcWorker } from "./rpc";
12 +import { openInEditor, renderLatestSessionLog } from "./log";
23 13 import { renderLlmiterateUi } from "./ui";
24 14 import { ProjectWatcher } from "./watcher";
25 15 import type { LlmiterateRun, RpcEvent, RpcMessage, RpcTextPart, RpcToolResult } from "./types";
39 29 interface ScannedFile {
40 30 runtime: WatchRuntime;
41 31 projectRel: string;
42 - agentRel: string;
43 32 text: string;
46 -const MAX_RUNS = 20;
35 +type WorkerOptions = ConstructorParameters<typeof PiRpcWorker>[0];
36 +type WorkerFactory = (options: WorkerOptions) => PiRpcWorker;
37 +type WatcherFactory = (
38 + root: string,
39 + config: LlmiterateConfig,
40 + pathFilter: CompiledPathFilter,
41 + onFileReady: (absolutePath: string) => void,
42 + onError: () => void,
43 +) => ProjectWatcher;
45 +export interface LlmiterateExtensionDeps {
46 + env?: NodeJS.ProcessEnv;
47 + now?: () => number;
48 + makeWorker?: WorkerFactory;
49 + makeWatcher?: WatcherFactory;
50 + openEditor?: (file: string, env?: NodeJS.ProcessEnv) => string | undefined;
47 53 const STATE_PROMPT_PREVIEW_CHARS = 120;
54 +const ERROR_PREVIEW_CHARS = 160;
55 +const COMMAND_USAGE = "Usage: /llmiterate [show|hide|status|scan|reset|reload|log]";
49 -export default function (pi: ExtensionAPI) {
50 - let runtime: WatchRuntime | undefined;
51 - let sessionCtx: ExtensionContext | undefined;
52 - let panelVisible = false;
53 - let nextRunId = 1;
54 - let activeRunId: number | undefined;
55 - let activeJob = false;
56 - let rpcWorker: PiRpcWorker | undefined;
57 - const runs: LlmiterateRun[] = [];
57 +export function createLlmiterateExtension(deps: LlmiterateExtensionDeps = {}) {
58 + return function llmiterate(pi: ExtensionAPI) {
59 + const env = deps.env ?? process.env;
60 + if (env[LLMITERATE_WORKER_ENV] === "1") return;
61 + new LlmiterateController(pi, deps, env).register();
62 + };
59 - pi.on("session_start", async (_event, ctx) => {
60 - sessionCtx = ctx;
61 - start(ctx.cwd);
62 - updateUi(ctx);
63 - });
65 +export default createLlmiterateExtension();
65 - pi.on("session_shutdown", async () => {
66 - stop();
67 - sessionCtx = undefined;
68 - activeRunId = undefined;
69 - });
67 +class LlmiterateController {
68 + private runtime?: WatchRuntime;
69 + private sessionCtx?: ExtensionContext;
70 + private panelVisible = false;
71 + private nextRunId = 1;
72 + private activeRunId?: number;
73 + private activeJob = false;
74 + private rpcWorker?: PiRpcWorker;
75 + private readonly runs: LlmiterateRun[] = [];
71 - pi.registerCommand("llmiterate", {
72 - description: "Toggle/show llmiterate watcher UI. Args: show | hide | status | scan | reset | reload",
73 - handler: async (args, ctx) => {
74 - runCommand(args.trim().toLowerCase(), ctx);
75 - updateUi(ctx);
76 - },
77 - });
77 + private readonly now: () => number;
78 + private readonly makeWorker: WorkerFactory;
79 + private readonly makeWatcher: WatcherFactory;
80 + private readonly openEditor: (file: string, env?: NodeJS.ProcessEnv) => string | undefined;
79 - function runCommand(command: string, ctx: ExtensionCommandContext): void {
82 + constructor(
83 + private readonly pi: ExtensionAPI,
84 + deps: LlmiterateExtensionDeps,
85 + private readonly env: NodeJS.ProcessEnv,
86 + ) {
87 + this.now = deps.now ?? (() => Date.now());
88 + this.makeWorker = deps.makeWorker ?? ((options) => new PiRpcWorker(options));
89 + this.makeWatcher = deps.makeWatcher ?? ((root, config, pathFilter, onFileReady, onError) =>
90 + new ProjectWatcher(root, config, pathFilter, onFileReady, onError));
91 + this.openEditor = deps.openEditor ?? openInEditor;
92 + }
94 + register(): void {
95 + this.pi.on("session_start", async (_event, ctx) => this.onSessionStart(ctx));
96 + this.pi.on("session_shutdown", async () => this.onSessionShutdown());
97 + this.pi.registerCommand("llmiterate", {
98 + description: "Toggle/show llmiterate watcher UI. Args: show | hide | status | scan | reset | reload | log",
99 + handler: async (args, ctx) => {
100 + this.runCommand(args.trim().toLowerCase(), ctx);
101 + this.updateUi(ctx);
102 + },
103 + });
106 + private onSessionStart(ctx: ExtensionContext): void {
107 + this.sessionCtx = ctx;
108 + this.start(ctx.cwd);
109 + this.updateUi(ctx);
112 + private onSessionShutdown(): void {
113 + this.stop();
114 + this.sessionCtx = undefined;
115 + this.activeRunId = undefined;
118 + private runCommand(command: string, ctx: ExtensionCommandContext): void {
80 119 switch (command) {
81 - case "": panelVisible = !panelVisible; return;
120 + case "": this.panelVisible = !this.panelVisible; return;
82 121 case "show":
83 - case "status": panelVisible = true; return;
84 - case "hide": panelVisible = false; return;
85 - case "scan": scanCommand(ctx); return;
86 - case "reset": resetCommand(ctx); return;
87 - case "reload":
88 - start(ctx.cwd);
89 - ctx.ui.notify("llmiterate config/watcher reloaded", "info");
90 - return;
91 - default:
92 - ctx.ui.notify("Usage: /llmiterate [show|hide|status|scan|reset|reload]", "warning");
122 + case "status": this.panelVisible = true; return;
123 + case "hide": this.panelVisible = false; return;
124 + case "scan": this.scanCommand(ctx); return;
125 + case "reset": this.resetCommand(ctx); return;
126 + case "reload": this.reloadCommand(ctx); return;
127 + case "log": this.logCommand(ctx); return;
128 + default: ctx.ui.notify(COMMAND_USAGE, "warning");
96 - function scanCommand(ctx: ExtensionCommandContext): void {
97 - if (notifyIfStandby(ctx)) {
98 - panelVisible = true;
132 + private scanCommand(ctx: ExtensionCommandContext): void {
133 + if (this.notifyIfStandby(ctx)) {
134 + this.panelVisible = true;
99 135 return;
102 - const count = scanAll();
103 - panelVisible = true;
138 + const count = this.scanAll();
139 + this.panelVisible = true;
104 140 ctx.ui.notify(`llmiterate scan queued ${count} new prompt(s)`, "info");
107 - function resetCommand(ctx: ExtensionCommandContext): void {
108 - if (notifyIfStandby(ctx)) return;
143 + private resetCommand(ctx: ExtensionCommandContext): void {
144 + if (this.notifyIfStandby(ctx)) return;
110 - if (runtime) {
111 - runtime.state = emptyState();
112 - persistState(runtime);
146 + if (this.runtime) {
147 + this.runtime.state = emptyState();
148 + this.persistState(this.runtime);
114 - stopWorker();
115 - runs.length = 0;
116 - activeRunId = undefined;
150 + this.stopWorker();
151 + this.runs.length = 0;
152 + this.activeRunId = undefined;
117 153 ctx.ui.notify("llmiterate state reset", "info");
120 - function notifyIfStandby(ctx: ExtensionCommandContext): boolean {
121 - if (!runtime?.lockError) return false;
122 - ctx.ui.notify(`llmiterate inactive: ${runtime.lockError}`, "warning");
156 + private reloadCommand(ctx: ExtensionCommandContext): void {
157 + this.start(ctx.cwd);
158 + ctx.ui.notify("llmiterate config/watcher reloaded", "info");
161 + private logCommand(ctx: ExtensionCommandContext): void {
162 + if (!this.runtime) return;
164 + const target = renderLatestSessionLog(sessionDir(this.runtime), path.join(this.runtime.storeDir, "logs"));
165 + if (!target) {
166 + ctx.ui.notify("llmiterate has no worker session logs yet", "warning");
167 + return;
170 + const error = this.openEditor(target.markdownFile, this.env);
171 + if (error) ctx.ui.notify(`llmiterate log written: ${target.markdownFile} (${error})`, "warning");
174 + private notifyIfStandby(ctx: ExtensionCommandContext): boolean {
175 + if (!this.runtime?.lockError) return false;
176 + ctx.ui.notify(`llmiterate inactive: ${this.runtime.lockError}`, "warning");
123 177 return true;
126 - function start(cwd: string): void {
127 - stop();
180 + private start(cwd: string): void {
181 + this.stop();
128 183 const root = findProjectRoot(cwd);
129 184 const config = loadConfig(root);
130 185 const storeDir = projectStoreDir(root);
131 - const state = loadState(storeDir);
132 - runtime = {
186 + this.runtime = {
134 188 cwd: realPath(cwd),
135 189 config,
136 190 pathFilter: compilePathFilter(config),
137 191 storeDir,
138 - state,
192 + state: loadState(storeDir),
140 - if (!config.enabled) return;
142 - const lock = acquireLock(storeDir);
195 + if (!config.enabled) return;
196 + this.activateWatcher(this.runtime);
199 + private activateWatcher(runtime: WatchRuntime): void {
200 + const lock = acquireLock(runtime.storeDir);
143 201 if (typeof lock === "string") {
144 202 runtime.lockError = lock;
145 203 return;
147 206 runtime.lock = lock;
148 - runtime.watcher = new ProjectWatcher(root, config, runtime.pathFilter, scanFile, () => updateUi(sessionCtx));
207 + runtime.watcher = this.makeWatcher(
208 + runtime.root,
209 + runtime.config,
210 + runtime.pathFilter,
211 + (file) => this.scanFile(file),
212 + () => this.updateUi(this.sessionCtx),
213 + );
149 214 runtime.watcher.start();
152 - function stop(): void {
153 - if (!runtime) return;
154 - runtime.watcher?.stop();
155 - stopWorker();
156 - if (runtime.lock) releaseLock(runtime.lock);
157 - runtime = undefined;
217 + private stop(): void {
218 + if (!this.runtime) return;
220 + this.runtime.watcher?.stop();
221 + this.stopWorker();
222 + if (this.runtime.lock) releaseLock(this.runtime.lock);
223 + this.runtime = undefined;
160 - function scanFile(absPath: string): number {
161 - const file = readScannedFile(absPath);
226 + private scanFile(absPath: string): number {
227 + const file = this.readScannedFile(absPath);
162 228 if (!file) return 0;
164 230 let queued = 0;
165 - const blocks = parseMarkerPrompts(file.projectRel, file.text, file.runtime.config.markers);
166 - for (const block of blocks) {
167 - if (file.runtime.state.processed[block.key]) continue;
168 - recordProcessedPrompt(file.runtime, block);
169 - enqueueRun({ ...block, file: file.agentRel }, file.projectRel, absPath);
231 + for (const block of parseMarkerPrompts(file.projectRel, file.text, file.runtime.config.commentPrefixes)) {
232 + if (!this.shouldQueue(file.runtime, block)) continue;
233 + this.recordQueuedPrompt(file.runtime, block);
234 + this.enqueueRun(block, file.projectRel, absPath);
170 235 queued++;
173 - if (queued > 0) persistState(file.runtime);
238 + if (queued > 0) this.persistState(file.runtime);
174 239 return queued;
177 - function readScannedFile(absPath: string): ScannedFile | undefined {
178 - const current = runtime;
179 - if (!current) return undefined;
242 + private readScannedFile(absPath: string): ScannedFile | undefined {
243 + const runtime = this.runtime;
244 + if (!runtime) return undefined;
181 - const projectRel = toSlash(path.relative(current.root, absPath));
182 - if (!shouldIncludeCompiledPath(projectRel, current.pathFilter)) return undefined;
246 + const projectRel = toSlash(path.relative(runtime.root, absPath));
247 + if (!shouldIncludeCompiledPath(projectRel, runtime.pathFilter)) return undefined;
184 249 const stat = statFile(absPath);
185 - if (!stat?.isFile() || stat.size > current.config.maxFileBytes) return undefined;
250 + if (!stat?.isFile() || stat.size > runtime.config.maxFileBytes) return undefined;
187 252 const text = readUtf8(absPath);
188 - if (text === undefined) return undefined;
190 - return {
191 - runtime: current,
192 - projectRel,
193 - agentRel: toSlash(path.relative(current.cwd, absPath)),
194 - text,
195 - };
253 + return text === undefined ? undefined : { runtime, projectRel, text };
198 - function recordProcessedPrompt(current: WatchRuntime, block: MarkerPrompt): void {
199 - current.state.processed[block.key] = {
256 + private shouldQueue(runtime: WatchRuntime, block: MarkerPrompt): boolean {
257 + const existing = runtime.state.markers[block.key];
258 + return !existing || existing.status === "failed";
261 + private recordQueuedPrompt(runtime: WatchRuntime, block: MarkerPrompt): void {
262 + const existing = runtime.state.markers[block.key];
263 + const timestamp = this.now();
264 + runtime.state.markers[block.key] = {
200 265 file: block.file,
201 266 startLine: block.startLine,
202 267 endLine: block.endLine,
203 268 promptHash: block.promptHash,
204 269 promptPreview: previewText(block.prompt, STATE_PROMPT_PREVIEW_CHARS),
205 - queuedAt: Date.now(),
270 + status: "queued",
271 + attempts: (existing?.attempts ?? 0) + 1,
272 + queuedAt: timestamp,
273 + updatedAt: timestamp,
209 - function statFile(absPath: string): fs.Stats | undefined {
210 - try { return fs.statSync(absPath); } catch { return undefined; }
277 + private persistState(runtime: WatchRuntime): void {
278 + saveState(runtime.storeDir, runtime.state);
213 - function readUtf8(absPath: string): string | undefined {
214 - try { return fs.readFileSync(absPath, "utf-8"); } catch { return undefined; }
281 + private scanAll(): number {
282 + return this.runtime?.watcher?.scanAll((file) => this.scanFile(file)) ?? 0;
217 - function persistState(current: WatchRuntime): void {
218 - saveState(current.storeDir, current.state);
285 + private enqueueRun(block: MarkerPrompt, projectFile: string, absoluteFile: string): void {
286 + this.runs.unshift(this.createRun(block, projectFile, absoluteFile));
287 + this.maybeNotify("queued", `llmiterate queued ${projectFile}:${block.startLine}`);
288 + this.startNextRun();
289 + this.updateUi(this.sessionCtx);
221 - function scanAll(): number {
222 - return runtime?.watcher?.scanAll(scanFile) ?? 0;
223 - }
225 - function enqueueRun(block: MarkerPrompt, projectFile: string, absoluteFile: string): void {
226 - runs.unshift(createRun(block, projectFile, absoluteFile));
227 - trimRuns();
228 - startNextRun();
229 - updateUi(sessionCtx);
230 - }
232 - function createRun(block: MarkerPrompt, projectFile: string, absoluteFile: string): LlmiterateRun {
233 - const now = Date.now();
292 + private createRun(block: MarkerPrompt, projectFile: string, absoluteFile: string): LlmiterateRun {
293 + const timestamp = this.now();
234 294 return {
235 - id: nextRunId++,
295 + id: this.nextRunId++,
236 296 block,
237 297 projectFile,
238 298 absoluteFile,
239 299 fullPrompt: buildAgentPrompt(block),
240 300 status: "queued",
241 - queuedAt: now,
242 - updatedAt: now,
301 + queuedAt: timestamp,
302 + updatedAt: timestamp,
243 303 assistantText: "",
244 304 toolText: "",
248 - function trimRuns(): void {
249 - while (runs.length > MAX_RUNS) runs.pop();
250 - }
308 + private startNextRun(): void {
309 + if (this.activeJob || !this.runtime) return;
252 - function startNextRun(): void {
253 - if (activeJob || !runtime) return;
255 - while (runtime) {
256 - const run = nextQueuedRun();
311 + while (this.runtime) {
312 + const run = this.nextQueuedRun();
257 313 if (!run) return;
258 - if (isRunStillValid(run)) {
259 - void runInRpcWorker(run);
314 + if (this.isRunStillValid(run)) {
315 + void this.runInRpcWorker(run);
260 316 return;
262 - failRun(run, "marker span changed before background agent start; skipped stale request");
263 - updateUi(sessionCtx);
318 + this.failRun(run, "marker span changed before background agent start; skipped stale request");
319 + this.updateUi(this.sessionCtx);
267 - function nextQueuedRun(): LlmiterateRun | undefined {
268 - for (let i = runs.length - 1; i >= 0; i--) {
269 - if (runs[i]?.status === "queued") return runs[i];
323 + private nextQueuedRun(): LlmiterateRun | undefined {
324 + for (let i = this.runs.length - 1; i >= 0; i--) {
325 + if (this.runs[i]?.status === "queued") return this.runs[i];
271 327 return undefined;
274 - async function runInRpcWorker(run: LlmiterateRun): Promise<void> {
275 - if (!runtime) return;
277 - if (!isRunStillValid(run)) {
278 - failRun(run, "marker span changed before background agent start; skipped stale request");
279 - updateUi(sessionCtx);
280 - queueMicrotask(startNextRun);
330 + private async runInRpcWorker(run: LlmiterateRun): Promise<void> {
331 + if (!this.runtime) return;
332 + if (!this.isRunStillValid(run)) {
333 + this.failStaleRun(run);
281 334 return;
284 - markRunRunning(run);
285 - updateUi(sessionCtx);
337 + this.markRunRunning(run);
338 + this.updateUi(this.sessionCtx);
288 - await worker().runPrompt(run.fullPrompt, sessionName(run));
289 - markRunDone(run);
341 + await this.worker().runPrompt(run.fullPrompt, sessionName(run));
342 + this.finishWorkerRun(run);
290 343 } catch (error) {
291 - failRun(run, errorMessage(error));
344 + this.failRun(run, errorMessage(error));
292 345 } finally {
293 - activeJob = false;
294 - activeRunId = undefined;
295 - touchRun(run);
296 - updateUi(sessionCtx);
297 - startNextRun();
346 + this.activeJob = false;
347 + this.activeRunId = undefined;
348 + this.touchRun(run);
349 + this.updateUi(this.sessionCtx);
350 + this.startNextRun();
301 - function worker(): PiRpcWorker {
354 + private failStaleRun(run: LlmiterateRun): void {
355 + this.failRun(run, "marker span changed before background agent start; skipped stale request");
356 + this.updateUi(this.sessionCtx);
357 + queueMicrotask(() => this.startNextRun());
360 + private finishWorkerRun(run: LlmiterateRun): void {
361 + if (this.isRunStillValid(run)) this.failRun(run, "marker still present after background agent finished");
362 + else this.markRunDone(run);
365 + private worker(): PiRpcWorker {
366 + const runtime = this.runtime;
302 367 if (!runtime) throw new Error("llmiterate runtime is not started");
303 - rpcWorker ??= new PiRpcWorker({
369 + this.rpcWorker ??= this.makeWorker({
304 370 cwd: runtime.root,
305 - sessionDir: path.join(runtime.storeDir, "sessions"),
306 - onEvent: handleRpcEvent,
371 + sessionDir: sessionDir(runtime),
372 + model: runtime.config.model,
373 + thinking: runtime.config.thinking,
374 + timeoutMs: runtime.config.timeoutMs,
375 + onEvent: (event) => this.handleRpcEvent(event),
308 - return rpcWorker;
377 + return this.rpcWorker;
311 - function stopWorker(): void {
312 - rpcWorker?.dispose();
313 - rpcWorker = undefined;
314 - activeJob = false;
315 - activeRunId = undefined;
380 + private stopWorker(): void {
381 + this.rpcWorker?.dispose();
382 + this.rpcWorker = undefined;
383 + this.activeJob = false;
384 + this.activeRunId = undefined;
318 - function handleRpcEvent(event: RpcEvent): void {
319 - const run = activeRun();
387 + private handleRpcEvent(event: RpcEvent): void {
388 + const run = this.activeRun();
320 389 if (!run) return;
322 391 switch (event.type) {
323 392 case "message_update":
324 393 case "message_end":
325 - if (event.message?.role === "assistant") updateAssistantText(run, event.message);
394 + if (event.message?.role === "assistant") this.updateAssistantText(run, event.message);
326 395 break;
327 396 case "tool_execution_start":
328 - updateToolText(run, `running ${toolName(event.toolName)}`);
397 + this.updateToolText(run, `running ${toolName(event.toolName)}`);
329 398 break;
330 - case "tool_execution_end": {
331 - const failed = event.isError === true;
332 - updateToolText(run, `${failed ? "error" : "done"} ${toolName(event.toolName)}`);
333 - if (failed) failRun(run, extractToolResultText(event.result));
399 + case "tool_execution_end":
400 + this.handleToolEnd(run, event);
334 401 break;
335 - }
336 402 case "agent_end":
337 - markRunDone(run);
338 403 break;
341 - updateUi(sessionCtx);
406 + this.updateUi(this.sessionCtx);
344 - function markRunRunning(run: LlmiterateRun): void {
345 - activeJob = true;
346 - activeRunId = run.id;
409 + private handleToolEnd(run: LlmiterateRun, event: Extract<RpcEvent, { type: "tool_execution_end" }>): void {
410 + const failed = event.isError === true;
411 + this.updateToolText(run, `${failed ? "error" : "done"} ${toolName(event.toolName)}`);
412 + if (failed) this.failRun(run, extractToolResultText(event.result));
415 + private markRunRunning(run: LlmiterateRun): void {
416 + this.activeJob = true;
417 + this.activeRunId = run.id;
347 418 run.status = "running";
348 419 run.toolText = "starting isolated RPC session";
349 420 run.assistantText = "";
350 - touchRun(run);
421 + this.setMarkerStatus(run, "running");
422 + this.touchRun(run);
353 - function markRunDone(run: LlmiterateRun): void {
425 + private markRunDone(run: LlmiterateRun): void {
354 426 if (run.status === "error") return;
355 427 run.status = "done";
356 - touchRun(run);
428 + this.setMarkerStatus(run, "done");
429 + this.maybeNotify("done", `llmiterate done ${run.projectFile}:${run.block.startLine}`);
430 + this.touchRun(run);
359 - function failRun(run: LlmiterateRun, error: string): void {
433 + private failRun(run: LlmiterateRun, error: string): void {
360 434 run.status = "error";
361 435 run.error = error || "background pi failed";
362 - touchRun(run);
436 + this.setMarkerStatus(run, "failed", run.error);
437 + this.maybeNotify("error", `llmiterate failed ${run.projectFile}:${run.block.startLine}: ${previewText(run.error, ERROR_PREVIEW_CHARS)}`);
438 + this.touchRun(run);
365 - function updateAssistantText(run: LlmiterateRun, message: RpcMessage): void {
441 + private setMarkerStatus(run: LlmiterateRun, status: MarkerRunState["status"], error?: string): void {
442 + const marker = this.runtime?.state.markers[run.block.key];
443 + if (!marker || !this.runtime) return;
445 + marker.status = status;
446 + marker.updatedAt = this.now();
447 + if (error) marker.lastError = error;
448 + else delete marker.lastError;
449 + this.persistState(this.runtime);
452 + private maybeNotify(kind: "queued" | "done" | "error", message: string): void {
453 + if (!this.sessionCtx?.hasUI || !this.runtime) return;
454 + if (!shouldNotify(this.runtime.config.notify, kind)) return;
455 + this.sessionCtx.ui.notify(message, kind === "error" ? "error" : "info");
458 + private updateAssistantText(run: LlmiterateRun, message: RpcMessage): void {
366 459 run.assistantText = extractMessageText(message);
367 - touchRun(run);
460 + this.touchRun(run);
370 - function updateToolText(run: LlmiterateRun, text: string): void {
463 + private updateToolText(run: LlmiterateRun, text: string): void {
371 464 run.toolText = text;
372 - touchRun(run);
465 + this.touchRun(run);
375 - function touchRun(run: LlmiterateRun): void {
376 - run.updatedAt = Date.now();
468 + private touchRun(run: LlmiterateRun): void {
469 + run.updatedAt = this.now();
379 - function isRunStillValid(run: LlmiterateRun): boolean {
472 + private isRunStillValid(run: LlmiterateRun): boolean {
473 + const runtime = this.runtime;
380 474 if (!runtime) return false;
381 476 const text = readUtf8(run.absoluteFile);
382 477 if (text === undefined) return false;
383 - return parseMarkerPrompts(run.projectFile, text, runtime.config.markers).some((block) =>
479 + return parseMarkerPrompts(run.projectFile, text, runtime.config.commentPrefixes).some((block) =>
384 480 block.startLine === run.block.startLine && block.promptHash === run.block.promptHash
388 - function activeRun(): LlmiterateRun | undefined {
389 - return runs.find((run) => run.id === activeRunId);
484 + private activeRun(): LlmiterateRun | undefined {
485 + return this.runs.find((run) => run.id === this.activeRunId);
392 - function updateUi(ctx: ExtensionContext | undefined): void {
393 - renderLlmiterateUi(ctx, panelVisible, runs, {
394 - config: runtime?.config,
395 - lockError: runtime?.lockError,
396 - watchErrors: runtime?.watcher?.errorCount ?? 0,
397 - activeRun: activeRun(),
398 - queuedRuns: queuedRunCount(),
488 + private updateUi(ctx: ExtensionContext | undefined): void {
489 + renderLlmiterateUi(ctx, this.panelVisible, this.runs, {
490 + config: this.runtime?.config,
491 + lockError: this.runtime?.lockError,
492 + watchErrors: this.runtime?.watcher?.errorCount ?? 0,
493 + watchDirs: this.runtime?.watcher?.watcherCount ?? 0,
494 + activeRun: this.activeRun(),
495 + queuedRuns: this.queuedRunCount(),
402 - function queuedRunCount(): number {
403 - return runs.filter((run) => run.status === "queued").length;
499 + private queuedRunCount(): number {
500 + return this.runs.filter((run) => run.status === "queued").length;
504 +function sessionDir(runtime: WatchRuntime): string {
505 + return path.join(runtime.storeDir, "sessions");
508 +function statFile(absPath: string): fs.Stats | undefined {
509 + try { return fs.statSync(absPath); } catch { return undefined; }
512 +function readUtf8(absPath: string): string | undefined {
513 + try { return fs.readFileSync(absPath, "utf-8"); } catch { return undefined; }
516 +function shouldNotify(policy: NotifyPolicy, kind: "queued" | "done" | "error"): boolean {
517 + if (policy === "off") return false;
518 + if (policy === "all") return true;
519 + if (policy === "done") return kind === "done" || kind === "error";
520 + return kind === "error";
407 523 function sessionName(run: LlmiterateRun): string {
408 524 return `llmiterate ${run.projectFile}:${run.block.startLine}`;

pi/agent/extensions/llmiterate/log.ts

Added
new file mode 100644
1 +import * as fs from "node:fs";
2 +import * as path from "node:path";
3 +import { spawnSync } from "node:child_process";
4 +import { previewText } from "./util";
6 +export interface RenderedLogTarget {
7 + sessionFile: string;
8 + markdownFile: string;
9 +}
11 +export function latestSessionFile(sessionDir: string): string | undefined {
12 + const files: string[] = [];
13 + walk(sessionDir, (file) => {
14 + if (file.endsWith(".jsonl")) files.push(file);
15 + });
16 + return files.sort((a, b) => mtimeMs(b) - mtimeMs(a))[0];
19 +export function renderLatestSessionLog(sessionDir: string, outDir: string): RenderedLogTarget | undefined {
20 + const sessionFile = latestSessionFile(sessionDir);
21 + if (!sessionFile) return undefined;
23 + fs.mkdirSync(outDir, { recursive: true });
24 + const markdownFile = path.join(outDir, "latest.md");
25 + fs.writeFileSync(markdownFile, renderSessionLogMarkdown(sessionFile), "utf-8");
26 + return { sessionFile, markdownFile };
29 +export function renderSessionLogMarkdown(sessionFile: string): string {
30 + const lines = fs.readFileSync(sessionFile, "utf-8").split(/\r?\n/).filter(Boolean);
31 + const out = [
32 + "# llmiterate log",
33 + "",
34 + `Session: ${sessionFile}`,
35 + "",
36 + ];
38 + for (const line of lines) {
39 + let entry: unknown;
40 + try { entry = JSON.parse(line); } catch { continue; }
41 + const rendered = renderEntry(entry);
42 + if (rendered) out.push(rendered, "");
43 + }
45 + return out.join("\n").trimEnd() + "\n";
48 +export interface EditorCommand {
49 + command: string;
50 + args: string[];
53 +export function openInEditor(file: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
54 + const editor = parseEditorCommand(env.VISUAL || env.EDITOR || "");
55 + if (!editor) return "VISUAL/EDITOR not set";
57 + const result = spawnSync(editor.command, [...editor.args, file], { stdio: "inherit" });
58 + if (result.error) return result.error.message;
59 + if (typeof result.status === "number" && result.status !== 0) return `${editor.command} exited with ${result.status}`;
60 + return undefined;
63 +export function parseEditorCommand(input: string): EditorCommand | undefined {
64 + const args = shellWords(input);
65 + const command = args.shift();
66 + return command ? { command, args } : undefined;
69 +function renderEntry(entry: unknown): string | undefined {
70 + if (!isObject(entry)) return undefined;
71 + const message = isObject(entry.message) ? entry.message : entry;
72 + const role = typeof message.role === "string" ? message.role : undefined;
73 + const text = contentText(message.content);
75 + if (role && text) return `## ${title(role)}\n\n${fence(text)}`;
76 + if (typeof entry.type === "string" && entry.type.includes("tool")) {
77 + return `## ${entry.type}\n\n${fence(previewText(JSON.stringify(entry, null, 2), 4000))}`;
78 + }
79 + return undefined;
82 +function contentText(content: unknown): string {
83 + if (typeof content === "string") return content.trim();
84 + if (!Array.isArray(content)) return "";
85 + return content.map((part) => {
86 + if (!isObject(part)) return "";
87 + if (typeof part.text === "string") return part.text;
88 + if (typeof part.content === "string") return part.content;
89 + return "";
90 + }).filter(Boolean).join("\n").trim();
93 +function title(role: string): string {
94 + return role.slice(0, 1).toUpperCase() + role.slice(1);
97 +function fence(text: string): string {
98 + return `\`\`\`text\n${text}\n\`\`\``;
101 +function walk(dir: string, onFile: (file: string) => void): void {
102 + let entries: fs.Dirent[];
103 + try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
104 + for (const entry of entries) {
105 + const file = path.join(dir, entry.name);
106 + if (entry.isDirectory()) walk(file, onFile);
107 + else if (entry.isFile()) onFile(file);
111 +function mtimeMs(file: string): number {
112 + try { return fs.statSync(file).mtimeMs; } catch { return 0; }
115 +function shellWords(input: string): string[] {
116 + const words: string[] = [];
117 + let current = "";
118 + let quote: "'" | '"' | undefined;
119 + let escaped = false;
121 + for (const char of input.trim()) {
122 + if (escaped) {
123 + current += char;
124 + escaped = false;
125 + continue;
127 + if (char === "\\") {
128 + escaped = true;
129 + continue;
131 + if (quote) {
132 + if (char === quote) quote = undefined;
133 + else current += char;
134 + continue;
136 + if (char === "'" || char === '"') {
137 + quote = char;
138 + continue;
140 + if (/\s/.test(char)) {
141 + if (current) words.push(current);
142 + current = "";
143 + continue;
145 + current += char;
148 + if (current) words.push(current);
149 + return words;
152 +function isObject(value: unknown): value is Record<string, unknown> {
153 + return typeof value === "object" && value !== null && !Array.isArray(value);

pi/agent/extensions/llmiterate/package.json

Modified
6 6 "scripts": {
7 7 "test": "bun test ./__tests__/*.test.ts"
9 + "dependencies": {
10 + "ignore": "^7.0.5"
11 + },
9 12 "peerDependencies": {
10 13 "@earendil-works/pi-coding-agent": "*",
11 14 "@earendil-works/pi-tui": "*"

pi/agent/extensions/llmiterate/parser.ts

Added
new file mode 100644
1 +import { BUILTIN_COMMENT_PREFIXES, DISABLE_MARKER, MARKER } from "./constants";
3 +export interface MarkerPrompt {
4 + marker: typeof MARKER;
5 + file: string;
6 + startLine: number;
7 + endLine: number;
8 + prompt: string;
9 + key: string;
10 + promptHash: string;
13 +const commentPrefixGroupCache = new Map<string, Map<string, string[]>>();
15 +export function parseMarkerPrompts(file: string, text: string, commentPrefixes = BUILTIN_COMMENT_PREFIXES): MarkerPrompt[] {
16 + if (!text.includes("llmiterate")) return [];
17 + if (isLlmiterateDisabled(text, commentPrefixes)) return [];
19 + const prefixes = normalizeCommentPrefixes(commentPrefixes);
20 + const lines = normalizeLines(text);
21 + const prompts: MarkerPrompt[] = [];
23 + for (let i = 0; i < lines.length; i++) {
24 + const first = parsePromptLine(lines[i] ?? "", prefixes);
25 + if (!first) continue;
27 + const startLine = i + 1;
28 + const body = [first];
29 + let endLine = startLine;
31 + for (let j = i + 1; j < lines.length; j++) {
32 + const next = parsePromptLine(lines[j] ?? "", prefixes);
33 + if (!next) break;
34 + body.push(next);
35 + endLine = j + 1;
36 + i = j;
37 + }
39 + const prompt = body.join("\n").trim();
40 + if (prompt) prompts.push(makePrompt(file, startLine, endLine, prompt));
41 + }
43 + return prompts;
46 +export function isLlmiterateDisabled(text: string, commentPrefixes = BUILTIN_COMMENT_PREFIXES): boolean {
47 + if (!text.includes(DISABLE_MARKER)) return false;
48 + const prefixes = normalizeCommentPrefixes(commentPrefixes);
49 + return normalizeLines(text).some((line) => {
50 + const stripped = stripCommentPrefix(line, prefixes);
51 + return stripped !== undefined && /^!llmiterate(?:\s|$)/.test(stripped);
52 + });
55 +function parsePromptLine(line: string, prefixes: string[]): string | undefined {
56 + const stripped = stripCommentPrefix(line, prefixes);
57 + if (stripped === undefined || !stripped.startsWith(MARKER)) return undefined;
58 + const prompt = stripped.slice(MARKER.length).trim();
59 + return prompt || undefined;
62 +function stripCommentPrefix(line: string, prefixes: string[]): string | undefined {
63 + const trimmed = line.trimStart();
64 + const candidates = commentPrefixGroups(prefixes).get(trimmed[0] ?? "");
65 + if (!candidates) return undefined;
66 + for (const prefix of candidates) {
67 + if (!startsWithCommentPrefix(trimmed, prefix)) continue;
68 + const suffix = commentSuffix(prefix);
69 + let body = trimmed.slice(prefix.length).trimStart();
70 + if (suffix && body.endsWith(suffix)) body = body.slice(0, -suffix.length).trimEnd();
71 + return body;
72 + }
73 + return undefined;
76 +function startsWithCommentPrefix(line: string, prefix: string): boolean {
77 + if (!line.startsWith(prefix)) return false;
78 + if (/^[a-z]+$/i.test(prefix)) {
79 + const next = line[prefix.length];
80 + return next === undefined || /\s/.test(next);
81 + }
82 + return true;
85 +function commentPrefixGroups(prefixes: string[]): Map<string, string[]> {
86 + const key = prefixes.join("\0");
87 + const cached = commentPrefixGroupCache.get(key);
88 + if (cached) return cached;
89 + const groups = new Map<string, string[]>();
90 + for (const prefix of prefixes) {
91 + const key = prefix[0] ?? "";
92 + const group = groups.get(key) ?? [];
93 + group.push(prefix);
94 + groups.set(key, group);
95 + }
96 + commentPrefixGroupCache.set(key, groups);
97 + return groups;
100 +function commentSuffix(prefix: string): string | undefined {
101 + if (prefix === "<!--") return "-->";
102 + if (prefix === "/*" || prefix === "/**") return "*/";
103 + return undefined;
106 +function normalizeLines(text: string): string[] {
107 + return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
110 +function makePrompt(file: string, startLine: number, endLine: number, prompt: string): MarkerPrompt {
111 + const promptHash = hashString(prompt);
112 + return {
113 + marker: MARKER,
114 + file,
115 + startLine,
116 + endLine,
117 + prompt,
118 + promptHash,
119 + key: `${file}:${startLine}:${promptHash}`,
120 + };
123 +function hashString(input: string): string {
124 + let hash = 0x811c9dc5;
125 + for (let i = 0; i < input.length; i++) {
126 + hash ^= input.charCodeAt(i);
127 + hash = Math.imul(hash, 0x01000193);
129 + return (hash >>> 0).toString(16).padStart(8, "0");
132 +function normalizeCommentPrefixes(prefixes: string[]): string[] {
133 + return [...new Set(prefixes.map((p) => p.trim()).filter(Boolean))].sort((a, b) => b.length - a.length);

pi/agent/extensions/llmiterate/path-filter.ts

Added
new file mode 100644
1 +import * as os from "node:os";
2 +import * as path from "node:path";
3 +import { createHash } from "node:crypto";
4 +import { APP_STATE_DIR, STORE_NAMESPACE } from "./constants";
5 +import type { LlmiterateConfig } from "./config";
6 +import { toSlash } from "./util";
8 +const REGEX_CHARS = /[|\\{}()[\]^$+?.]/;
10 +export type CompiledGlobSegment = "**" | RegExp;
12 +export interface CompiledPathFilter {
13 + include: RegExp[];
14 + includeDirPatterns: CompiledGlobSegment[][];
15 + exclude: RegExp[];
16 + excludeRootDirs: Set<string>;
17 + excludePrefixes: string[];
20 +export function projectStoreDir(root: string): string {
21 + return path.join(platformStateDir(), STORE_NAMESPACE, hashProjectRoot(root));
24 +export function platformStateDir(
25 + platform: NodeJS.Platform = process.platform,
26 + env: NodeJS.ProcessEnv = process.env,
27 + home = os.homedir(),
28 +): string {
29 + const paths = platform === "win32" ? path.win32 : path.posix;
31 + if (platform === "win32") {
32 + return paths.join(env.LOCALAPPDATA ?? paths.join(home, "AppData", "Local"), APP_STATE_DIR);
33 + }
35 + if (env.XDG_STATE_HOME) return paths.join(env.XDG_STATE_HOME, APP_STATE_DIR);
36 + if (platform === "darwin") return paths.join(home, "Library", "Application Support", APP_STATE_DIR);
37 + return paths.join(home, ".local", "state", APP_STATE_DIR);
40 +export function hashProjectRoot(root: string): string {
41 + return createHash("sha256").update(root).digest("hex");
44 +export function compilePathFilter(config: Pick<LlmiterateConfig, "include" | "exclude">): CompiledPathFilter {
45 + const includeDirPatterns = config.include.map(compileGlobSegments);
46 + const excludeRootDirs = new Set<string>();
47 + const excludePrefixes: string[] = [];
48 + const exclude: RegExp[] = [];
50 + for (const glob of config.exclude) {
51 + const prefix = simpleGlobstarPrefix(glob);
52 + if (!prefix) {
53 + exclude.push(globToRegExp(glob));
54 + continue;
55 + }
57 + const rootDir = rootDirPrefix(prefix);
58 + if (rootDir) excludeRootDirs.add(rootDir);
59 + else excludePrefixes.push(prefix);
60 + }
62 + return { include: config.include.map(globToRegExp), includeDirPatterns, exclude, excludeRootDirs, excludePrefixes };
65 +export function shouldIncludePath(relPath: string, config: Pick<LlmiterateConfig, "include" | "exclude"> | CompiledPathFilter): boolean {
66 + const filter = isCompiledPathFilter(config) ? config : compilePathFilter(config);
67 + return shouldIncludeCompiledPath(relPath, filter);
70 +export function shouldIncludeCompiledPath(relPath: string, filter: CompiledPathFilter): boolean {
71 + const rel = toSlash(relPath);
72 + if (isExcludedPath(rel, filter)) return false;
73 + return filter.include.some((pattern) => pattern.test(rel));
76 +export function isExcludedPath(relPath: string, filter: CompiledPathFilter): boolean {
77 + const rel = toSlash(relPath);
78 + return filter.excludeRootDirs.has(firstPathSegment(rel))
79 + || filter.excludePrefixes.some((prefix) => rel.startsWith(prefix))
80 + || filter.exclude.some((pattern) => pattern.test(rel));
83 +export function shouldWatchDirectory(relPath: string, filter: CompiledPathFilter): boolean {
84 + const rel = toSlash(relPath);
85 + if (rel && (isExcludedPath(rel, filter) || isExcludedPath(`${rel}/`, filter))) return false;
86 + const segments = rel ? rel.split("/") : [];
87 + return filter.includeDirPatterns.some((include) => includeCanMatchUnderDir(include, segments));
90 +export function globToRegExp(pattern: string): RegExp {
91 + const glob = toSlash(pattern);
92 + let s = "^";
93 + for (let i = 0; i < glob.length;) {
94 + const c = glob[i];
95 + if (c === "*") {
96 + if (glob[i + 1] === "*") {
97 + i += 2;
98 + if (glob[i] === "/") {
99 + i++;
100 + s += "(?:.*/)?";
101 + } else {
102 + s += ".*";
104 + continue;
106 + s += "[^/]*";
107 + i++;
108 + continue;
110 + if (c === "?") {
111 + s += "[^/]";
112 + i++;
113 + continue;
115 + if (c === "{") {
116 + const end = glob.indexOf("}", i + 1);
117 + if (end !== -1) {
118 + const parts = glob.slice(i + 1, end).split(",").map((p) => p.trim()).filter(Boolean).map(escapeRegExp);
119 + if (parts.length) {
120 + s += `(?:${parts.join("|")})`;
121 + i = end + 1;
122 + continue;
126 + s += REGEX_CHARS.test(c) ? `\\${c}` : c;
127 + i++;
129 + return new RegExp(`${s}$`);
132 +function includeCanMatchUnderDir(pattern: CompiledGlobSegment[], dir: string[]): boolean {
133 + const memo = new Map<string, boolean>();
134 + const visit = (patternIndex: number, dirIndex: number): boolean => {
135 + const key = `${patternIndex}:${dirIndex}`;
136 + const cached = memo.get(key);
137 + if (cached !== undefined) return cached;
139 + let result: boolean;
140 + if (dirIndex >= dir.length) {
141 + result = patternIndex < pattern.length;
142 + } else if (patternIndex >= pattern.length) {
143 + result = false;
144 + } else {
145 + const segment = pattern[patternIndex]!;
146 + result = segment === "**"
147 + ? visit(patternIndex + 1, dirIndex) || visit(patternIndex, dirIndex + 1)
148 + : segment.test(dir[dirIndex]!) && visit(patternIndex + 1, dirIndex + 1);
151 + memo.set(key, result);
152 + return result;
153 + };
154 + return visit(0, 0);
157 +function compileGlobSegments(pattern: string): CompiledGlobSegment[] {
158 + return toSlash(pattern).split("/").filter(Boolean).map((segment) => segment === "**" ? "**" : globToRegExp(segment));
161 +function simpleGlobstarPrefix(glob: string): string | undefined {
162 + const normalized = toSlash(glob);
163 + if (!normalized.endsWith("/**")) return undefined;
164 + const prefix = normalized.slice(0, -2);
165 + return /[*?{[]/.test(prefix) ? undefined : prefix;
168 +function rootDirPrefix(prefix: string): string | undefined {
169 + const dir = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
170 + return dir && !dir.includes("/") ? dir : undefined;
173 +function firstPathSegment(path: string): string {
174 + const slash = path.indexOf("/");
175 + return slash === -1 ? path : path.slice(0, slash);
178 +function escapeRegExp(s: string): string {
179 + return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
182 +function isCompiledPathFilter(value: Pick<LlmiterateConfig, "include" | "exclude"> | CompiledPathFilter): value is CompiledPathFilter {
183 + return "includeDirPatterns" in value;

pi/agent/extensions/llmiterate/prompt.ts

Added
new file mode 100644
1 +import type { MarkerPrompt } from "./parser";
3 +export function buildAgentPrompt(block: MarkerPrompt): string {
4 + return [
5 + `llmiterate request from @${block.file}:${block.startLine}`,
6 + "",
7 + "Prompt marker contents:",
8 + "```text",
9 + block.prompt,
10 + "```",
11 + "",
12 + "Instructions:",
13 + `- Work in/around @${block.file}.`,
14 + `- Marker span to replace: ${block.file}:${block.startLine}-${block.endLine}.`,
15 + "- Treat the marker comment line(s) as an inline prompt/TODO, not program code.",
16 + "- Replace the whole marker span with the requested implementation or code change.",
17 + "- Do not leave the marker line(s) behind unless impossible; explain if impossible.",
18 + ].join("\n");

pi/agent/extensions/llmiterate/rpc.ts

Modified
4 4 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
5 5 import * as fs from "node:fs";
6 6 import * as path from "node:path";
7 7 import type { RpcEvent } from "./types";
9 9 const RPC_KILL_GRACE_MS = 5_000;
10 +export const LLMITERATE_WORKER_ENV = "LLMITERATE_WORKER";
11 +export const WORKER_SYSTEM_PROMPT = [
12 + "You are llmiterate, a background Pi worker launched from a file-save marker.",
13 + "Fulfill only the marker request.",
14 + "Edit files directly with tools.",
15 + "Do not ask for confirmation.",
16 + "Keep assistant text concise; source edits are the primary output.",
17 +].join("\n");
10 18 const RESPONSE_EVENT = "response";
11 19 const AGENT_END_EVENT = "agent_end";
12 20 const CMD_NEW_SESSION = "new_session";
45 53 sessionDir: string;
46 54 onEvent(event: RpcEvent): void;
47 55 invocation?: PiInvocation;
56 + model?: string;
57 + thinking?: string;
58 + timeoutMs?: number;
59 + appendSystemPrompt?: string;
60 + offline?: boolean;
61 + env?: NodeJS.ProcessEnv;
50 64 export class PiRpcWorker {
70 84 this.currentPrompt = { resolve, reject };
72 86 await this.command({ type: CMD_PROMPT, message: prompt });
73 - await done;
87 + await withTimeout(done, this.options.timeoutMs, () => {
88 + this.abort();
89 + return new Error(`RPC worker timed out after ${this.options.timeoutMs}ms`);
90 + });
74 91 } finally {
75 92 this.runningPrompt = false;
76 93 this.currentPrompt = undefined;
100 117 if (this.proc && !this.proc.killed) return;
102 119 fs.mkdirSync(this.options.sessionDir, { recursive: true });
103 - const invocation = this.options.invocation ?? getPiInvocation([
104 - "--mode", "rpc",
105 - "--no-extensions",
106 - "--session-dir", this.options.sessionDir,
107 - ]);
120 + const invocation = this.options.invocation ?? getPiInvocation(workerArgs(this.options));
109 122 this.stderr = "";
110 123 this.proc = spawn(invocation.command, invocation.args, {
111 124 cwd: this.options.cwd,
125 + env: { ...process.env, ...this.options.env, [LLMITERATE_WORKER_ENV]: "1" },
112 126 shell: false,
113 127 stdio: ["pipe", "pipe", "pipe"],
215 229 return typeof value === "object" && value !== null && !Array.isArray(value);
232 +function withTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, makeError: () => Error): Promise<T> {
233 + if (!timeoutMs) return promise;
234 + return new Promise((resolve, reject) => {
235 + const timer = setTimeout(() => reject(makeError()), timeoutMs);
236 + promise.then(
237 + (value) => {
238 + clearTimeout(timer);
239 + resolve(value);
240 + },
241 + (error) => {
242 + clearTimeout(timer);
243 + reject(error);
244 + },
245 + );
246 + });
249 +export function workerArgs(options: Pick<RpcWorkerOptions, "sessionDir" | "model" | "thinking" | "appendSystemPrompt" | "offline">): string[] {
250 + const args = ["--mode", "rpc"];
251 + if (options.offline !== false) args.push("--offline");
252 + args.push("--session-dir", options.sessionDir);
253 + args.push("--append-system-prompt", options.appendSystemPrompt ?? WORKER_SYSTEM_PROMPT);
254 + if (options.model) args.push("--model", options.model);
255 + if (options.thinking) args.push("--thinking", options.thinking);
256 + return args;
218 259 function getPiInvocation(args: string[]): PiInvocation {
219 260 const currentScript = process.argv[1];
220 261 const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");

pi/agent/extensions/llmiterate/state.ts

Added
new file mode 100644
1 +import * as fs from "node:fs";
2 +import * as path from "node:path";
3 +import { STATE_FILE } from "./constants";
4 +import { isObject } from "./util";
6 +export type MarkerRunStatus = "queued" | "running" | "done" | "failed";
8 +export interface MarkerRunState {
9 + file: string;
10 + startLine: number;
11 + endLine: number;
12 + promptHash: string;
13 + promptPreview: string;
14 + status: MarkerRunStatus;
15 + attempts: number;
16 + queuedAt: number;
17 + updatedAt: number;
18 + lastError?: string;
21 +export interface LlmiterateState {
22 + version: 1;
23 + markers: Record<string, MarkerRunState>;
26 +export function loadState(storeDir: string): LlmiterateState {
27 + try {
28 + const parsed = JSON.parse(fs.readFileSync(path.join(storeDir, STATE_FILE), "utf-8"));
29 + if (!isObject(parsed) || parsed.version !== 1 || !isObject(parsed.markers)) return emptyState();
30 + return { version: 1, markers: resetInflightMarkers(parseMarkerRunStates(parsed.markers)) };
31 + } catch {
32 + return emptyState();
33 + }
36 +export function saveState(storeDir: string, state: LlmiterateState): void {
37 + fs.mkdirSync(storeDir, { recursive: true });
38 + fs.writeFileSync(path.join(storeDir, STATE_FILE), JSON.stringify(state, null, 2) + "\n", "utf-8");
41 +export function emptyState(): LlmiterateState {
42 + return { version: 1, markers: {} };
45 +function resetInflightMarkers(markers: Record<string, MarkerRunState>): Record<string, MarkerRunState> {
46 + const now = Date.now();
47 + for (const marker of Object.values(markers)) {
48 + if (marker.status === "queued" || marker.status === "running") {
49 + marker.status = "failed";
50 + marker.lastError = "pi stopped before marker finished";
51 + marker.updatedAt = now;
52 + }
53 + }
54 + return markers;
57 +function parseMarkerRunStates(raw: Record<string, unknown>): Record<string, MarkerRunState> {
58 + const markers: Record<string, MarkerRunState> = {};
59 + for (const [key, value] of Object.entries(raw)) {
60 + if (isMarkerRunState(value)) markers[key] = value;
61 + }
62 + return markers;
65 +function isMarkerRunState(value: unknown): value is MarkerRunState {
66 + if (!isObject(value)) return false;
67 + return typeof value.file === "string"
68 + && typeof value.startLine === "number"
69 + && typeof value.endLine === "number"
70 + && typeof value.promptHash === "string"
71 + && typeof value.promptPreview === "string"
72 + && isMarkerRunStatus(value.status)
73 + && typeof value.attempts === "number"
74 + && typeof value.queuedAt === "number"
75 + && typeof value.updatedAt === "number"
76 + && (value.lastError === undefined || typeof value.lastError === "string");
79 +function isMarkerRunStatus(value: unknown): value is MarkerRunStatus {
80 + return value === "queued" || value === "running" || value === "done" || value === "failed";

pi/agent/extensions/llmiterate/types.ts

Modified
20 20 config?: LlmiterateConfig;
21 21 lockError?: string;
22 22 watchErrors: number;
23 + watchDirs: number;
23 24 activeRun?: LlmiterateRun;
24 25 queuedRuns: number;

pi/agent/extensions/llmiterate/ui.ts

Modified
1 1 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2 2 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
3 3 import type { Component } from "@earendil-works/pi-tui";
4 -import { previewText } from "./core";
4 +import { previewText } from "./util";
5 5 import type { LlmiterateRun, RunStatus, UiState } from "./types";
7 7 const STATUS_KEY = "llmiterate";
32 32 function statusLine(ctx: ExtensionContext, state: UiState): string {
33 33 const theme = ctx.ui.theme;
34 34 if (!state.config?.enabled) return theme.fg("dim", "llmiterate off");
35 + if (state.config.include.length === 0) return theme.fg("dim", "llmiterate watching nothing");
35 36 if (state.lockError) return theme.fg("dim", "llmiterate standby");
36 37 if (state.watchErrors > 0) return theme.fg("warning", `llmiterate ${state.watchErrors} watch error(s)`);
37 38 if (state.activeRun) return theme.fg("accent", `llmiterate ${state.activeRun.status} ${state.activeRun.block.file}:${state.activeRun.block.startLine}`);
61 62 invalidate(): void {}
63 64 private runLines(inner: number): string[] {
64 - if (this.runs.length === 0) return [this.line(this.theme.fg("dim", "no prompts queued yet"), inner)];
65 + if (this.runs.length === 0) return [this.line(this.theme.fg("dim", "no prompts queued yet; /llmiterate log opens latest transcript"), inner)];
66 67 const lines: string[] = [];
67 68 for (const run of this.runs.slice(0, WIDGET_RUN_LIMIT)) {

pi/agent/extensions/llmiterate/util.ts

Added
new file mode 100644
1 +export function toSlash(s: string): string {
2 + return s.includes("\\") ? s.replace(/\\/g, "/") : s;
3 +}
5 +export function previewText(text: string, maxChars: number): string {
6 + const oneLine = text.replace(/\s+/g, " ").trim();
7 + return oneLine.length > maxChars ? `${oneLine.slice(0, Math.max(0, maxChars - 1))}…` : oneLine;
8 +}
10 +export function isObject(value: unknown): value is Record<string, unknown> {
11 + return typeof value === "object" && value !== null && !Array.isArray(value);
14 +export function stringArray(value: unknown, fallback: string[]): string[] {
15 + return Array.isArray(value) && value.every((v) => typeof v === "string" && v.trim())
16 + ? value.map((v) => v.trim())
17 + : [...fallback];
20 +export function positiveInt(value: unknown, fallback: number): number {
21 + return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;

pi/agent/extensions/llmiterate/watcher.ts

Modified
1 1 import * as fs from "node:fs";
2 2 import * as path from "node:path";
3 -import {
4 - shouldIncludeCompiledPath,
5 - shouldWatchDirectory,
6 - toSlash,
7 - type CompiledPathFilter,
8 - type LlmiterateConfig,
9 -} from "./core";
3 +import ignore, { type Ignore } from "ignore";
4 +import { type LlmiterateConfig } from "./config";
5 +import { shouldIncludeCompiledPath, shouldWatchDirectory, type CompiledPathFilter } from "./path-filter";
6 +import { toSlash } from "./util";
11 8 const DIRECTORY_REFRESH_MS = 250;
9 +const IGNORE_FILE_NAMES = new Set([".gitignore", ".ignore"]);
13 11 type FileHandler = (absolutePath: string) => void;
14 12 type ErrorHandler = () => void;
14 +interface RefreshOptions {
15 + scheduleFiles: boolean;
16 + fileMtimeSinceMs?: number;
19 +interface IgnoreContext {
20 + matcher: Ignore;
21 + stamp: string;
16 24 export class ProjectWatcher {
17 25 private readonly watchers = new Map<string, fs.FSWatcher>();
18 26 private readonly fileTimers = new Map<string, ReturnType<typeof setTimeout>>();
19 27 private readonly dirTimers = new Map<string, ReturnType<typeof setTimeout>>();
28 + private readonly ignoreContexts = new Map<string, IgnoreContext>();
29 + private watchLimitHit = false;
21 31 public errorCount = 0;
33 + get watcherCount(): number {
34 + return this.watchers.size;
35 + }
23 37 constructor(
24 38 private readonly root: string,
25 39 private readonly config: LlmiterateConfig,
32 46 if (!shouldWatchDirectory("", this.pathFilter)) return;
34 48 const root = path.resolve(this.root);
35 - this.watchTree(root);
49 + const startedAt = Date.now();
50 + this.watchTree(root, { scheduleFiles: false });
36 51 // fs.watch can miss changes made immediately after watcher creation.
37 - // One delayed reconciliation makes startup deterministic without polling.
38 - this.scheduleDirectoryRefresh(root);
52 + // Reconcile watched dirs once, but only queue files modified after start.
53 + this.scheduleWatchedTreeRefresh(root, { scheduleFiles: true, fileMtimeSinceMs: startedAt });
41 56 stop(): void {
45 60 this.fileTimers.clear();
46 61 this.dirTimers.clear();
47 62 this.watchers.clear();
63 + this.ignoreContexts.clear();
50 66 scanAll(onFile: (absolutePath: string) => number): number {
53 69 return total;
56 - private watchTree(dir: string): void {
72 + private watchTree(dir: string, options: RefreshOptions): void {
57 73 const abs = path.resolve(dir);
58 74 if (this.watchers.has(abs)) return;
76 + if (!this.reserveWatchSlot()) return;
60 78 try {
61 79 const watcher = fs.watch(abs, { persistent: false }, (eventType, filename) => {
62 80 if (!filename) {
63 - this.scheduleDirectoryRefresh(abs);
81 + this.scheduleWatchedTreeRefresh(abs, { scheduleFiles: true }, true);
64 82 return;
67 - this.handlePathEvent(path.join(abs, filename.toString()));
68 - if (eventType === "rename") this.scheduleDirectoryRefresh(abs);
85 + const child = path.join(abs, filename.toString());
86 + if (IGNORE_FILE_NAMES.has(path.basename(child))) {
87 + this.scheduleWatchedTreeRefresh(abs, { scheduleFiles: false }, true);
88 + return;
89 + }
91 + this.handlePathEvent(child);
92 + if (eventType === "rename") this.scheduleDirectoryRefresh(abs, { scheduleFiles: true }, true);
70 94 watcher.on("error", () => {
71 95 this.recordError();
75 99 this.watchers.set(abs, watcher);
76 100 } catch {
77 101 this.recordError();
78 - // fs.watch is not equally reliable across platforms/runtimes. Still scan
79 - // the directory once so startup/reconciliation catches already-written files.
80 - this.refreshDirectory(abs);
102 + this.refreshDirectory(abs, options);
81 103 return;
84 - this.refreshDirectory(abs);
106 + this.refreshDirectory(abs, options);
87 109 private handlePathEvent(absPath: string): void {
89 111 try { stat = fs.statSync(absPath); } catch { return; }
91 113 if (stat.isDirectory()) {
92 - if (this.shouldWatchDir(absPath)) this.watchTree(absPath);
114 + if (this.shouldWatchDir(absPath)) this.watchTree(absPath, { scheduleFiles: true });
93 115 return;
96 118 if (stat.isFile()) this.scheduleFile(absPath);
99 - private refreshDirectory(abs: string): void {
121 + private refreshDirectory(abs: string, options: RefreshOptions): void {
122 + this.loadIgnoreContext(abs);
100 124 let entries: fs.Dirent[];
101 125 try { entries = fs.readdirSync(abs, { withFileTypes: true }); } catch { return; }
104 128 const child = path.join(abs, entry.name);
105 129 const rel = this.projectRel(child);
106 130 if (entry.isDirectory()) {
107 - if (!shouldWatchDirectory(rel, this.pathFilter)) continue;
108 - this.watchTree(child);
131 + if (this.isIgnored(rel, true) || !shouldWatchDirectory(rel, this.pathFilter)) continue;
132 + this.watchTree(child, options);
109 133 continue;
111 - if (entry.isFile() && shouldIncludeCompiledPath(rel, this.pathFilter)) this.scheduleFile(child);
135 + if (entry.isFile() && options.scheduleFiles && !this.isIgnored(rel, false) && shouldIncludeCompiledPath(rel, this.pathFilter) && this.isFreshEnough(child, options)) {
136 + this.scheduleFile(child);
115 - private scheduleDirectoryRefresh(abs: string): void {
141 + private scheduleDirectoryRefresh(abs: string, options: RefreshOptions, reloadIgnores = false): void {
116 142 const existing = this.dirTimers.get(abs);
117 143 if (existing) clearTimeout(existing);
118 144 this.dirTimers.set(abs, setTimeout(() => {
119 145 this.dirTimers.delete(abs);
120 - this.reconcileWatchers();
121 - this.refreshDirectory(abs);
146 + if (reloadIgnores) this.invalidateIgnoreContextsUnder(abs);
147 + this.reconcileWatchersUnder(abs);
148 + this.refreshDirectory(abs, options);
122 149 }, DIRECTORY_REFRESH_MS));
125 - private reconcileWatchers(): void {
126 - for (const dir of this.watchers.keys()) {
127 - if (!fs.existsSync(dir)) this.unwatchTree(dir);
152 + private scheduleWatchedTreeRefresh(abs: string, options: RefreshOptions, reloadIgnores = false): void {
153 + const existing = this.dirTimers.get(abs);
154 + if (existing) clearTimeout(existing);
155 + this.dirTimers.set(abs, setTimeout(() => {
156 + this.dirTimers.delete(abs);
157 + if (reloadIgnores) this.invalidateIgnoreContextsUnder(abs);
158 + this.reconcileWatchersUnder(abs);
159 + for (const dir of [...this.watchers.keys()]) {
160 + if (dir === abs || isDescendant(abs, dir)) this.refreshDirectory(dir, options);
162 + }, DIRECTORY_REFRESH_MS));
165 + private reconcileWatchersUnder(abs: string): void {
166 + for (const dir of [...this.watchers.keys()]) {
167 + if (dir !== abs && !isDescendant(abs, dir)) continue;
168 + const rel = this.projectRel(dir);
169 + if (!fs.existsSync(dir) || (rel && this.isIgnored(rel, true))) this.unwatchTree(dir);
131 173 private unwatchTree(abs: string): void {
132 - const watcher = this.watchers.get(abs);
133 - this.watchers.delete(abs);
134 - try { watcher?.close(); } catch {}
136 - for (const dir of [...this.watchers.keys()]) {
137 - if (isDescendant(abs, dir)) this.unwatchTree(dir);
174 + const dirs = [abs, ...[...this.watchers.keys()].filter((dir) => isDescendant(abs, dir))]
175 + .sort((a, b) => b.length - a.length);
176 + for (const dir of dirs) {
177 + const watcher = this.watchers.get(dir);
178 + this.watchers.delete(dir);
179 + this.ignoreContexts.delete(this.projectRel(dir));
180 + try { watcher?.close(); } catch {}
184 + private reserveWatchSlot(): boolean {
185 + if (this.watchers.size < this.config.maxWatchDirs) return true;
186 + if (!this.watchLimitHit) {
187 + this.watchLimitHit = true;
188 + this.recordError();
190 + return false;
193 + private isFreshEnough(absPath: string, options: RefreshOptions): boolean {
194 + if (options.fileMtimeSinceMs === undefined) return true;
195 + try { return fs.statSync(absPath).mtimeMs >= options.fileMtimeSinceMs; } catch { return false; }
141 198 private scheduleFile(absPath: string): void {
142 199 const rel = this.projectRel(absPath);
143 - if (!isSafeProjectRel(rel) || !shouldIncludeCompiledPath(rel, this.pathFilter)) return;
200 + if (!isSafeProjectRel(rel) || this.isIgnored(rel, false) || !shouldIncludeCompiledPath(rel, this.pathFilter)) return;
145 202 const existing = this.fileTimers.get(rel);
146 203 if (existing) clearTimeout(existing);
153 210 private walkFiles(dir: string, onFile: FileHandler): void {
211 + this.loadIgnoreContext(dir);
154 213 let entries: fs.Dirent[];
155 214 try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
158 217 const abs = path.join(dir, entry.name);
159 218 const rel = this.projectRel(abs);
160 219 if (entry.isDirectory()) {
161 - if (!shouldWatchDirectory(rel, this.pathFilter)) continue;
220 + if (this.isIgnored(rel, true) || !shouldWatchDirectory(rel, this.pathFilter)) continue;
162 221 this.walkFiles(abs, onFile);
163 222 continue;
165 - if (entry.isFile() && shouldIncludeCompiledPath(rel, this.pathFilter)) onFile(abs);
224 + if (entry.isFile() && !this.isIgnored(rel, false) && shouldIncludeCompiledPath(rel, this.pathFilter)) onFile(abs);
173 232 private shouldWatchDir(absPath: string): boolean {
174 233 const rel = this.projectRel(absPath);
175 - return isSafeProjectRel(rel) && shouldWatchDirectory(rel, this.pathFilter);
234 + return isSafeProjectRel(rel) && !this.isIgnored(rel, true) && shouldWatchDirectory(rel, this.pathFilter);
237 + private loadIgnoreContext(absDir: string): void {
238 + const rel = this.projectRel(absDir);
239 + const stamp = this.ignoreStamp(absDir);
240 + const cached = this.ignoreContexts.get(rel);
241 + if (cached?.stamp === stamp) return;
243 + const parent = path.dirname(absDir);
244 + if (parent !== absDir && isDescendant(this.root, absDir)) this.loadIgnoreContext(parent);
246 + const matcher = ignore();
247 + for (const name of IGNORE_FILE_NAMES) {
248 + try { matcher.add(fs.readFileSync(path.join(absDir, name), "utf-8")); } catch {}
250 + this.ignoreContexts.set(rel, { matcher, stamp });
253 + private isIgnored(relPath: string, directory: boolean): boolean {
254 + const rel = toSlash(relPath);
255 + this.loadIgnoreContext(path.dirname(path.join(this.root, rel)));
256 + for (const [base, context] of this.ignoreContexts) {
257 + if (base && rel !== base && !rel.startsWith(`${base}/`)) continue;
258 + const local = base ? rel.slice(base.length + 1) : rel;
259 + if (!local) continue;
260 + if (context.matcher.ignores(local) || (directory && context.matcher.ignores(`${local}/`))) return true;
262 + return false;
265 + private ignoreStamp(absDir: string): string {
266 + return [...IGNORE_FILE_NAMES].map((name) => {
267 + try {
268 + const stat = fs.statSync(path.join(absDir, name));
269 + return `${name}:${stat.mtimeMs}:${stat.size}`;
270 + } catch {
271 + return `${name}:missing`;
273 + }).join("|");
276 + private invalidateIgnoreContextsUnder(abs: string): void {
277 + const rel = this.projectRel(abs);
278 + for (const base of [...this.ignoreContexts.keys()]) {
279 + if (base === rel || !rel || base.startsWith(`${rel}/`)) this.ignoreContexts.delete(base);
178 283 private recordError(): void {