repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(acli): add atlassian-cli fallback for Confluence page CRUD

2744c6129dafbcf54fa13151a134b37271762a5f

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (13)

.pi/pulse.json

Added
new file mode 100644
1 +{
2 + "documents": [
3 + {
4 + "path": "README.md"
5 + }
6 + ]
7 +}

README.md

Modified
93 93 | `vcs-status` | Pi workspace VCS telemetry for Git and Jujutsu. | [README](extensions/vcs-status/README.md) |
94 94 | `web` | Web fetch, search, and image-analysis tools for Pi. | [README](extensions/web/README.md) |
96 +## Prompts
98 +Global prompt templates live in `~/.pi/agent/prompts/*.md`.
99 +Invoke with `/name` in the editor.
101 +| Name | Description |
102 +| ------ | ------------------------------------------------------------ |
103 +| `wtf` | Agent behavior feedback — surprise, confusion, or annoyance. Acknowledge → fix → prevent, no defensive justifications. |
96 105 ## Resources
98 107 `skills/`, `prompts/`, and `themes/` are exported by the root Pi package

extensions/autoresearch/CHANGELOG.md

Added
new file mode 100644
1 +# Changelog
3 +## 0.1.0 - 2026-05-30
5 +Fork of [pi-autoresearch](https://github.com/davebcn87/pi-autoresearch) with breaking changes:
7 +- State dir moved to `.pi/autoresearch/` (was `autoresearch.*` files at project root)
8 +- Scripts renamed: `benchmark.mjs` (was `autoresearch.sh`), `checks.mjs` (was `autoresearch.checks.sh`)
9 +- Hooks are Node.js only (`.mjs`), no bash dependency
10 +- `workingDir` config option removed (state always in `.pi/autoresearch/`)
11 +- Session files renamed: `session.jsonl` (was `autoresearch.jsonl`), `session.md` (was `autoresearch.md`), `ideas.md` (was `autoresearch.ideas.md`)
12 +- Adapted to `@earendil-works/pi-coding-agent` and `typebox` packages

extensions/autoresearch/README.md

Added
new file mode 100644
1 +# autoresearch
3 +Autonomous experiment loop for Pi.
5 +## Install / load
7 +Loaded through the root `pi-ext` package.
8 +See [root README](../../README.md).
10 +## Commands / tools / settings
12 +Commands:
13 +`/autoresearch [off|clear|export|<text>]` — start, stop, clear, or resume autoresearch mode.
15 +Tools:
16 +- `init_experiment` — configure session (name, metric, unit, direction)
17 +- `run_experiment` — run a timed command, capture output and metrics
18 +- `log_experiment` — record result, auto-commit or auto-revert
20 +Settings:
21 +Keyboard shortcuts configurable in `<agent-dir>/extensions/autoresearch.json`.
23 +## Hooks
25 +- `session_start` / `session_tree`: reconstruct state from `.pi/autoresearch/session.jsonl`
26 +- `before_agent_start`: inject autoresearch system prompt when mode active
27 +- `session_before_compact`: produce deterministic compaction summary
28 +- `agent_end`: schedule auto-resume when mode active
29 +- `session_shutdown`: clean up UI and timers
31 +## State
33 +All state lives in `.pi/autoresearch/`:
35 +| File | Purpose |
36 +|---|---|
37 +| `session.jsonl` | Append-only experiment log |
38 +| `session.md` | Living document: objective, what's been tried |
39 +| `ideas.md` | Backlog of untried optimizations |
40 +| `benchmark.mjs` | Benchmark script |
41 +| `checks.mjs` | Optional correctness gate |
42 +| `config.json` | Optional (`maxIterations`) |
43 +| `hooks/before.mjs` | Optional pre-iteration hook |
44 +| `hooks/after.mjs` | Optional post-iteration hook |
46 +## Behavior
48 +Runs an autonomous loop: edit → commit → benchmark → log → keep or revert → repeat.
50 +Confidence scoring (MAD-based) after 3+ runs: ≥2.0× = real, 1.0–2.0× = marginal, <1.0× = noise.
52 +Backpressure: if `checks.mjs` exists, runs after every passing benchmark. Failures block `keep`.
54 +Hooks: `.mjs` scripts that receive JSON on stdin. Stdout → steer message to agent. Cross-platform.

extensions/autoresearch/__tests__/harness.test.ts

Added
new file mode 100644
1 +import { afterEach, describe, expect, it } from "bun:test";
2 +import path from "node:path";
3 +import {
4 + createTestSession,
5 + type TestSession,
6 +} from "@marcfargas/pi-test-harness";
8 +describe("autoresearch pi-test-harness", () => {
9 + let t: TestSession | undefined;
11 + afterEach(() => {
12 + t?.dispose();
13 + t = undefined;
14 + });
16 + it("loads in real Pi extension runtime", async () => {
17 + const extensionPath = path.resolve(import.meta.dir, "../index.ts");
18 + t = await createTestSession({ extensions: [extensionPath] });
20 + expect(t.session.extensionRunner.extensions).toHaveLength(1);
21 + expect(t.session.extensionRunner.extensions[0].path).toBe(extensionPath);
22 + });
23 +});

extensions/autoresearch/__tests__/unit.test.ts

Added
new file mode 100644
1 +import { describe, expect, it } from "bun:test";
2 +import { __test } from "../index.ts";
3 +import {
4 + parseJsonlEntry,
5 + isAutoresearchConfigEntry,
6 + isAutoresearchRunEntry,
7 + reconstructJsonlState,
8 + hasAutoresearchConfigHeader,
9 + extractAutoresearchSessionName,
10 +} from "../jsonl.ts";
11 +import { buildAutoresearchCompactionSummary } from "../compaction.ts";
12 +import { hookScriptPath } from "../hooks.ts";
14 +// ── Metric line parsing ───────────────────────────────────────────────────
16 +describe("parseMetricLines", () => {
17 + const { parseMetricLines } = __test;
19 + it("parses single METRIC line", () => {
20 + const result = parseMetricLines("METRIC total_µs=15200\n");
21 + expect(result.get("total_µs")).toBe(15200);
22 + });
24 + it("parses multiple METRIC lines", () => {
25 + const output = "METRIC total_µs=15200\nMETRIC compile_µs=4200\n";
26 + const result = parseMetricLines(output);
27 + expect(result.get("total_µs")).toBe(15200);
28 + expect(result.get("compile_µs")).toBe(4200);
29 + });
31 + it("ignores non-METRIC lines", () => {
32 + const result = parseMetricLines("hello\nMETRIC x=42\nworld\n");
33 + expect(result.size).toBe(1);
34 + expect(result.get("x")).toBe(42);
35 + });
37 + it("rejects NaN and Infinity values", () => {
38 + const result = parseMetricLines("METRIC a=Infinity\nMETRIC b=NaN\nMETRIC c=42\n");
39 + expect(result.size).toBe(1);
40 + expect(result.get("c")).toBe(42);
41 + });
43 + it("rejects prototype pollution names", () => {
44 + const result = parseMetricLines("METRIC __proto__=1\nMETRIC constructor=2\n");
45 + expect(result.size).toBe(0);
46 + });
47 +});
49 +// ── Number formatting ─────────────────────────────────────────────────────
51 +describe("formatNum", () => {
52 + const { formatNum } = __test;
54 + it("formats integers with commas", () => {
55 + expect(formatNum(15586, "")).toBe("15,586");
56 + });
58 + it("formats with unit suffix", () => {
59 + expect(formatNum(15200, "µs")).toBe("15,200µs");
60 + });
62 + it("formats fractional with 2 decimals", () => {
63 + expect(formatNum(42.5, "ms")).toBe("42.50ms");
64 + });
65 +});
67 +// ── Benchmark command guard ───────────────────────────────────────────────
69 +describe("isBenchmarkCommand", () => {
70 + const { isBenchmarkCommand } = __test;
72 + it("accepts node benchmark.mjs", () => {
73 + expect(isBenchmarkCommand("node .pi/autoresearch/benchmark.mjs")).toBe(true);
74 + });
76 + it("accepts node with path to benchmark.mjs", () => {
77 + expect(isBenchmarkCommand("node benchmark.mjs")).toBe(true);
78 + });
80 + it("rejects arbitrary commands", () => {
81 + expect(isBenchmarkCommand("pnpm test")).toBe(false);
82 + });
84 + it("strips env prefix", () => {
85 + expect(isBenchmarkCommand("NODE_ENV=test node benchmark.mjs")).toBe(true);
86 + });
88 + it("rejects chained commands", () => {
89 + expect(isBenchmarkCommand("evil.py; node benchmark.mjs")).toBe(false);
90 + });
91 +});
93 +// ── JSONL parsing ─────────────────────────────────────────────────────────
95 +describe("parseJsonlEntry", () => {
96 + it("parses valid JSON", () => {
97 + const entry = parseJsonlEntry('{"type":"config","name":"test"}');
98 + expect(entry).not.toBeNull();
99 + expect(entry!.type).toBe("config");
100 + });
102 + it("returns null for invalid JSON", () => {
103 + expect(parseJsonlEntry("not json")).toBeNull();
104 + });
106 + it("returns null for arrays", () => {
107 + expect(parseJsonlEntry("[1,2,3]")).toBeNull();
108 + });
109 +});
111 +describe("isAutoresearchConfigEntry", () => {
112 + it("recognizes config entries", () => {
113 + expect(isAutoresearchConfigEntry({ type: "config" })).toBe(true);
114 + });
116 + it("rejects run entries", () => {
117 + expect(isAutoresearchConfigEntry({ type: "run", run: 1 })).toBe(false);
118 + });
119 +});
121 +describe("isAutoresearchRunEntry", () => {
122 + it("recognizes run entries", () => {
123 + expect(isAutoresearchRunEntry({ run: 1, metric: 42 })).toBe(true);
124 + });
126 + it("rejects non-run entries", () => {
127 + expect(isAutoresearchRunEntry({ type: "config" })).toBe(false);
128 + });
129 +});
131 +describe("hasAutoresearchConfigHeader", () => {
132 + it("detects config header", () => {
133 + const content = '{"type":"config","name":"test"}\n{"run":1}\n';
134 + expect(hasAutoresearchConfigHeader(content)).toBe(true);
135 + });
137 + it("returns false for no config", () => {
138 + const content = '{"run":1}\n{"run":2}\n';
139 + expect(hasAutoresearchConfigHeader(content)).toBe(false);
140 + });
141 +});
143 +describe("extractAutoresearchSessionName", () => {
144 + it("extracts name from config", () => {
145 + const content = '{"type":"config","name":"Optimize tests"}\n';
146 + expect(extractAutoresearchSessionName(content)).toBe("Optimize tests");
147 + });
149 + it("returns default when no config", () => {
150 + expect(extractAutoresearchSessionName('{"run":1}\n')).toBe("Autoresearch");
151 + });
152 +});
154 +describe("reconstructJsonlState", () => {
155 + it("reconstructs from a complete session", () => {
156 + const content = [
157 + '{"type":"config","name":"test","metricName":"total_ms","metricUnit":"ms","bestDirection":"lower"}',
158 + '{"run":1,"commit":"abc1234","metric":100,"status":"keep","description":"baseline","timestamp":1000}',
159 + '{"run":2,"commit":"def5678","metric":95,"status":"keep","description":"optimized","timestamp":2000}',
160 + ].join("\n");
162 + const state = reconstructJsonlState(content);
163 + expect(state.name).toBe("test");
164 + expect(state.metricName).toBe("total_ms");
165 + expect(state.bestDirection).toBe("lower");
166 + expect(state.results).toHaveLength(2);
167 + expect(state.results[0].metric).toBe(100);
168 + expect(state.results[1].metric).toBe(95);
169 + expect(state.currentSegment).toBe(0);
170 + });
172 + it("handles empty content", () => {
173 + const state = reconstructJsonlState("");
174 + expect(state.results).toHaveLength(0);
175 + expect(state.name).toBeNull();
176 + });
178 + it("segments on re-init", () => {
179 + const content = [
180 + '{"type":"config","name":"v1","metricName":"x"}',
181 + '{"run":1,"commit":"a","metric":10,"status":"keep","description":"b1","timestamp":1000}',
182 + '{"type":"config","name":"v2","metricName":"y"}',
183 + '{"run":2,"commit":"b","metric":20,"status":"keep","description":"b2","timestamp":2000}',
184 + ].join("\n");
186 + const state = reconstructJsonlState(content);
187 + expect(state.results[0].segment).toBe(0);
188 + expect(state.results[1].segment).toBe(1);
189 + expect(state.currentSegment).toBe(1);
190 + expect(state.metricName).toBe("y");
191 + });
192 +});
194 +// ── Compaction summary ────────────────────────────────────────────────────
196 +describe("buildAutoresearchCompactionSummary", () => {
197 + it("produces a summary with no data", () => {
198 + const paths = {
199 + workDir: "/tmp/nonexistent",
200 + jsonlPath: "/tmp/nonexistent/session.jsonl",
201 + mdPath: "/tmp/nonexistent/session.md",
202 + ideasPath: "/tmp/nonexistent/ideas.md",
203 + };
204 + const summary = buildAutoresearchCompactionSummary(paths);
205 + expect(summary).toContain("Autoresearch Compaction Summary");
206 + expect(summary).toContain("Runs so far: 0");
207 + expect(summary).toContain("Next Step");
208 + });
209 +});
211 +// ── Hook script path ──────────────────────────────────────────────────────
213 +describe("hookScriptPath", () => {
214 + it("resolves to .pi/autoresearch/hooks/{stage}.mjs", () => {
215 + expect(hookScriptPath("/project", "before")).toBe(
216 + "/project/.pi/autoresearch/hooks/before.mjs",
217 + );
218 + expect(hookScriptPath("/project", "after")).toBe(
219 + "/project/.pi/autoresearch/hooks/after.mjs",
220 + );
221 + });
222 +});

extensions/autoresearch/compaction.ts

Added
new file mode 100644
1 +/**
2 + * Deterministic compaction summary for autoresearch sessions.
3 + *
4 + * Replaces the default LLM-generated summary with a synthesized view of
5 + * persisted state. Everything that matters lives on disk, so we skip
6 + * the LLM call entirely.
7 + */
9 +import * as fs from "node:fs";
10 +import * as path from "node:path";
12 +import {
13 + reconstructJsonlState,
14 + type ReconstructedJsonlState,
15 + type ReconstructedRun,
16 +} from "./jsonl.ts";
18 +// ── Constants ─────────────────────────────────────────────────────────────
20 +const RECENT_RUN_LIMIT = 50;
22 +// ── Types ─────────────────────────────────────────────────────────────────
24 +type RunStatus = ReconstructedRun["status"];
25 +type StatusCounts = Record<RunStatus, number>;
27 +export interface AutoresearchSummaryPaths {
28 + workDir: string;
29 + jsonlPath: string;
30 + mdPath: string;
31 + ideasPath: string;
34 +export function autoresearchSummaryPathsFor(workDir: string): AutoresearchSummaryPaths {
35 + const base = path.join(workDir, ".pi", "autoresearch");
36 + return {
37 + workDir,
38 + jsonlPath: path.join(base, "session.jsonl"),
39 + mdPath: path.join(base, "session.md"),
40 + ideasPath: path.join(base, "ideas.md"),
41 + };
44 +// ── Public API ────────────────────────────────────────────────────────────
46 +export function buildAutoresearchCompactionSummary(paths: AutoresearchSummaryPaths): string {
47 + const state = loadState(paths.jsonlPath);
48 + return [
49 + headerSection(),
50 + sessionSection(state),
51 + rulesSection(paths.mdPath),
52 + ideasSection(paths.ideasPath),
53 + recentRunsSection(state),
54 + nextStepSection(),
55 + ]
56 + .filter(Boolean)
57 + .join("\n\n");
60 +// ── Sections ──────────────────────────────────────────────────────────────
62 +function loadState(jsonlPath: string): ReconstructedJsonlState {
63 + return reconstructJsonlState(readFileOrEmpty(jsonlPath));
66 +function headerSection(): string {
67 + return [
68 + "# Autoresearch Compaction Summary",
69 + "",
70 + "The conversation history was discarded; the persisted autoresearch state below is the source of truth.",
71 + "Continue the experiment loop using only what is included here plus the live tools.",
72 + ].join("\n");
75 +function sessionSection(state: ReconstructedJsonlState): string {
76 + const runs = currentSegmentRuns(state);
77 + return [
78 + "## Session",
79 + "",
80 + `Goal: ${state.name ?? "—"}`,
81 + `Metric: ${state.metricName} — ${state.bestDirection} is better`,
82 + runCountLine(runs),
83 + ...baselineAndBestLines(runs, state.bestDirection, state.metricUnit),
84 + ].join("\n");
87 +function currentSegmentRuns(state: ReconstructedJsonlState): ReconstructedRun[] {
88 + return state.results.filter((run) => run.segment === state.currentSegment);
91 +function runCountLine(runs: ReconstructedRun[]): string {
92 + if (runs.length === 0) return "Runs so far: 0";
93 + const counts = countByStatus(runs);
94 + const parts = [
95 + `${counts.keep} keep`,
96 + counts.discard ? `${counts.discard} discard` : "",
97 + counts.crash ? `${counts.crash} crash` : "",
98 + counts.checks_failed ? `${counts.checks_failed} checks_failed` : "",
99 + ].filter(Boolean);
100 + return `Runs so far: ${runs.length} (${parts.join(" · ")})`;
103 +function countByStatus(runs: ReconstructedRun[]): StatusCounts {
104 + const counts: StatusCounts = { keep: 0, discard: 0, crash: 0, checks_failed: 0 };
105 + for (const run of runs) counts[run.status]++;
106 + return counts;
109 +function baselineAndBestLines(
110 + runs: ReconstructedRun[],
111 + direction: "lower" | "higher",
112 + unit: string,
113 +): string[] {
114 + const baseline = runs[0];
115 + if (!baseline) return [];
116 + const lines = [`Baseline (#${baseline.run}): ${formatMetricWithUnit(baseline.metric, unit)}`];
117 + const best = bestRun(runs, direction);
118 + if (best && best.run !== baseline.run) {
119 + lines.push(
120 + `Best (#${best.run}): ${formatMetricWithUnit(best.metric, unit)}${formatDelta(best.metric, baseline.metric)}`,
121 + );
123 + return lines;
126 +function formatMetricWithUnit(value: number, unit: string): string {
127 + return `${formatMetric(value)}${unit}`;
130 +function bestRun(runs: ReconstructedRun[], direction: "lower" | "higher"): ReconstructedRun | null {
131 + const kept = runs.filter((run) => run.status === "keep" && Number.isFinite(run.metric));
132 + if (kept.length === 0) return null;
133 + return kept.reduce((best, run) => (isBetter(run.metric, best.metric, direction) ? run : best));
136 +function isBetter(value: number, current: number, direction: "lower" | "higher"): boolean {
137 + return direction === "lower" ? value < current : value > current;
140 +function rulesSection(mdPath: string): string {
141 + const content = readTrimmedFile(mdPath);
142 + if (!content) return "";
143 + return `## Experiment Rules (session.md)\n\n${content}`;
146 +function ideasSection(ideasPath: string): string {
147 + const content = readTrimmedFile(ideasPath);
148 + if (!content) return "";
149 + return `## Ideas Backlog (ideas.md)\n\n${content}`;
152 +function recentRunsSection(state: ReconstructedJsonlState): string {
153 + const runs = state.results.slice(-RECENT_RUN_LIMIT);
154 + if (runs.length === 0) {
155 + return "## Recent Runs\n\nNo runs yet — start with the first hypothesis.";
157 + const lines = runs.map((run) => formatRunLine(run, baselineFor(run, state.results)));
158 + return [
159 + `## Recent Runs (last ${runs.length})`,
160 + "",
161 + "Format: `#run status metric (delta) | desc | hyp: ... | next: ... | rollback: ...`",
162 + "",
163 + ...lines,
164 + "",
165 + "If you need more details, read additional lines from session.jsonl.",
166 + ].join("\n");
169 +function nextStepSection(): string {
170 + return [
171 + "## Next Step",
172 + "",
173 + "Pick the most promising hypothesis (from the ideas backlog or the latest `next:` hints in recent runs)",
174 + "and run the next experiment immediately. Do not stop until interrupted.",
175 + ].join("\n");
178 +// ── Run formatting ────────────────────────────────────────────────────────
180 +function baselineFor(run: ReconstructedRun, all: ReconstructedRun[]): number | null {
181 + const sameSegment = all.find((other) => other.segment === run.segment);
182 + return sameSegment?.metric ?? null;
185 +function formatRunLine(run: ReconstructedRun, baseline: number | null): string {
186 + const head = `#${run.run} ${padStatus(run.status)} ${formatMetric(run.metric)}${formatDelta(run.metric, baseline)}`;
187 + const parts = [head, formatDescription(run), ...formatAsiFields(run.asi)];
188 + return parts.filter(Boolean).join(" | ");
191 +const STATUS_WIDTH = "checks_failed".length;
193 +function padStatus(status: ReconstructedRun["status"]): string {
194 + return status.padEnd(STATUS_WIDTH);
197 +function formatMetric(value: number): string {
198 + if (!Number.isFinite(value)) return "—";
199 + if (Number.isInteger(value)) return String(value);
200 + return value.toFixed(2);
203 +function formatDelta(value: number, baseline: number | null): string {
204 + if (baseline === null || baseline === 0 || value === baseline) return "";
205 + const pct = ((value - baseline) / baseline) * 100;
206 + const sign = pct > 0 ? "+" : "";
207 + return ` (${sign}${pct.toFixed(1)}%)`;
210 +function formatDescription(run: ReconstructedRun): string {
211 + return run.description ? `desc: ${run.description}` : "";
214 +function formatAsiFields(asi: ReconstructedRun["asi"]): string[] {
215 + if (!asi) return [];
216 + return [
217 + formatAsiField(asi, "hypothesis", "hyp"),
218 + formatAsiField(asi, "next_action_hint", "next"),
219 + formatAsiField(asi, "rollback_reason", "rollback"),
220 + ];
223 +function formatAsiField(asi: Record<string, unknown>, key: string, label: string): string {
224 + const value = asi[key];
225 + if (typeof value !== "string" || value.trim() === "") return "";
226 + return `${label}: ${value.trim()}`;
229 +// ── File IO ───────────────────────────────────────────────────────────────
231 +function readTrimmedFile(filePath: string): string {
232 + return readFileOrEmpty(filePath).trim();
235 +function readFileOrEmpty(filePath: string): string {
236 + if (!fs.existsSync(filePath)) return "";
237 + try {
238 + return fs.readFileSync(filePath, "utf-8");
239 + } catch {
240 + return "";

extensions/autoresearch/hooks.ts

Added
new file mode 100644
1 +/**
2 + * Hook runner — fires before/after iteration scripts.
3 + *
4 + * Scripts are Node.js (.mjs) only. No bash dependency.
5 + * Contract: JSON on stdin, text on stdout (→ steer message).
6 + */
8 +import { spawn } from "node:child_process";
9 +import * as fs from "node:fs";
10 +import * as path from "node:path";
12 +import { hasAutoresearchConfigHeader } from "./jsonl.ts";
14 +// ── Constants ─────────────────────────────────────────────────────────────
16 +const TIMEOUT_MS = 30_000;
17 +const STDOUT_MAX_BYTES = 8 * 1024;
18 +const TRUNCATION_MARKER = "\n…[truncated: hook stdout exceeded 8KB]";
19 +const HOOKS_DIR = ".pi/autoresearch/hooks";
21 +const NEWLINE = 0x0a;
22 +const UTF8_CONT_MASK = 0xc0;
23 +const UTF8_CONT = 0x80;
24 +const UTF8_LEAD = 0xc0;
26 +// ── Types ─────────────────────────────────────────────────────────────────
28 +export type HookStage = "before" | "after";
30 +export interface SessionSnapshot {
31 + metric_name: string;
32 + metric_unit: string;
33 + direction: "lower" | "higher";
34 + baseline_metric: number | null;
35 + best_metric: number | null;
36 + run_count: number;
37 + goal: string;
40 +export interface BeforeHookPayload {
41 + event: "before";
42 + cwd: string;
43 + next_run: number;
44 + last_run: Record<string, unknown> | null;
45 + session: SessionSnapshot;
48 +export interface AfterHookPayload {
49 + event: "after";
50 + cwd: string;
51 + run_entry: Record<string, unknown>;
52 + session: SessionSnapshot;
55 +export type HookPayload = BeforeHookPayload | AfterHookPayload;
57 +export interface HookResult {
58 + fired: boolean;
59 + stdout: string;
60 + stderr: string;
61 + exitCode: number | null;
62 + timedOut: boolean;
63 + durationMs: number;
66 +// ── Helpers ───────────────────────────────────────────────────────────────
68 +function truncateAtBoundary(buf: Buffer): Buffer {
69 + const newlineEnd = buf.lastIndexOf(NEWLINE);
70 + if (newlineEnd >= 0) return buf.subarray(0, newlineEnd + 1);
71 + let end = buf.length;
72 + while (end > 0 && (buf[end - 1] & UTF8_CONT_MASK) === UTF8_CONT) end--;
73 + if (end > 0 && (buf[end - 1] & UTF8_CONT_MASK) === UTF8_LEAD) end--;
74 + return buf.subarray(0, end);
77 +export function hookScriptPath(workDir: string, stage: HookStage): string {
78 + return path.join(workDir, HOOKS_DIR, `${stage}.mjs`);
81 +function isFile(filePath: string): boolean {
82 + try {
83 + return fs.statSync(filePath).isFile();
84 + } catch {
85 + return false;
86 + }
89 +const notFired: HookResult = {
90 + fired: false,
91 + stdout: "",
92 + stderr: "",
93 + exitCode: null,
94 + timedOut: false,
95 + durationMs: 0,
96 +};
98 +// ── Public API ────────────────────────────────────────────────────────────
100 +export async function runHook(payload: HookPayload): Promise<HookResult> {
101 + const script = hookScriptPath(payload.cwd, payload.event);
102 + if (!isFile(script)) return notFired;
104 + const t0 = Date.now();
105 + return new Promise<HookResult>((resolve) => {
106 + const child = spawn("node", [script], {
107 + cwd: payload.cwd,
108 + timeout: TIMEOUT_MS,
109 + });
111 + let stdout = "";
112 + let stdoutBytes = 0;
113 + let stdoutFull = false;
114 + let stderr = "";
116 + child.stdout.on("data", (chunk: Buffer) => {
117 + if (stdoutFull) return;
118 + const remaining = STDOUT_MAX_BYTES - stdoutBytes;
119 + if (chunk.length <= remaining) {
120 + stdout += chunk.toString("utf8");
121 + stdoutBytes += chunk.length;
122 + return;
124 + const kept = truncateAtBoundary(chunk.subarray(0, remaining));
125 + stdout += kept.toString("utf8") + TRUNCATION_MARKER;
126 + stdoutFull = true;
127 + });
129 + child.stderr.on("data", (chunk: Buffer) => {
130 + stderr += chunk.toString("utf8");
131 + });
133 + const finish = (exitCode: number | null, extraErr = "") => {
134 + const combinedStderr = extraErr
135 + ? (stderr ? `${stderr}\n${extraErr}` : extraErr)
136 + : stderr;
137 + resolve({
138 + fired: true,
139 + stdout,
140 + stderr: combinedStderr,
141 + exitCode,
142 + timedOut: child.killed,
143 + durationMs: Date.now() - t0,
144 + });
145 + };
147 + child.on("error", (err) => finish(null, err.message));
148 + child.on("close", (code) => finish(code));
150 + child.stdin.write(JSON.stringify(payload));
151 + child.stdin.end();
152 + });
155 +export function steerMessageFor(stage: HookStage, result: HookResult): string | null {
156 + if (!result.fired) return null;
157 + if (result.timedOut) return `[${stage} hook timed out after ${TIMEOUT_MS / 1000}s]`;
158 + if (result.exitCode !== 0) {
159 + const parts = [`[${stage} hook exited ${result.exitCode}]`];
160 + const err = result.stderr.trim();
161 + const out = result.stdout.trim();
162 + if (err) parts.push(err);
163 + if (out) parts.push(out);
164 + return parts.join("\n");
166 + return result.stdout.trim() || null;
169 +export function hookLogEntry(stage: HookStage, result: HookResult): Record<string, unknown> {
170 + return {
171 + type: "hook",
172 + stage,
173 + exit_code: result.exitCode,
174 + duration_ms: result.durationMs,
175 + stdout_bytes: Buffer.byteLength(result.stdout, "utf8"),
176 + timed_out: result.timedOut,
177 + };
180 +function hasConfigHeader(jsonlPath: string): boolean {
181 + if (!fs.existsSync(jsonlPath)) return false;
182 + try {
183 + return hasAutoresearchConfigHeader(fs.readFileSync(jsonlPath, "utf-8"));
184 + } catch {
185 + return false;
189 +export function appendHookLogEntryIfConfigured(
190 + jsonlPath: string,
191 + stage: HookStage,
192 + result: HookResult,
193 +): boolean {
194 + if (!result.fired) return false;
195 + if (!hasConfigHeader(jsonlPath)) return false;
197 + try {
198 + fs.appendFileSync(jsonlPath, JSON.stringify(hookLogEntry(stage, result)) + "\n");
199 + return true;
200 + } catch {
201 + return false;

extensions/autoresearch/index.ts

Added
new file mode 100644
1 +/**
2 + * autoresearch — Autonomous experiment loop for Pi.
3 + *
4 + * Provides tools and a live dashboard for running optimization loops:
5 + * try an idea, benchmark it, keep improvements, revert regressions, repeat.
6 + *
7 + * State lives in .pi/autoresearch/ — zero project-root litter.
8 + */
10 +import type {
11 + ExtensionAPI,
12 + ExtensionContext,
13 + SessionBeforeCompactEvent,
14 + Theme,
15 +} from "@earendil-works/pi-coding-agent";
16 +import { truncateTail, DEFAULT_MAX_BYTES, formatSize } from "@earendil-works/pi-coding-agent";
17 +import { StringEnum } from "@earendil-works/pi-ai";
18 +import { Text, truncateToWidth, matchesKey, visibleWidth } from "@earendil-works/pi-tui";
19 +import { Type } from "typebox";
20 +import * as fs from "node:fs";
21 +import * as path from "node:path";
22 +import { fileURLToPath } from "node:url";
23 +import { createServer, type Server, type ServerResponse } from "node:http";
24 +import { spawn } from "node:child_process";
25 +import { createWriteStream } from "node:fs";
26 +import { randomBytes } from "node:crypto";
27 +import { tmpdir } from "node:os";
29 +import {
30 + runHook,
31 + steerMessageFor,
32 + appendHookLogEntryIfConfigured,
33 + type HookPayload,
34 + type SessionSnapshot,
35 +} from "./hooks.ts";
36 +import {
37 + parseJsonlEntry,
38 + isAutoresearchRunEntry,
39 + extractAutoresearchSessionName,
40 + reconstructJsonlState,
41 +} from "./jsonl.ts";
42 +import {
43 + autoresearchSummaryPathsFor,
44 + buildAutoresearchCompactionSummary,
45 +} from "./compaction.ts";
46 +import { resolveAutoresearchShortcuts } from "./shortcuts.ts";
48 +// ── Constants ─────────────────────────────────────────────────────────────
50 +const EXPERIMENT_MAX_LINES = 10;
51 +const EXPERIMENT_MAX_BYTES = 4 * 1024;
53 +const STATE_DIR = ".pi/autoresearch";
55 +// ── Types ─────────────────────────────────────────────────────────────────
57 +interface ASI {
58 + [key: string]: unknown;
61 +interface ExperimentResult {
62 + commit: string;
63 + metric: number;
64 + metrics: Record<string, number>;
65 + status: "keep" | "discard" | "crash" | "checks_failed";
66 + description: string;
67 + timestamp: number;
68 + segment: number;
69 + confidence: number | null;
70 + asi?: ASI;
73 +interface MetricDef {
74 + name: string;
75 + unit: string;
78 +interface ExperimentState {
79 + results: ExperimentResult[];
80 + bestMetric: number | null;
81 + bestDirection: "lower" | "higher";
82 + metricName: string;
83 + metricUnit: string;
84 + secondaryMetrics: MetricDef[];
85 + name: string | null;
86 + currentSegment: number;
87 + maxExperiments: number | null;
88 + confidence: number | null;
91 +interface RunDetails {
92 + command: string;
93 + exitCode: number | null;
94 + durationSeconds: number;
95 + passed: boolean;
96 + crashed: boolean;
97 + timedOut: boolean;
98 + tailOutput: string;
99 + checksPass: boolean | null;
100 + checksTimedOut: boolean;
101 + checksOutput: string;
102 + checksDuration: number;
103 + parsedMetrics: Record<string, number> | null;
104 + parsedPrimary: number | null;
105 + metricName: string;
106 + metricUnit: string;
109 +interface LogDetails {
110 + experiment: ExperimentResult;
111 + state: ExperimentState;
112 + wallClockSeconds: number | null;
115 +interface AutoresearchRuntime {
116 + autoresearchMode: boolean;
117 + dashboardExpanded: boolean;
118 + experimentsThisSession: number;
119 + autoResumeTurns: number;
120 + lastRunChecks: { pass: boolean; output: string; duration: number } | null;
121 + lastRunDuration: number | null;
122 + runningExperiment: { startedAt: number; command: string } | null;
123 + state: ExperimentState;
124 + pendingResumeTimer: ReturnType<typeof setTimeout> | null;
125 + pendingResumeMessage: string | null;
128 +// ── Tool parameter schemas ────────────────────────────────────────────────
130 +const RunParams = Type.Object({
131 + command: Type.String({
132 + description: "Shell command to run (e.g. 'node .pi/autoresearch/benchmark.mjs')",
133 + }),
134 + timeout_seconds: Type.Optional(
135 + Type.Number({ description: "Kill after this many seconds (default: 600)" }),
136 + ),
137 + checks_timeout_seconds: Type.Optional(
138 + Type.Number({
139 + description: "Kill checks.mjs after this many seconds (default: 300)",
140 + }),
141 + ),
142 +});
144 +const InitParams = Type.Object({
145 + name: Type.String({
146 + description: 'Human-readable session name (e.g. "Optimize test speed")',
147 + }),
148 + metric_name: Type.String({
149 + description: 'Display name for the primary metric (e.g. "total_µs")',
150 + }),
151 + metric_unit: Type.Optional(
152 + Type.String({
153 + description: 'Unit for the primary metric. Default: ""',
154 + }),
155 + ),
156 + direction: Type.Optional(
157 + Type.String({
158 + description: 'Whether "lower" or "higher" is better. Default: "lower".',
159 + }),
160 + ),
161 +});
163 +export const LogParams = Type.Object({
164 + commit: Type.String({ description: "Git commit hash (short, 7 chars)" }),
165 + metric: Type.Number({
166 + description: "Primary optimization metric value. 0 for crashes.",
167 + }),
168 + status: StringEnum(["keep", "discard", "crash", "checks_failed"] as const),
169 + description: Type.String({
170 + description: "Short description of what this experiment tried",
171 + }),
172 + metrics: Type.Optional(
173 + Type.Object(
174 + {},
176 + additionalProperties: Type.Number(),
177 + description: 'Additional metrics as { name: value } pairs',
178 + },
179 + ),
180 + ),
181 + force: Type.Optional(
182 + Type.Boolean({
183 + description: "Allow adding a new secondary metric that wasn't tracked before.",
184 + }),
185 + ),
186 + asi: Type.Optional(
187 + Type.Object(
188 + {},
190 + additionalProperties: Type.Unknown(),
191 + description: "Actionable Side Information — free-form key/value diagnostics.",
192 + },
193 + ),
194 + ),
195 +});
197 +// ── Metric line parsing ───────────────────────────────────────────────────
199 +const METRIC_LINE_PREFIX = "METRIC";
200 +const DENIED_METRIC_NAMES = new Set(["__proto__", "constructor", "prototype"]);
202 +function parseMetricLines(output: string): Map<string, number> {
203 + const metrics = new Map<string, number>();
204 + const regex = new RegExp(
205 + `^${METRIC_LINE_PREFIX}\\s+([\\w.µ]+)=(\\S+)\\s*$`,
206 + "gm",
207 + );
208 + let match;
209 + while ((match = regex.exec(output)) !== null) {
210 + const name = match[1];
211 + if (DENIED_METRIC_NAMES.has(name)) continue;
212 + const value = Number(match[2]);
213 + if (Number.isFinite(value)) metrics.set(name, value);
215 + return metrics;
218 +// ── Formatting helpers ────────────────────────────────────────────────────
220 +function commas(n: number): string {
221 + const s = String(Math.round(n));
222 + const parts: string[] = [];
223 + for (let i = s.length; i > 0; i -= 3) {
224 + parts.unshift(s.slice(Math.max(0, i - 3), i));
226 + return parts.join(",");
229 +function fmtNum(n: number, decimals = 0): string {
230 + if (decimals > 0) {
231 + const int = Math.floor(Math.abs(n));
232 + const frac = (Math.abs(n) - int).toFixed(decimals).slice(1);
233 + return (n < 0 ? "-" : "") + commas(int) + frac;
235 + return commas(n);
238 +function formatNum(value: number | null, unit: string): string {
239 + if (value === null) return "—";
240 + const u = unit || "";
241 + if (value === Math.round(value)) return fmtNum(value) + u;
242 + return fmtNum(value, 2) + u;
245 +function formatElapsed(ms: number): string {
246 + const totalSec = Math.floor(ms / 1000);
247 + const m = Math.floor(totalSec / 60);
248 + const s = totalSec % 60;
249 + if (m > 0) return `${m}m ${String(s).padStart(2, "0")}s`;
250 + return `${s}s`;
253 +// ── Misc helpers ──────────────────────────────────────────────────────────
255 +function killTree(pid: number): void {
256 + try {
257 + process.kill(-pid, "SIGTERM");
258 + } catch {
259 + try {
260 + process.kill(pid, "SIGTERM");
261 + } catch {
262 + // Already exited
267 +function isBetter(current: number, best: number, direction: "lower" | "higher"): boolean {
268 + return direction === "lower" ? current < best : current > best;
271 +function sortedMedian(values: number[]): number {
272 + if (values.length === 0) return 0;
273 + const sorted = [...values].sort((a, b) => a - b);
274 + const mid = Math.floor(sorted.length / 2);
275 + return sorted.length % 2 === 0
276 + ? (sorted[mid - 1] + sorted[mid]) / 2
277 + : sorted[mid];
280 +function computeConfidence(
281 + results: ExperimentResult[],
282 + segment: number,
283 + direction: "lower" | "higher",
284 +): number | null {
285 + const cur = currentResults(results, segment).filter((r) => r.metric > 0);
286 + if (cur.length < 3) return null;
288 + const values = cur.map((r) => r.metric);
289 + const median = sortedMedian(values);
290 + const deviations = values.map((v) => Math.abs(v - median));
291 + const mad = sortedMedian(deviations);
292 + if (mad === 0) return null;
294 + const baseline = findBaselineMetric(results, segment);
295 + if (baseline === null) return null;
297 + let bestKept: number | null = null;
298 + for (const r of cur) {
299 + if (r.status === "keep" && r.metric > 0) {
300 + if (bestKept === null || isBetter(r.metric, bestKept, direction)) {
301 + bestKept = r.metric;
305 + if (bestKept === null || bestKept === baseline) return null;
307 + return Math.abs(bestKept - baseline) / mad;
310 +function currentResults(results: ExperimentResult[], segment: number): ExperimentResult[] {
311 + return results.filter((r) => r.segment === segment);
314 +function clamp(value: number, min: number, max: number): number {
315 + return Math.min(max, Math.max(min, value));
318 +function createTempFileAllocator(): () => string {
319 + let p: string | undefined;
320 + return () => {
321 + if (!p) {
322 + const id = randomBytes(8).toString("hex");
323 + p = path.join(tmpdir(), `pi-experiment-${id}.log`);
325 + return p;
326 + };
329 +// ── State path helpers ────────────────────────────────────────────────────
331 +const stateDir = (dir: string) => path.join(dir, STATE_DIR);
332 +const autoresearchJsonlPath = (dir: string) => path.join(stateDir(dir), "session.jsonl");
333 +const autoresearchMdPath = (dir: string) => path.join(stateDir(dir), "session.md");
334 +const autoresearchIdeasPath = (dir: string) => path.join(stateDir(dir), "ideas.md");
335 +const autoresearchChecksPath = (dir: string) => path.join(stateDir(dir), "checks.mjs");
336 +const autoresearchScriptPath = (dir: string) => path.join(stateDir(dir), "benchmark.mjs");
337 +const autoresearchConfigPath = (dir: string) => path.join(stateDir(dir), "config.json");
339 +function findBaselineMetric(results: ExperimentResult[], segment: number): number | null {
340 + const cur = currentResults(results, segment);
341 + return cur.length > 0 ? cur[0].metric : null;
344 +function findBestMetric(
345 + results: ExperimentResult[],
346 + segment: number,
347 + direction: "lower" | "higher",
348 +): number | null {
349 + const kept = currentResults(results, segment)
350 + .filter((r) => r.status === "keep")
351 + .map((r) => r.metric);
352 + if (kept.length === 0) return null;
353 + return direction === "lower" ? Math.min(...kept) : Math.max(...kept);
356 +function findBaselineRunNumber(results: ExperimentResult[], segment: number): number | null {
357 + const index = results.findIndex((result) => result.segment === segment);
358 + return index >= 0 ? index + 1 : null;
361 +function findBaselineSecondary(
362 + results: ExperimentResult[],
363 + segment: number,
364 + knownMetrics?: MetricDef[],
365 +): Record<string, number> {
366 + const cur = currentResults(results, segment);
367 + const base: Record<string, number> = cur.length > 0 ? { ...(cur[0].metrics ?? {}) } : {};
369 + if (knownMetrics) {
370 + for (const sm of knownMetrics) {
371 + if (base[sm.name] === undefined) {
372 + for (const r of cur) {
373 + const val = (r.metrics ?? {})[sm.name];
374 + if (val !== undefined) {
375 + base[sm.name] = val;
376 + break;
382 + return base;
385 +function readMaxExperiments(cwd: string): number | null {
386 + try {
387 + const configPath = autoresearchConfigPath(cwd);
388 + if (!fs.existsSync(configPath)) return null;
389 + const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
390 + return typeof config.maxIterations === "number" && config.maxIterations > 0
391 + ? Math.floor(config.maxIterations)
392 + : null;
393 + } catch {
394 + return null;
398 +// ── State factories ───────────────────────────────────────────────────────
400 +function cloneExperimentState(state: ExperimentState): ExperimentState {
401 + return {
402 + ...state,
403 + results: state.results.map((result) => ({
404 + ...result,
405 + metrics: { ...result.metrics },
406 + })),
407 + secondaryMetrics: state.secondaryMetrics.map((metric) => ({ ...metric })),
408 + };
411 +function createExperimentState(): ExperimentState {
412 + return {
413 + results: [],
414 + bestMetric: null,
415 + bestDirection: "lower",
416 + metricName: "metric",
417 + metricUnit: "",
418 + secondaryMetrics: [],
419 + name: null,
420 + currentSegment: 0,
421 + maxExperiments: null,
422 + confidence: null,
423 + };
426 +function createSessionRuntime(): AutoresearchRuntime {
427 + return {
428 + autoresearchMode: false,
429 + dashboardExpanded: false,
430 + experimentsThisSession: 0,
431 + autoResumeTurns: 0,
432 + lastRunChecks: null,
433 + lastRunDuration: null,
434 + runningExperiment: null,
435 + state: createExperimentState(),
436 + pendingResumeTimer: null,
437 + pendingResumeMessage: null,
438 + };
441 +function createRuntimeStore() {
442 + const runtimes = new Map<string, AutoresearchRuntime>();
443 + return {
444 + ensure(sessionKey: string): AutoresearchRuntime {
445 + let runtime = runtimes.get(sessionKey);
446 + if (!runtime) {
447 + runtime = createSessionRuntime();
448 + runtimes.set(sessionKey, runtime);
450 + return runtime;
451 + },
452 + clear(sessionKey: string): void {
453 + runtimes.delete(sessionKey);
454 + },
455 + };
458 +// ── Benchmark command guard ───────────────────────────────────────────────
460 +function isBenchmarkCommand(command: string): boolean {
461 + let cmd = command.trim();
462 + cmd = cmd.replace(/^(?:\w+=\S*\s+)+/, "");
463 + let prev: string;
464 + do {
465 + prev = cmd;
466 + cmd = cmd.replace(/^(?:env|time|nice|nohup)(?:\s+-\S+(?:\s+\d+)?)*\s+/, "");
467 + } while (cmd !== prev);
469 + return /^(?:node)\s+(?:.*\/)?benchmark\.mjs(?:\s|$)/.test(cmd);
472 +// ── TUI helpers ───────────────────────────────────────────────────────────
474 +function truncateDisplayText(text: string, width: number): string {
475 + if (width <= 0) return "";
476 + return truncateToWidth(text, width, "…", true);
479 +function joinPartsToWidth(parts: string[], width: number): string {
480 + let line = "";
481 + for (const part of parts) {
482 + if (!part) continue;
483 + const next = line + part;
484 + if (visibleWidth(next) <= width) {
485 + line = next;
486 + continue;
488 + return truncateToWidth(line || part, width, "…", true);
490 + return truncateToWidth(line, width, "…", true);
493 +function appendRightAlignedAdaptiveHint(
494 + left: string,
495 + width: number,
496 + theme: Theme,
497 + candidates: string[],
498 +): string {
499 + if (width <= 0) return "";
500 + const leftWidth = visibleWidth(left);
501 + for (const candidate of candidates) {
502 + const hint = theme.fg("dim", ` ${candidate}`);
503 + const hintWidth = visibleWidth(hint);
504 + if (hintWidth > width) continue;
505 + if (leftWidth + hintWidth <= width) {
506 + return left + " ".repeat(Math.max(0, width - leftWidth - hintWidth)) + hint;
508 + const availableLeftWidth = Math.max(0, width - hintWidth);
509 + const truncatedLeft = truncateToWidth(left, availableLeftWidth, "…", true);
510 + const truncatedLeftWidth = visibleWidth(truncatedLeft);
511 + return (
512 + truncatedLeft +
513 + " ".repeat(Math.max(0, width - truncatedLeftWidth - hintWidth)) +
514 + hint
515 + );
517 + return truncateToWidth(left, width, "…", true);
520 +function getTuiSize(tui: {
521 + terminal?: { columns?: number; rows?: number };
522 +}): { width: number; height: number } {
523 + return {
524 + width: tui.terminal?.columns ?? process.stdout.columns ?? 120,
525 + height: tui.terminal?.rows ?? process.stdout.rows ?? 40,
526 + };
529 +// ── Dashboard renderer ────────────────────────────────────────────────────
531 +function renderDashboardLines(
532 + st: ExperimentState,
533 + width: number,
534 + th: Theme,
535 + maxRows = 6,
536 + headerHints: string[] = [],
537 +): string[] {
538 + const lines: string[] = [];
539 + if (st.results.length === 0) {
540 + lines.push(` ${th.fg("dim", "No experiments yet.")}`);
541 + return lines;
544 + const cur = currentResults(st.results, st.currentSegment);
545 + const kept = cur.filter((r) => r.status === "keep").length;
546 + const discarded = cur.filter((r) => r.status === "discard").length;
547 + const crashed = cur.filter((r) => r.status === "crash").length;
548 + const checksFailed = cur.filter((r) => r.status === "checks_failed").length;
550 + const baseline = st.bestMetric;
551 + const baselineRunNumber = findBaselineRunNumber(st.results, st.currentSegment);
552 + const baselineSec = findBaselineSecondary(st.results, st.currentSegment, st.secondaryMetrics);
554 + let bestPrimary: number | null = null;
555 + let bestSecondary: Record<string, number> = {};
556 + let bestRunNum = 0;
557 + for (let i = st.results.length - 1; i >= 0; i--) {
558 + const r = st.results[i];
559 + if (r.segment !== st.currentSegment) continue;
560 + if (r.status === "keep" && r.metric > 0) {
561 + if (bestPrimary === null || isBetter(r.metric, bestPrimary, st.bestDirection)) {
562 + bestPrimary = r.metric;
563 + bestSecondary = r.metrics ?? {};
564 + bestRunNum = i + 1;
569 + const confSuffix = st.confidence !== null
570 + ? (() => {
571 + const confStr = st.confidence!.toFixed(1);
572 + const confColor: Parameters<typeof th.fg>[0] =
573 + st.confidence! >= 2.0 ? "success" : st.confidence! >= 1.0 ? "warning" : "error";
574 + return ` ${th.fg(confColor, `(conf: ${confStr}×)`)}`;
575 + })()
576 + : "";
578 + lines.push(
579 + truncateToWidth(
580 + ` ${th.fg("muted", "Runs:")} ${th.fg("text", String(st.results.length))}` +
581 + ` ${th.fg("success", `${kept} kept`)}` +
582 + confSuffix +
583 + (discarded > 0 ? ` ${th.fg("warning", `${discarded} discarded`)}` : "") +
584 + (crashed > 0 ? ` ${th.fg("error", `${crashed} crashed`)}` : "") +
585 + (checksFailed > 0 ? ` ${th.fg("error", `${checksFailed} checks failed`)}` : ""),
586 + width,
587 + ),
588 + );
590 + const baselineSuffix = baselineRunNumber === null ? "" : ` #${baselineRunNumber}`;
591 + lines.push(
592 + truncateToWidth(
593 + ` ${th.fg("muted", "Baseline:")} ${th.fg("muted", `★ ${st.metricName}: ${formatNum(baseline, st.metricUnit)}${baselineSuffix}`)}`,
594 + width,
595 + ),
596 + );
598 + if (bestPrimary !== null) {
599 + let progressLine = ` ${th.fg("muted", "Progress:")} ${th.fg("warning", th.bold(`★ ${st.metricName}: ${formatNum(bestPrimary, st.metricUnit)}`))}${th.fg("dim", ` #${bestRunNum}`)}`;
600 + if (baseline !== null && baseline !== 0 && bestPrimary !== baseline) {
601 + const pct = ((bestPrimary - baseline) / baseline) * 100;
602 + const sign = pct > 0 ? "+" : "";
603 + const color = isBetter(bestPrimary, baseline, st.bestDirection) ? "success" : "error";
604 + progressLine += th.fg(color, ` (${sign}${pct.toFixed(1)}%)`);
606 + lines.push(truncateToWidth(progressLine, width));
608 + if (st.secondaryMetrics.length > 0) {
609 + const indent = " ";
610 + const maxLineW = width - 2 - indent.length;
611 + const secParts: string[] = [];
612 + for (const sm of st.secondaryMetrics) {
613 + const val = bestSecondary[sm.name];
614 + const bv = baselineSec[sm.name];
615 + if (val !== undefined) {
616 + let part = th.fg("muted", `${sm.name}: ${formatNum(val, sm.unit)}`);
617 + if (bv !== undefined && bv !== 0 && val !== bv) {
618 + const p = ((val - bv) / bv) * 100;
619 + const s = p > 0 ? "+" : "";
620 + const c = val <= bv ? "success" : "error";
621 + part += th.fg(c, ` ${s}${p.toFixed(1)}%`);
623 + secParts.push(part);
626 + if (secParts.length > 0) {
627 + let curLine = "";
628 + let curVisW = 0;
629 + for (const part of secParts) {
630 + const partVisW = visibleWidth(part);
631 + const sep = curLine ? " " : "";
632 + if (curLine && curVisW + sep.length + partVisW > maxLineW) {
633 + lines.push(
634 + truncateToWidth(` ${th.fg("dim", indent)}${curLine}`, width),
635 + );
636 + curLine = part;
637 + curVisW = partVisW;
638 + } else {
639 + curLine += sep + part;
640 + curVisW += sep.length + partVisW;
643 + if (curLine) {
644 + lines.push(
645 + truncateToWidth(` ${th.fg("dim", indent)}${curLine}`, width),
646 + );
652 + lines.push("");
654 + const effectiveMax = maxRows <= 0 ? st.results.length : maxRows;
655 + const startIdx = Math.max(0, st.results.length - effectiveMax);
656 + const rowsToRender = st.results.slice(startIdx);
658 + const secMetrics = st.secondaryMetrics.filter((sm) =>
659 + rowsToRender.some((r) => (r.metrics ?? {})[sm.name] !== undefined),
660 + );
662 + const primaryLabel = "★ " + (st.metricName || "metric");
663 + const primaryW = Math.max(
664 + 11,
665 + Math.min(Math.floor(width * 0.25), visibleWidth(primaryLabel) + 1),
666 + );
667 + const col = { idx: 3, commit: 8, primary: primaryW, status: 15 };
668 + const minDescW = Math.max(10, Math.floor(width * 0.25));
669 + const fixedW = col.idx + col.commit + col.primary + col.status + 6;
671 + const secColWidths: number[] = secMetrics.map((sm) => {
672 + let maxW = visibleWidth(sm.name);
673 + for (const r of rowsToRender) {
674 + const val = (r.metrics ?? {})[sm.name];
675 + if (val !== undefined) maxW = Math.max(maxW, visibleWidth(formatNum(val, sm.unit)));
677 + return maxW + 1;
678 + });
680 + const totalSecWidth = () =>
681 + secColWidths.slice(0, visibleSecMetrics.length).reduce((a, b) => a + b, 0);
683 + let visibleSecMetrics = secMetrics;
684 + while (
685 + visibleSecMetrics.length > 0 &&
686 + totalSecWidth() > width - fixedW - minDescW
687 + ) {
688 + visibleSecMetrics = visibleSecMetrics.slice(0, -1);
691 + const descW = Math.max(minDescW, width - fixedW - totalSecWidth());
693 + let headerLine =
694 + ` ${th.fg("muted", "#".padEnd(col.idx))}` +
695 + `${th.fg("muted", "commit".padEnd(col.commit))}` +
696 + `${th.fg("warning", th.bold(truncateToWidth(primaryLabel, col.primary - 1).padEnd(col.primary)))}`;
698 + for (let si = 0; si < visibleSecMetrics.length; si++) {
699 + const sm = visibleSecMetrics[si];
700 + headerLine += th.fg("muted", sm.name.padEnd(secColWidths[si]));
703 + headerLine +=
704 + `${th.fg("muted", "status".padEnd(col.status))}` +
705 + `${th.fg("muted", "description")}`;
707 + lines.push(
708 + headerHints.length > 0
709 + ? appendRightAlignedAdaptiveHint(headerLine, width, th, headerHints)
710 + : truncateToWidth(headerLine, width, "…", true),
711 + );
712 + lines.push(
713 + truncateToWidth(
714 + ` ${th.fg("borderMuted", "─".repeat(Math.max(0, width - 4)))}`,
715 + width,
716 + ),
717 + );
719 + const baselinePrimary = findBaselineMetric(st.results, st.currentSegment);
720 + const baselineSecondary = findBaselineSecondary(
721 + st.results,
722 + st.currentSegment,
723 + st.secondaryMetrics,
724 + );
726 + if (startIdx > 0) {
727 + lines.push(
728 + truncateToWidth(
729 + ` ${th.fg("dim", `… ${startIdx} earlier run${startIdx === 1 ? "" : "s"}`)}`,
730 + width,
731 + ),
732 + );
735 + const baselineIndex = st.results.findIndex((x) => x.segment === st.currentSegment);
737 + for (let i = startIdx; i < st.results.length; i++) {
738 + const r = st.results[i];
739 + const isOld = r.segment !== st.currentSegment;
740 + const isBaseline = !isOld && i === baselineIndex;
742 + const color: Parameters<typeof th.fg>[0] = isOld
743 + ? "dim"
744 + : r.status === "keep"
745 + ? "success"
746 + : r.status === "crash" || r.status === "checks_failed"
747 + ? "error"
748 + : "warning";
750 + const primaryStr = formatNum(r.metric, st.metricUnit);
751 + let primaryColor: Parameters<typeof th.fg>[0] = isOld ? "dim" : "text";
752 + if (!isOld) {
753 + if (isBaseline) {
754 + primaryColor = "text";
755 + } else if (
756 + baselinePrimary !== null &&
757 + r.status === "keep" &&
758 + r.metric > 0
759 + ) {
760 + if (isBetter(r.metric, baselinePrimary, st.bestDirection)) {
761 + primaryColor = "success";
762 + } else if (r.metric !== baselinePrimary) {
763 + primaryColor = "error";
768 + const idxStr = th.fg("dim", String(i + 1).padEnd(col.idx));
769 + const commitStr = isOld
770 + ? "(old)".padEnd(col.commit)
771 + : r.status !== "keep"
772 + ? "—".padStart(Math.ceil(col.commit / 2)).padEnd(col.commit)
773 + : r.commit.padEnd(col.commit);
775 + let rowLine =
776 + ` ${idxStr}` +
777 + `${th.fg(isOld ? "dim" : "accent", commitStr)}` +
778 + `${th.fg(primaryColor, isOld ? primaryStr.padEnd(col.primary) : th.bold(primaryStr.padEnd(col.primary)))}`;
780 + const rowMetrics = r.metrics ?? {};
781 + for (let si = 0; si < visibleSecMetrics.length; si++) {
782 + const sm = visibleSecMetrics[si];
783 + const colW = secColWidths[si];
784 + const val = rowMetrics[sm.name];
785 + if (val !== undefined) {
786 + const secStr = formatNum(val, sm.unit);
787 + let secColor: Parameters<typeof th.fg>[0] = "dim";
788 + if (!isOld) {
789 + const bv = baselineSecondary[sm.name];
790 + if (isBaseline) secColor = "text";
791 + else if (bv !== undefined && bv !== 0)
792 + secColor = val <= bv ? "success" : "error";
794 + rowLine += th.fg(secColor, secStr.padEnd(colW));
795 + } else {
796 + rowLine += th.fg("dim", "—".padEnd(colW));
800 + rowLine +=
801 + `${th.fg(color, r.status.padEnd(col.status))}` +
802 + `${th.fg("muted", r.description.slice(0, descW))}`;
804 + lines.push(truncateToWidth(rowLine, width));
807 + return lines;
810 +// ── Exported test helpers ─────────────────────────────────────────────────
812 +export const __test = {
813 + parseMetricLines,
814 + formatNum,
815 + isBenchmarkCommand,
818 +// ── Extension ─────────────────────────────────────────────────────────────
820 +export default function autoresearchExtension(pi: ExtensionAPI) {
821 + const MAX_AUTORESUME_TURNS = 20;
822 + const BENCHMARK_GUARDRAIL =
823 + "Be careful not to overfit to the benchmarks and do not cheat on the benchmarks.";
824 + const SETTLED_WINDOW_MS = 800;
825 + const shortcuts = resolveAutoresearchShortcuts();
827 + const dashboardHintVariants = (toggleAction: "expand" | "collapse"): string[] => {
828 + const toggle = shortcuts.toggleDashboard
829 + ? `${shortcuts.toggleDashboard} ${toggleAction}`
830 + : null;
831 + const fullscreen = shortcuts.fullscreenDashboard
832 + ? `${shortcuts.fullscreenDashboard} fullscreen`
833 + : null;
834 + if (toggle && fullscreen) {
835 + return [
836 + `${toggle} • ${fullscreen}`,
837 + `${toggle} • full: ${shortcuts.fullscreenDashboard}`,
838 + `${shortcuts.toggleDashboard} • ${shortcuts.fullscreenDashboard}`,
839 + ];
841 + return [toggle, fullscreen].filter((hint): hint is string => hint !== null);
842 + };
844 + const runtimeStore = createRuntimeStore();
845 + const getSessionKey = (ctx: ExtensionContext) => ctx.sessionManager.getSessionId();
846 + const getRuntime = (ctx: ExtensionContext): AutoresearchRuntime =>
847 + runtimeStore.ensure(getSessionKey(ctx));
849 + const isAgentSettled = (ctx: ExtensionContext): boolean =>
850 + ctx.isIdle() && !ctx.hasPendingMessages();
852 + const hasPendingResume = (runtime: AutoresearchRuntime): boolean =>
853 + runtime.pendingResumeMessage !== null;
855 + const pausePendingResume = (runtime: AutoresearchRuntime): void => {
856 + if (!runtime.pendingResumeTimer) return;
857 + clearTimeout(runtime.pendingResumeTimer);
858 + runtime.pendingResumeTimer = null;
859 + };
861 + const cancelPendingResume = (runtime: AutoresearchRuntime): void => {
862 + pausePendingResume(runtime);
863 + runtime.pendingResumeMessage = null;
864 + };
866 + const markAutoResumeSent = (runtime: AutoresearchRuntime): void => {
867 + runtime.autoResumeTurns++;
868 + };
870 + const sendPendingResumeIfReady = (
871 + ctx: ExtensionContext,
872 + runtime: AutoresearchRuntime,
873 + ): void => {
874 + const message = runtime.pendingResumeMessage;
875 + if (!message) return;
876 + if (!runtime.autoresearchMode) {
877 + cancelPendingResume(runtime);
878 + return;
880 + if (!isAgentSettled(ctx)) return;
881 + if (hasReachedAutoResumeLimit(runtime)) {
882 + cancelPendingResume(runtime);
883 + notifyAutoResumeLimitReached(ctx);
884 + return;
886 + cancelPendingResume(runtime);
887 + markAutoResumeSent(runtime);
888 + pi.sendUserMessage(message);
889 + };
891 + const schedulePendingResume = (
892 + ctx: ExtensionContext,
893 + runtime: AutoresearchRuntime,
894 + message: string,
895 + ): void => {
896 + pausePendingResume(runtime);
897 + runtime.pendingResumeMessage = message;
898 + runtime.pendingResumeTimer = setTimeout(
899 + () => sendPendingResumeIfReady(ctx, runtime),
900 + SETTLED_WINDOW_MS,
901 + );
902 + };
904 + const reschedulePendingResume = (
905 + ctx: ExtensionContext,
906 + runtime: AutoresearchRuntime,
907 + ): void => {
908 + if (!hasPendingResume(runtime)) return;
909 + schedulePendingResume(ctx, runtime, runtime.pendingResumeMessage!);
910 + };
912 + const hasRunExperimentsThisSession = (runtime: AutoresearchRuntime): boolean =>
913 + runtime.experimentsThisSession > 0;
915 + const shouldAutoResumeAfterTurn = (runtime: AutoresearchRuntime): boolean =>
916 + runtime.autoresearchMode && hasRunExperimentsThisSession(runtime);
918 + const shouldAutoResumeAfterCompact = (runtime: AutoresearchRuntime): boolean =>
919 + runtime.autoresearchMode;
921 + const hasReachedAutoResumeLimit = (runtime: AutoresearchRuntime): boolean =>
922 + runtime.autoResumeTurns >= MAX_AUTORESUME_TURNS;
924 + const notifyAutoResumeLimitReached = (ctx: ExtensionContext): void => {
925 + ctx.ui.notify(
926 + `Autoresearch auto-resume limit reached (${MAX_AUTORESUME_TURNS} turns)`,
927 + "info",
928 + );
929 + };
931 + const composeResumeMessage = (_ctx: ExtensionContext): string => {
932 + return [
933 + "Run the next iteration now.",
934 + "Use the persisted autoresearch state as needed, pick the most promising hypothesis, then call run_experiment + log_experiment.",
935 + BENCHMARK_GUARDRAIL,
936 + ].join(" ");
937 + };
939 + const composeCompactionResumeMessage = (_ctx: ExtensionContext): string => {
940 + return [
941 + "Run the next iteration now.",
942 + "Pick the most promising hypothesis from the ideas backlog or the latest `next:` hints in recent runs, then call run_experiment + log_experiment.",
943 + "Do not re-read session.md or session.jsonl — the compaction summary already contains them.",
944 + BENCHMARK_GUARDRAIL,
945 + ].join(" ");
946 + };
948 + const autoresearchCompactionFor = (
949 + ctx: ExtensionContext,
950 + event: SessionBeforeCompactEvent,
951 + ) => {
952 + if (!getRuntime(ctx).autoresearchMode) return undefined;
953 + return {
954 + compaction: {
955 + summary: buildAutoresearchCompactionSummary(
956 + autoresearchSummaryPathsFor(ctx.cwd),
957 + ),
958 + firstKeptEntryId: event.preparation.firstKeptEntryId,
959 + tokensBefore: event.preparation.tokensBefore,
960 + },
961 + };
962 + };
964 + const sendWhenReady = (ctx: ExtensionContext, message: string): void => {
965 + if (ctx.isIdle()) {
966 + pi.sendUserMessage(message);
967 + return;
969 + pi.sendUserMessage(message, { deliverAs: "followUp" });
970 + };
972 + const hasAutoresearchRules = (ctx: ExtensionContext): boolean =>
973 + fs.existsSync(autoresearchMdPath(ctx.cwd));
975 + const readJsonlLines = (cwd: string): string[] => {
976 + const jsonlPath = autoresearchJsonlPath(cwd);
977 + if (!fs.existsSync(jsonlPath)) return [];
978 + return fs.readFileSync(jsonlPath, "utf-8").split("\n").filter(Boolean);
979 + };
981 + const readLastRun = (cwd: string): Record<string, unknown> | null => {
982 + const lines = readJsonlLines(cwd);
983 + for (let i = lines.length - 1; i >= 0; i--) {
984 + const entry = parseJsonlEntry(lines[i]);
985 + if (isAutoresearchRunEntry(entry)) return entry;
987 + return null;
988 + };
990 + const buildSessionSnapshot = (state: ExperimentState): SessionSnapshot => ({
991 + metric_name: state.metricName,
992 + metric_unit: state.metricUnit,
993 + direction: state.bestDirection,
994 + baseline_metric: state.bestMetric,
995 + best_metric: findBestMetric(state.results, state.currentSegment, state.bestDirection),
996 + run_count: state.results.length,
997 + goal: state.name ?? "",
998 + });
1000 + const fireHook = async (payload: HookPayload): Promise<string | null> => {
1001 + const result = await runHook(payload);
1002 + appendHookLogEntryIfConfigured(
1003 + autoresearchJsonlPath(payload.cwd),
1004 + payload.event,
1005 + result,
1006 + );
1007 + return steerMessageFor(payload.event, result);
1008 + };
1010 + // ── Fullscreen overlay state ────────────────────────────────────────
1012 + let overlayTui: { requestRender: () => void } | null = null;
1013 + let spinnerInterval: ReturnType<typeof setInterval> | null = null;
1014 + let spinnerFrame = 0;
1015 + const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
1017 + const clearOverlay = () => {
1018 + overlayTui = null;
1019 + if (spinnerInterval) {
1020 + clearInterval(spinnerInterval);
1021 + spinnerInterval = null;
1023 + };
1025 + const clearSessionUi = (ctx: ExtensionContext) => {
1026 + clearOverlay();
1027 + if (ctx.hasUI) ctx.ui.setWidget("autoresearch", undefined);
1028 + };
1030 + const autoresearchHelp = () =>
1032 + "Usage: /autoresearch [off|clear|export|<text>]",
1033 + "",
1034 + "<text> enters autoresearch mode and starts or resumes the loop.",
1035 + "off leaves autoresearch mode.",
1036 + "clear deletes session.jsonl and turns autoresearch mode off.",
1037 + "export opens a local live dashboard in your browser.",
1038 + "",
1039 + "Examples:",
1040 + " /autoresearch optimize unit test runtime",
1041 + " /autoresearch export",
1042 + ].join("\n");
1044 + // ── State reconstruction ───────────────────────────────────────────
1046 + const reconstructState = (ctx: ExtensionContext) => {
1047 + const runtime = getRuntime(ctx);
1048 + cancelPendingResume(runtime);
1049 + runtime.lastRunChecks = null;
1050 + runtime.lastRunDuration = null;
1051 + runtime.runningExperiment = null;
1052 + runtime.experimentsThisSession = 0;
1053 + runtime.autoResumeTurns = 0;
1054 + runtime.state = createExperimentState();
1056 + const state = runtime.state;
1057 + const jsonlPath = autoresearchJsonlPath(ctx.cwd);
1058 + let loadedFromJsonl = false;
1059 + try {
1060 + if (fs.existsSync(jsonlPath)) {
1061 + const reconstructed = reconstructJsonlState(
1062 + fs.readFileSync(jsonlPath, "utf-8"),
1063 + );
1064 + state.name = reconstructed.name;
1065 + state.metricName = reconstructed.metricName;
1066 + state.metricUnit = reconstructed.metricUnit;
1067 + state.bestDirection = reconstructed.bestDirection;
1068 + state.currentSegment = reconstructed.currentSegment;
1069 + state.results = reconstructed.results.map((result) => ({
1070 + ...result,
1071 + metrics: { ...result.metrics },
1072 + }));
1073 + state.secondaryMetrics = reconstructed.secondaryMetrics.map((metric) => ({
1074 + ...metric,
1075 + }));
1077 + if (state.results.length > 0) {
1078 + loadedFromJsonl = true;
1079 + state.bestMetric = findBaselineMetric(state.results, state.currentSegment);
1080 + state.confidence = computeConfidence(
1081 + state.results,
1082 + state.currentSegment,
1083 + state.bestDirection,
1084 + );
1087 + } catch {
1088 + // Fall through
1091 + if (!loadedFromJsonl) {
1092 + for (const entry of ctx.sessionManager.getBranch()) {
1093 + if (entry.type !== "message") continue;
1094 + const msg = entry.message;
1095 + if (msg.role !== "toolResult" || msg.toolName !== "log_experiment") continue;
1096 + const details = msg.details as LogDetails | undefined;
1097 + if (details?.state) {
1098 + runtime.state = cloneExperimentState(details.state);
1099 + if (!runtime.state.secondaryMetrics) runtime.state.secondaryMetrics = [];
1100 + for (const r of runtime.state.results) {
1101 + if (!r.metrics) r.metrics = {};
1102 + if (r.confidence === undefined) r.confidence = null;
1104 + if (runtime.state.confidence === undefined) {
1105 + runtime.state.confidence = computeConfidence(
1106 + runtime.state.results,
1107 + runtime.state.currentSegment,
1108 + runtime.state.bestDirection,
1109 + );
1115 + state.maxExperiments = readMaxExperiments(ctx.cwd);
1116 + runtime.autoresearchMode = fs.existsSync(jsonlPath);
1117 + updateWidget(ctx);
1118 + };
1120 + // ── Widget ──────────────────────────────────────────────────────────
1122 + const updateWidget = (ctx: ExtensionContext) => {
1123 + if (!ctx.hasUI) return;
1124 + const runtime = getRuntime(ctx);
1125 + const state = runtime.state;
1127 + if (state.results.length === 0 && !runtime.runningExperiment) {
1128 + ctx.ui.setWidget("autoresearch", undefined);
1129 + return;
1132 + if (state.results.length === 0 && runtime.runningExperiment) {
1133 + ctx.ui.setWidget("autoresearch", (tui, theme) => ({
1134 + render(width: number): string[] {
1135 + const safeWidth = Math.max(1, width || getTuiSize(tui).width);
1136 + return [
1137 + joinPartsToWidth(
1139 + theme.fg("accent", "🔬"),
1140 + theme.fg("warning", " running…"),
1141 + state.name ? theme.fg("dim", ` │ ${state.name}`) : "",
1142 + theme.fg("dim", ` │ ${runtime.runningExperiment?.command ?? ""}`),
1143 + theme.fg("dim", " │ waiting for first logged result"),
1144 + ],
1145 + safeWidth,
1146 + ),
1147 + ];
1148 + },
1149 + invalidate(): void {},
1150 + }));
1151 + return;
1154 + if (runtime.dashboardExpanded) {
1155 + ctx.ui.setWidget("autoresearch", (tui, theme) => ({
1156 + render(width: number): string[] {
1157 + const safeWidth = Math.max(1, width || getTuiSize(tui).width);
1158 + const title = truncateDisplayText(
1159 + `🔬 autoresearch${state.name ? `: ${state.name}` : ""}`,
1160 + Math.max(0, safeWidth - 5),
1161 + );
1162 + const fillLen = Math.max(0, safeWidth - 3 - 1 - visibleWidth(title) - 1);
1163 + const rows = safeWidth < 95 ? 4 : 6;
1164 + return [
1165 + truncateToWidth(
1166 + theme.fg("borderMuted", "───") +
1167 + theme.fg("accent", ` ${title} `) +
1168 + theme.fg("borderMuted", "─".repeat(fillLen)),
1169 + safeWidth,
1170 + "…",
1171 + true,
1172 + ),
1173 + ...renderDashboardLines(
1174 + state,
1175 + safeWidth,
1176 + theme,
1177 + rows,
1178 + dashboardHintVariants("collapse"),
1179 + ),
1180 + ];
1181 + },
1182 + invalidate(): void {},
1183 + }));
1184 + } else {
1185 + ctx.ui.setWidget("autoresearch", (tui, theme) => ({
1186 + render(width: number): string[] {
1187 + const safeWidth = Math.max(1, width || getTuiSize(tui).width);
1188 + const cur = currentResults(state.results, state.currentSegment);
1189 + const kept = cur.filter((r) => r.status === "keep").length;
1190 + const crashed = cur.filter((r) => r.status === "crash").length;
1191 + const checksFailed = cur.filter((r) => r.status === "checks_failed").length;
1192 + const baseline = state.bestMetric;
1193 + const baselineSec = findBaselineSecondary(
1194 + state.results,
1195 + state.currentSegment,
1196 + state.secondaryMetrics,
1197 + );
1199 + let bestPrimary: number | null = null;
1200 + let bestSec: Record<string, number> = {};
1201 + let bestRunNum = 0;
1202 + for (let i = state.results.length - 1; i >= 0; i--) {
1203 + const r = state.results[i];
1204 + if (r.segment !== state.currentSegment) continue;
1205 + if (r.status === "keep" && r.metric > 0) {
1206 + if (bestPrimary === null || isBetter(r.metric, bestPrimary, state.bestDirection)) {
1207 + bestPrimary = r.metric;
1208 + bestSec = r.metrics ?? {};
1209 + bestRunNum = i + 1;
1214 + const displayVal = bestPrimary ?? baseline;
1215 + const essential = [
1216 + theme.fg("accent", "🔬"),
1217 + theme.fg("muted", ` ${state.results.length} runs`),
1218 + theme.fg("success", ` ${kept} kept`),
1219 + theme.fg("dim", " │ "),
1220 + theme.fg(
1221 + "warning",
1222 + theme.bold(`★ ${state.metricName}: ${formatNum(displayVal, state.metricUnit)}`),
1223 + ),
1224 + bestRunNum > 0 ? theme.fg("dim", ` #${bestRunNum}`) : "",
1225 + ];
1227 + const optional: string[] = [];
1228 + if (crashed > 0) optional.push(theme.fg("error", ` ${crashed}💥`));
1229 + if (checksFailed > 0)
1230 + optional.push(theme.fg("error", ` ${checksFailed}⚠`));
1232 + if (
1233 + baseline !== null &&
1234 + bestPrimary !== null &&
1235 + baseline !== 0 &&
1236 + bestPrimary !== baseline
1237 + ) {
1238 + const pct = ((bestPrimary - baseline) / baseline) * 100;
1239 + const sign = pct > 0 ? "+" : "";
1240 + const deltaColor = isBetter(bestPrimary, baseline, state.bestDirection)
1241 + ? "success"
1242 + : "error";
1243 + optional.push(theme.fg(deltaColor, ` (${sign}${pct.toFixed(1)}%)`));
1246 + if (state.confidence !== null) {
1247 + const confStr = state.confidence.toFixed(1);
1248 + const confColor: Parameters<typeof theme.fg>[0] =
1249 + state.confidence >= 2.0 ? "success" : state.confidence >= 1.0 ? "warning" : "error";
1250 + optional.push(theme.fg("dim", " │ "));
1251 + optional.push(theme.fg(confColor, `conf: ${confStr}×`));
1254 + if (state.secondaryMetrics.length > 0) {
1255 + for (const sm of state.secondaryMetrics) {
1256 + const val = bestSec[sm.name];
1257 + const bv = baselineSec[sm.name];
1258 + if (val === undefined) continue;
1259 + let secText = `${sm.name}: ${formatNum(val, sm.unit)}`;
1260 + if (bv !== undefined && bv !== 0 && val !== bv) {
1261 + const p = ((val - bv) / bv) * 100;
1262 + const s = p > 0 ? "+" : "";
1263 + const c = val <= bv ? "success" : "error";
1264 + secText += theme.fg(c, ` ${s}${p.toFixed(1)}%`);
1266 + optional.push(theme.fg("dim", " "));
1267 + optional.push(theme.fg("muted", secText));
1268 + break;
1272 + if (state.name) optional.push(theme.fg("dim", ` │ ${state.name}`));
1274 + const left = [...essential, ...optional].join("");
1275 + const hintVariants = dashboardHintVariants("expand");
1276 + return [
1277 + hintVariants.length > 0
1278 + ? appendRightAlignedAdaptiveHint(left, safeWidth, theme, hintVariants)
1279 + : truncateToWidth(left, safeWidth, "…", true),
1280 + ];
1281 + },
1282 + invalidate(): void {},
1283 + }));
1285 + };
1287 + // ── Lifecycle hooks ─────────────────────────────────────────────────
1289 + pi.on("session_start", async (_e, ctx) => reconstructState(ctx));
1290 + pi.on("session_tree", async (_e, ctx) => reconstructState(ctx));
1291 + pi.on("session_before_switch", async () => clearOverlay());
1292 + pi.on("session_shutdown", async (_e, ctx) => {
1293 + clearSessionUi(ctx);
1294 + cancelPendingResume(getRuntime(ctx));
1295 + runtimeStore.clear(getSessionKey(ctx));
1296 + stopDashboardServer();
1297 + });
1299 + pi.on("agent_start", async (_event, ctx) => {
1300 + const runtime = getRuntime(ctx);
1301 + runtime.experimentsThisSession = 0;
1302 + pausePendingResume(runtime);
1303 + });
1305 + const ensurePendingResume = (
1306 + ctx: ExtensionContext,
1307 + gate: (runtime: AutoresearchRuntime) => boolean,
1308 + composeMessage: (ctx: ExtensionContext) => string = composeResumeMessage,
1309 + ): void => {
1310 + const runtime = getRuntime(ctx);
1311 + if (hasPendingResume(runtime)) {
1312 + reschedulePendingResume(ctx, runtime);
1313 + return;
1315 + if (!gate(runtime)) return;
1316 + if (hasReachedAutoResumeLimit(runtime)) {
1317 + notifyAutoResumeLimitReached(ctx);
1318 + return;
1320 + schedulePendingResume(ctx, runtime, composeMessage(ctx));
1321 + };
1323 + pi.on("session_before_compact", async (event, ctx) => {
1324 + pausePendingResume(getRuntime(ctx));
1325 + return autoresearchCompactionFor(ctx, event);
1326 + });
1328 + pi.on("session_compact", async (_event, ctx) => {
1329 + ensurePendingResume(ctx, shouldAutoResumeAfterCompact, composeCompactionResumeMessage);
1330 + });
1332 + pi.on("agent_end", async (_event, ctx) => {
1333 + const runtime = getRuntime(ctx);
1334 + runtime.runningExperiment = null;
1335 + if (overlayTui) overlayTui.requestRender();
1336 + ensurePendingResume(ctx, shouldAutoResumeAfterTurn);
1337 + });
1339 + pi.on("before_agent_start", async (event, ctx) => {
1340 + const runtime = getRuntime(ctx);
1341 + if (!runtime.autoresearchMode) return;
1343 + const mdPath = autoresearchMdPath(ctx.cwd);
1344 + const ideasPath = autoresearchIdeasPath(ctx.cwd);
1345 + const hasIdeas = fs.existsSync(ideasPath);
1346 + const checksPath = autoresearchChecksPath(ctx.cwd);
1347 + const hasChecks = fs.existsSync(checksPath);
1349 + let extra =
1350 + "\n\n## Autoresearch Mode (ACTIVE)" +
1351 + "\nYou are in autoresearch mode. Optimize the primary metric through an autonomous experiment loop." +
1352 + "\nUse init_experiment, run_experiment, and log_experiment tools. NEVER STOP until interrupted." +
1353 + `\nExperiment rules: ${mdPath} — read this file at the start of every session and after compaction.` +
1354 + "\nWrite promising but deferred optimizations as bullet points to ideas.md — don't let good ideas get lost." +
1355 + `\n${BENCHMARK_GUARDRAIL}` +
1356 + "\nIf the user sends a follow-on message while an experiment is running, finish the current run_experiment + log_experiment cycle first, then address their message in the next iteration.";
1358 + if (hasChecks) {
1359 + extra +=
1360 + "\n\n## Backpressure Checks (ACTIVE)" +
1361 + `\n${checksPath} exists and runs automatically after every passing benchmark in run_experiment.` +
1362 + "\nIf the benchmark passes but checks fail, run_experiment will report it clearly." +
1363 + "\nUse status 'checks_failed' in log_experiment — it behaves like a crash (no commit, changes auto-reverted)." +
1364 + "\nYou cannot use status 'keep' when checks have failed." +
1365 + "\nThe checks execution time does NOT affect the primary metric.";
1368 + if (hasIdeas) {
1369 + extra += `\n\n💡 Ideas backlog exists at ${ideasPath} — check it for promising experiment paths.`;
1372 + return { systemPrompt: event.systemPrompt + extra };
1373 + });
1375 + // ── init_experiment tool ────────────────────────────────────────────
1377 + pi.registerTool({
1378 + name: "init_experiment",
1379 + label: "Init Experiment",
1380 + description:
1381 + "Initialize the experiment session. Call once before the first run_experiment.",
1382 + promptSnippet: "Initialize experiment session (name, metric, unit, direction).",
1383 + promptGuidelines: [
1384 + "Call init_experiment exactly once at the start of an autoresearch session.",
1385 + "If session.jsonl already exists with a config, do NOT call init_experiment again.",
1386 + "If the optimization target changes, call init_experiment again to insert a new config header.",
1387 + ],
1388 + parameters: InitParams,
1390 + async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
1391 + const runtime = getRuntime(ctx);
1392 + const state = runtime.state;
1393 + const isReinit = state.results.length > 0;
1395 + state.name = params.name;
1396 + state.metricName = params.metric_name;
1397 + state.metricUnit = params.metric_unit ?? "";
1398 + if (params.direction === "lower" || params.direction === "higher") {
1399 + state.bestDirection = params.direction;
1401 + if (isReinit) state.currentSegment++;
1402 + state.bestMetric = null;
1403 + state.secondaryMetrics = [];
1404 + state.confidence = null;
1405 + state.maxExperiments = readMaxExperiments(ctx.cwd);
1407 + // Ensure state directory exists
1408 + const dir = stateDir(ctx.cwd);
1409 + fs.mkdirSync(dir, { recursive: true });
1411 + try {
1412 + const jsonlPath = autoresearchJsonlPath(ctx.cwd);
1413 + const config = JSON.stringify({
1414 + type: "config",
1415 + name: state.name,
1416 + metricName: state.metricName,
1417 + metricUnit: state.metricUnit,
1418 + bestDirection: state.bestDirection,
1419 + });
1420 + if (fs.existsSync(jsonlPath)) {
1421 + fs.appendFileSync(jsonlPath, config + "\n");
1422 + } else {
1423 + fs.writeFileSync(jsonlPath, config + "\n");
1425 + broadcastDashboardUpdate(ctx.cwd);
1426 + } catch (e) {
1427 + return {
1428 + content: [
1430 + type: "text",
1431 + text: `⚠️ Failed to write session.jsonl: ${e instanceof Error ? e.message : String(e)}`,
1432 + },
1433 + ],
1434 + details: {},
1435 + };
1438 + const wasInactive = !runtime.autoresearchMode;
1439 + runtime.autoresearchMode = true;
1440 + updateWidget(ctx);
1442 + if (wasInactive) {
1443 + const steer = await fireHook({
1444 + event: "before",
1445 + cwd: ctx.cwd,
1446 + next_run: state.results.length + 1,
1447 + last_run: readLastRun(ctx.cwd),
1448 + session: buildSessionSnapshot(state),
1449 + });
1450 + if (steer) pi.sendUserMessage(steer, { deliverAs: "steer" });
1453 + const reinitNote = isReinit
1454 + ? " (re-initialized — previous results archived, new baseline needed)"
1455 + : "";
1456 + const limitNote =
1457 + state.maxExperiments !== null
1458 + ? `\nMax iterations: ${state.maxExperiments} (from config.json)`
1459 + : "";
1460 + return {
1461 + content: [
1463 + type: "text",
1464 + text: `✅ Experiment initialized: "${state.name}"${reinitNote}\nMetric: ${state.metricName} (${state.metricUnit || "unitless"}, ${state.bestDirection} is better)${limitNote}\nState dir: .pi/autoresearch/\nConfig written to session.jsonl. Now run the baseline with run_experiment.`,
1465 + },
1466 + ],
1467 + details: { state: cloneExperimentState(state) },
1468 + };
1469 + },
1471 + renderCall(args, theme) {
1472 + return new Text(
1473 + theme.fg("toolTitle", theme.bold("init_experiment ")) +
1474 + theme.fg("accent", args.name ?? ""),
1475 + 0,
1476 + 0,
1477 + );
1478 + },
1480 + renderResult(result, _options, theme) {
1481 + const t = result.content[0];
1482 + return new Text(t?.type === "text" ? t.text : "", 0, 0);
1483 + },
1484 + });
1486 + // ── run_experiment tool ─────────────────────────────────────────────
1488 + pi.registerTool({
1489 + name: "run_experiment",
1490 + label: "Run Experiment",
1491 + description: `Run a shell command as an experiment. Times wall-clock duration, captures output, detects pass/fail. Output truncated to last ${EXPERIMENT_MAX_LINES} lines or ${EXPERIMENT_MAX_BYTES / 1024}KB.`,
1492 + promptSnippet: "Run a timed experiment command",
1493 + promptGuidelines: [
1494 + "Use run_experiment instead of bash for experiment commands.",
1495 + "After run_experiment, always call log_experiment to record the result.",
1496 + "If the benchmark script outputs METRIC lines, run_experiment parses them automatically.",
1497 + ],
1498 + parameters: RunParams,
1500 + async execute(_toolCallId, params, signal, onUpdate, ctx) {
1501 + const runtime = getRuntime(ctx);
1502 + const state = runtime.state;
1503 + const cwd = ctx.cwd;
1505 + // Block if max experiments reached
1506 + if (state.maxExperiments !== null) {
1507 + const segCount = currentResults(state.results, state.currentSegment).length;
1508 + if (segCount >= state.maxExperiments) {
1509 + return {
1510 + content: [
1512 + type: "text",
1513 + text: `🛑 Maximum experiments reached (${state.maxExperiments}). Call init_experiment to start a new segment.`,
1514 + },
1515 + ],
1516 + details: {},
1517 + };
1521 + // Guard: if benchmark.mjs exists, only allow running it
1522 + const benchmarkPath = autoresearchScriptPath(cwd);
1523 + if (fs.existsSync(benchmarkPath) && !isBenchmarkCommand(params.command)) {
1524 + return {
1525 + content: [
1527 + type: "text",
1528 + text: `❌ benchmark.mjs exists — you must run it instead of a custom command.\n\nFound: ${benchmarkPath}\nYour command: ${params.command}\n\nUse: run_experiment({ command: "node .pi/autoresearch/benchmark.mjs" })`,
1529 + },
1530 + ],
1531 + details: {
1532 + command: params.command,
1533 + exitCode: null,
1534 + durationSeconds: 0,
1535 + passed: false,
1536 + crashed: true,
1537 + timedOut: false,
1538 + tailOutput: "",
1539 + checksPass: null,
1540 + checksTimedOut: false,
1541 + checksOutput: "",
1542 + checksDuration: 0,
1543 + } as RunDetails,
1544 + };
1547 + runtime.runningExperiment = { startedAt: Date.now(), command: params.command };
1548 + updateWidget(ctx);
1549 + if (overlayTui) overlayTui.requestRender();
1551 + const timeout = (params.timeout_seconds ?? 600) * 1000;
1552 + const t0 = Date.now();
1553 + const getTempFile = createTempFileAllocator();
1555 + const {
1556 + exitCode,
1557 + killed: timedOut,
1558 + output,
1559 + tempFilePath: streamTempFile,
1560 + actualTotalBytes,
1561 + } = await new Promise<{
1562 + exitCode: number | null;
1563 + killed: boolean;
1564 + output: string;
1565 + tempFilePath: string | undefined;
1566 + actualTotalBytes: number;
1567 + }>((resolve, reject) => {
1568 + let processTimedOut = false;
1570 + const child = spawn("bash", ["-c", params.command], {
1571 + cwd,
1572 + detached: true,
1573 + stdio: ["ignore", "pipe", "pipe"],
1574 + });
1576 + const chunks: Buffer[] = [];
1577 + let chunksBytes = 0;
1578 + const maxChunksBytes = DEFAULT_MAX_BYTES * 2;
1579 + let tempFilePath: string | undefined;
1580 + let tempFileStream: ReturnType<typeof createWriteStream> | undefined;
1581 + let totalBytes = 0;
1582 + let chunksGeneration = 0;
1583 + let cachedGeneration = -1;
1584 + let cachedText = "";
1586 + function getBufferText(): string {
1587 + if (cachedGeneration === chunksGeneration) return cachedText;
1588 + cachedText = Buffer.concat(chunks).toString("utf-8");
1589 + cachedGeneration = chunksGeneration;
1590 + return cachedText;
1593 + const timerInterval = setInterval(() => {
1594 + if (!onUpdate) return;
1595 + const elapsed = formatElapsed(Date.now() - t0);
1596 + const trunc = truncateTail(getBufferText(), {
1597 + maxLines: DEFAULT_MAX_LINES,
1598 + maxBytes: DEFAULT_MAX_BYTES,
1599 + });
1600 + onUpdate({
1601 + content: [{ type: "text", text: trunc.content || "" }],
1602 + details: {
1603 + phase: "running",
1604 + elapsed,
1605 + truncation: trunc.truncated ? trunc : undefined,
1606 + fullOutputPath: tempFilePath,
1607 + },
1608 + });
1609 + }, 1000);
1611 + const handleData = (data: Buffer) => {
1612 + totalBytes += data.length;
1613 + if (totalBytes > DEFAULT_MAX_BYTES && !tempFilePath) {
1614 + tempFilePath = getTempFile();
1615 + tempFileStream = createWriteStream(tempFilePath);
1616 + for (const chunk of chunks) tempFileStream.write(chunk);
1618 + if (tempFileStream) tempFileStream.write(data);
1620 + chunks.push(data);
1621 + chunksBytes += data.length;
1622 + while (chunksBytes > maxChunksBytes && chunks.length > 1) {
1623 + const removed = chunks.shift()!;
1624 + chunksBytes -= removed.length;
1626 + if (chunks.length > 0 && chunksBytes > maxChunksBytes) {
1627 + const buf = chunks[0];
1628 + const nlIdx = buf.indexOf(0x0a);
1629 + if (nlIdx !== -1 && nlIdx < buf.length - 1) {
1630 + chunks[0] = buf.subarray(nlIdx + 1);
1631 + chunksBytes -= nlIdx + 1;
1634 + chunksGeneration++;
1635 + };
1637 + if (child.stdout) child.stdout.on("data", handleData);
1638 + if (child.stderr) child.stderr.on("data", handleData);
1640 + let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
1641 + if (timeout > 0) {
1642 + timeoutHandle = setTimeout(() => {
1643 + processTimedOut = true;
1644 + if (child.pid) killTree(child.pid);
1645 + }, timeout);
1648 + const onAbort = () => {
1649 + if (child.pid) killTree(child.pid);
1650 + else {
1651 + child.kill();
1652 + child.once("spawn", () => {
1653 + if (child.pid) killTree(child.pid);
1654 + });
1656 + };
1657 + if (signal) {
1658 + if (signal.aborted) onAbort();
1659 + else signal.addEventListener("abort", onAbort, { once: true });
1662 + child.on("error", (err) => {
1663 + clearInterval(timerInterval);
1664 + if (timeoutHandle) clearTimeout(timeoutHandle);
1665 + if (signal) signal.removeEventListener("abort", onAbort);
1666 + if (tempFileStream) tempFileStream.end();
1667 + reject(err);
1668 + });
1670 + child.on("close", (code) => {
1671 + clearInterval(timerInterval);
1672 + if (timeoutHandle) clearTimeout(timeoutHandle);
1673 + if (signal) signal.removeEventListener("abort", onAbort);
1674 + if (tempFileStream) tempFileStream.end();
1676 + if (signal?.aborted) {
1677 + reject(new Error("aborted"));
1678 + return;
1681 + const fullBuffer = Buffer.concat(chunks);
1682 + resolve({
1683 + exitCode: code,
1684 + killed: processTimedOut,
1685 + output: fullBuffer.toString("utf-8"),
1686 + tempFilePath,
1687 + actualTotalBytes: totalBytes,
1688 + });
1689 + });
1690 + }).finally(() => {
1691 + runtime.runningExperiment = null;
1692 + updateWidget(ctx);
1693 + if (overlayTui) overlayTui.requestRender();
1694 + });
1696 + const durationSeconds = (Date.now() - t0) / 1000;
1697 + runtime.lastRunDuration = durationSeconds;
1698 + const benchmarkPassed = exitCode === 0 && !timedOut;
1700 + // Run backpressure checks
1701 + let checksPass: boolean | null = null;
1702 + let checksTimedOut = false;
1703 + let checksOutput = "";
1704 + let checksDuration = 0;
1706 + const checksPath = autoresearchChecksPath(cwd);
1707 + if (benchmarkPassed && fs.existsSync(checksPath)) {
1708 + const checksTimeout = (params.checks_timeout_seconds ?? 300) * 1000;
1709 + const ct0 = Date.now();
1710 + try {
1711 + const checksResult = await pi.exec("node", [checksPath], {
1712 + signal,
1713 + timeout: checksTimeout,
1714 + cwd,
1715 + });
1716 + checksDuration = (Date.now() - ct0) / 1000;
1717 + checksTimedOut = !!checksResult.killed;
1718 + checksPass = checksResult.code === 0 && !checksResult.killed;
1719 + checksOutput = (checksResult.stdout + "\n" + checksResult.stderr).trim();
1720 + } catch (e) {
1721 + checksDuration = (Date.now() - ct0) / 1000;
1722 + checksPass = false;
1723 + checksOutput = e instanceof Error ? e.message : String(e);
1727 + runtime.lastRunChecks =
1728 + checksPass !== null
1729 + ? { pass: checksPass, output: checksOutput, duration: checksDuration }
1730 + : null;
1732 + const passed = benchmarkPassed && (checksPass === null || checksPass);
1734 + let fullOutputPath: string | undefined = streamTempFile;
1735 + const totalLines = output.split("\n").length;
1736 + if (
1737 + !fullOutputPath &&
1738 + (actualTotalBytes > EXPERIMENT_MAX_BYTES || totalLines > EXPERIMENT_MAX_LINES)
1739 + ) {
1740 + fullOutputPath = getTempFile();
1741 + fs.writeFileSync(fullOutputPath, output);
1744 + const displayTruncation = truncateTail(output, {
1745 + maxLines: DEFAULT_MAX_LINES,
1746 + maxBytes: DEFAULT_MAX_BYTES,
1747 + });
1748 + const llmTruncation = truncateTail(output, {
1749 + maxLines: EXPERIMENT_MAX_LINES,
1750 + maxBytes: EXPERIMENT_MAX_BYTES,
1751 + });
1753 + const parsedMetricMap = parseMetricLines(output);
1754 + const parsedMetrics =
1755 + parsedMetricMap.size > 0 ? Object.fromEntries(parsedMetricMap) : null;
1756 + const parsedPrimary = parsedMetricMap.get(state.metricName) ?? null;
1758 + const details: RunDetails = {
1759 + command: params.command,
1760 + exitCode,
1761 + durationSeconds,
1762 + passed,
1763 + crashed: !passed,
1764 + timedOut,
1765 + tailOutput: displayTruncation.content,
1766 + checksPass,
1767 + checksTimedOut,
1768 + checksOutput: checksOutput.split("\n").slice(-80).join("\n"),
1769 + checksDuration,
1770 + parsedMetrics,
1771 + parsedPrimary,
1772 + metricName: state.metricName,
1773 + metricUnit: state.metricUnit,
1774 + };
1776 + let text = "";
1777 + if (details.timedOut) {
1778 + text += `⏰ TIMEOUT after ${durationSeconds.toFixed(1)}s\n`;
1779 + } else if (!benchmarkPassed) {
1780 + text += `💥 FAILED (exit code ${exitCode}) in ${durationSeconds.toFixed(1)}s\n`;
1781 + } else if (checksTimedOut) {
1782 + text += `✅ Benchmark PASSED in ${durationSeconds.toFixed(1)}s\n`;
1783 + text += `⏰ CHECKS TIMEOUT after ${checksDuration.toFixed(1)}s\n`;
1784 + } else if (checksPass === false) {
1785 + text += `✅ Benchmark PASSED in ${durationSeconds.toFixed(1)}s\n`;
1786 + text += `💥 CHECKS FAILED in ${checksDuration.toFixed(1)}s\n`;
1787 + } else {
1788 + text += `✅ PASSED in ${durationSeconds.toFixed(1)}s\n`;
1789 + if (checksPass === true)
1790 + text += `✅ Checks passed in ${checksDuration.toFixed(1)}s\n`;
1793 + if (state.bestMetric !== null) {
1794 + text += `📊 Current best ${state.metricName}: ${formatNum(state.bestMetric, state.metricUnit)}\n`;
1797 + if (parsedMetrics) {
1798 + const secondary = Object.entries(parsedMetrics).filter(
1799 + ([k]) => k !== state.metricName,
1800 + );
1801 + text += `\n📐 Parsed metrics:`;
1802 + if (parsedPrimary !== null) {
1803 + text += ` ★ ${state.metricName}=${formatNum(parsedPrimary, state.metricUnit)}`;
1805 + for (const [name, value] of secondary) {
1806 + const sm = state.secondaryMetrics.find((m) => m.name === name);
1807 + text += ` ${name}=${formatNum(value, sm?.unit ?? "")}`;
1809 + text += `\nUse these values directly in log_experiment (metric: ${parsedPrimary ?? "?"}, metrics: {${secondary.map(([k, v]) => `"${k}": ${v}`).join(", ")}})\n`;
1812 + text += `\n${llmTruncation.content}`;
1814 + if (llmTruncation.truncated) {
1815 + if (llmTruncation.truncatedBy === "lines") {
1816 + text += `\n\n[Showing last ${llmTruncation.outputLines} of ${llmTruncation.totalLines} lines.`;
1817 + } else {
1818 + text += `\n\n[Showing last ${llmTruncation.outputLines} lines (${formatSize(EXPERIMENT_MAX_BYTES)} limit).`;
1820 + if (fullOutputPath) text += ` Full output: ${fullOutputPath}`;
1821 + text += `]`;
1824 + if (checksPass === false) {
1825 + text += `\n\n── Checks output (last 80 lines) ──\n${details.checksOutput}`;
1828 + return {
1829 + content: [{ type: "text", text }],
1830 + details: {
1831 + ...details,
1832 + truncation: llmTruncation.truncated ? llmTruncation : undefined,
1833 + fullOutputPath,
1834 + },
1835 + };
1836 + },
1838 + renderCall(args, theme) {
1839 + let text = theme.fg("toolTitle", theme.bold("run_experiment "));
1840 + text += theme.fg("muted", args.command);
1841 + if (args.timeout_seconds)
1842 + text += theme.fg("dim", ` (timeout: ${args.timeout_seconds}s)`);
1843 + return new Text(text, 0, 0);
1844 + },
1846 + renderResult(result, { expanded, isPartial }, theme) {
1847 + const PREVIEW_LINES = 5;
1849 + if (isPartial) {
1850 + const d = result.details as
1851 + | { phase?: string; elapsed?: string }
1852 + | undefined;
1853 + const elapsed = d?.elapsed ?? "";
1854 + const outputText =
1855 + result.content[0]?.type === "text" ? result.content[0].text : "";
1856 + let text = theme.fg("warning", `⏳ Running${elapsed ? ` ${elapsed}` : ""}…`);
1857 + if (outputText) {
1858 + const lines = outputText.split("\n");
1859 + const maxLines = expanded ? 20 : PREVIEW_LINES;
1860 + const tail = lines.slice(-maxLines).join("\n");
1861 + if (tail.trim()) text += "\n" + theme.fg("dim", tail);
1863 + return new Text(text, 0, 0);
1866 + const d = result.details as
1867 + | (RunDetails & { truncation?: any; fullOutputPath?: string })
1868 + | undefined;
1869 + if (!d) {
1870 + const t = result.content[0];
1871 + return new Text(t?.type === "text" ? t.text : "", 0, 0);
1874 + const appendOutput = (text: string, output: string): string => {
1875 + if (!output) return text;
1876 + const lines = output.split("\n");
1877 + if (expanded) {
1878 + text += "\n" + theme.fg("dim", output.slice(-2000));
1879 + } else {
1880 + const tail = lines.slice(-PREVIEW_LINES).join("\n");
1881 + if (tail.trim()) {
1882 + const hidden = lines.length - PREVIEW_LINES;
1883 + if (hidden > 0) text += "\n" + theme.fg("muted", `… ${hidden} more lines`);
1884 + text += "\n" + theme.fg("dim", tail);
1887 + return text;
1888 + };
1890 + if (d.timedOut) {
1891 + return new Text(
1892 + appendOutput(
1893 + theme.fg("error", `⏰ TIMEOUT ${d.durationSeconds.toFixed(1)}s`),
1894 + d.tailOutput,
1895 + ),
1896 + 0,
1897 + 0,
1898 + );
1901 + const parsedSuffix =
1902 + d.parsedPrimary !== null
1903 + ? theme.fg(
1904 + "accent",
1905 + `, ${d.metricName}: ${formatNum(d.parsedPrimary, d.metricUnit)}`,
1907 + : "";
1909 + if (d.checksTimedOut) {
1910 + return new Text(
1911 + theme.fg("success", `✅ wall: ${d.durationSeconds.toFixed(1)}s`) +
1912 + parsedSuffix +
1913 + theme.fg("error", ` ⏰ checks timeout ${d.checksDuration.toFixed(1)}s`),
1914 + 0,
1915 + 0,
1916 + );
1919 + if (d.checksPass === false) {
1920 + return new Text(
1921 + theme.fg("success", `✅ wall: ${d.durationSeconds.toFixed(1)}s`) +
1922 + parsedSuffix +
1923 + theme.fg("error", ` 💥 checks failed ${d.checksDuration.toFixed(1)}s`),
1924 + 0,
1925 + 0,
1926 + );
1929 + if (d.crashed) {
1930 + return new Text(
1931 + appendOutput(
1932 + theme.fg("error", `💥 FAIL exit=${d.exitCode} ${d.durationSeconds.toFixed(1)}s`) +
1933 + parsedSuffix,
1934 + d.tailOutput,
1935 + ),
1936 + 0,
1937 + 0,
1938 + );
1941 + let text = theme.fg("success", "✅ ");
1942 + const parts: string[] = [`wall: ${d.durationSeconds.toFixed(1)}s`];
1943 + if (d.parsedPrimary !== null)
1944 + parts.push(`${d.metricName}: ${formatNum(d.parsedPrimary, d.metricUnit)}`);
1945 + text += theme.fg("accent", parts.join(", "));
1946 + if (d.checksPass === true)
1947 + text += theme.fg("success", ` ✓ checks ${d.checksDuration.toFixed(1)}s`);
1949 + text = appendOutput(text, d.tailOutput);
1950 + return new Text(text, 0, 0);
1951 + },
1952 + });
1954 + // ── log_experiment tool ─────────────────────────────────────────────
1956 + pi.registerTool({
1957 + name: "log_experiment",
1958 + label: "Log Experiment",
1959 + description:
1960 + "Record an experiment result. Tracks metrics, updates widget and dashboard. Call after every run_experiment.",
1961 + promptSnippet: "Log experiment result",
1962 + promptGuidelines: [
1963 + "Always call log_experiment after run_experiment.",
1964 + "log_experiment auto-commits on 'keep', auto-reverts on 'discard'/'crash'/'checks_failed'.",
1965 + "Use status 'keep' if PRIMARY metric improved. 'discard' if worse. 'crash' if failed.",
1966 + "Always include the asi parameter with at minimum {\"hypothesis\": \"what you tried\"}.",
1967 + ],
1968 + parameters: LogParams,
1970 + async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
1971 + const runtime = getRuntime(ctx);
1972 + const state = runtime.state;
1973 + const cwd = ctx.cwd;
1974 + const secondaryMetrics = params.metrics ?? {};
1976 + // Gate: prevent "keep" when checks failed
1977 + if (params.status === "keep" && runtime.lastRunChecks && !runtime.lastRunChecks.pass) {
1978 + return {
1979 + content: [
1981 + type: "text",
1982 + text: `❌ Cannot keep — checks.mjs failed.\n\n${runtime.lastRunChecks.output.slice(-500)}\n\nLog as 'checks_failed' instead.`,
1983 + },
1984 + ],
1985 + details: {},
1986 + };
1989 + // Validate secondary metrics
1990 + if (state.secondaryMetrics.length > 0) {
1991 + const knownNames = new Set(state.secondaryMetrics.map((m) => m.name));
1992 + const providedNames = new Set(Object.keys(secondaryMetrics));
1993 + const missing = [...knownNames].filter((n) => !providedNames.has(n));
1994 + if (missing.length > 0) {
1995 + return {
1996 + content: [
1998 + type: "text",
1999 + text: `❌ Missing secondary metrics: ${missing.join(", ")}\nExpected: ${[...knownNames].join(", ")}`,
2000 + },
2001 + ],
2002 + details: {},
2003 + };
2005 + const newMetrics = [...providedNames].filter((n) => !knownNames.has(n));
2006 + if (newMetrics.length > 0 && !params.force) {
2007 + return {
2008 + content: [
2010 + type: "text",
2011 + text: `❌ New secondary metric(s): ${newMetrics.join(", ")}\nUse force: true to add.`,
2012 + },
2013 + ],
2014 + details: {},
2015 + };
2019 + const mergedASI =
2020 + params.asi && Object.keys(params.asi).length > 0
2021 + ? (params.asi as ASI)
2022 + : undefined;
2024 + const experiment: ExperimentResult = {
2025 + commit: params.commit.slice(0, 7),
2026 + metric: params.metric,
2027 + metrics: secondaryMetrics,
2028 + status: params.status,
2029 + description: params.description,
2030 + timestamp: Date.now(),
2031 + segment: state.currentSegment,
2032 + confidence: null,
2033 + asi: mergedASI,
2034 + };
2036 + state.results.push(experiment);
2037 + runtime.experimentsThisSession++;
2039 + // Register new secondary metrics
2040 + for (const name of Object.keys(secondaryMetrics)) {
2041 + if (!state.secondaryMetrics.find((m) => m.name === name)) {
2042 + let unit = "";
2043 + if (name.endsWith("µs")) unit = "µs";
2044 + else if (name.endsWith("_ms")) unit = "ms";
2045 + else if (name.endsWith("_s") || name.endsWith("_sec")) unit = "s";
2046 + else if (name.endsWith("_kb")) unit = "kb";
2047 + else if (name.endsWith("_mb")) unit = "mb";
2048 + state.secondaryMetrics.push({ name, unit });
2052 + state.bestMetric = findBaselineMetric(state.results, state.currentSegment);
2053 + state.confidence = computeConfidence(
2054 + state.results,
2055 + state.currentSegment,
2056 + state.bestDirection,
2057 + );
2058 + experiment.confidence = state.confidence;
2060 + const segmentCount = currentResults(state.results, state.currentSegment).length;
2061 + let text = `Logged #${state.results.length}: ${experiment.status} — ${experiment.description}`;
2063 + if (state.bestMetric !== null) {
2064 + text += `\nBaseline ${state.metricName}: ${formatNum(state.bestMetric, state.metricUnit)}`;
2065 + if (segmentCount > 1 && params.status === "keep" && params.metric > 0) {
2066 + const delta = params.metric - state.bestMetric;
2067 + const pct = ((delta / state.bestMetric) * 100).toFixed(1);
2068 + const sign = delta > 0 ? "+" : "";
2069 + text += ` | this: ${formatNum(params.metric, state.metricUnit)} (${sign}${pct}%)`;
2073 + if (Object.keys(secondaryMetrics).length > 0) {
2074 + const baselines = findBaselineSecondary(
2075 + state.results,
2076 + state.currentSegment,
2077 + state.secondaryMetrics,
2078 + );
2079 + const parts: string[] = [];
2080 + for (const [name, value] of Object.entries(secondaryMetrics)) {
2081 + const def = state.secondaryMetrics.find((m) => m.name === name);
2082 + let part = `${name}: ${formatNum(value, def?.unit ?? "")}`;
2083 + const bv = baselines[name];
2084 + if (bv !== undefined && state.results.length > 1 && bv !== 0) {
2085 + const d = value - bv;
2086 + const p = ((d / bv) * 100).toFixed(1);
2087 + const s = d > 0 ? "+" : "";
2088 + part += ` (${s}${p}%)`;
2090 + parts.push(part);
2092 + text += `\nSecondary: ${parts.join(" ")}`;
2095 + if (mergedASI) {
2096 + const asiParts: string[] = [];
2097 + for (const [k, v] of Object.entries(mergedASI)) {
2098 + const s = typeof v === "string" ? v : JSON.stringify(v);
2099 + asiParts.push(`${k}: ${s.length > 80 ? s.slice(0, 77) + "…" : s}`);
2101 + if (asiParts.length > 0) text += `\n📋 ASI: ${asiParts.join(" | ")}`;
2104 + if (state.confidence !== null) {
2105 + const confStr = state.confidence.toFixed(1);
2106 + if (state.confidence >= 2.0)
2107 + text += `\n📊 Confidence: ${confStr}× — improvement is likely real`;
2108 + else if (state.confidence >= 1.0)
2109 + text += `\n📊 Confidence: ${confStr}× — above noise but marginal`;
2110 + else
2111 + text += `\n⚠️ Confidence: ${confStr}× — within noise. Consider re-running.`;
2114 + text += `\n(${segmentCount} experiments`;
2115 + if (state.maxExperiments !== null) text += ` / ${state.maxExperiments} max`;
2116 + text += `)`;
2118 + // Auto-commit on keep
2119 + if (params.status === "keep") {
2120 + try {
2121 + const resultData: Record<string, unknown> = {
2122 + status: params.status,
2123 + [state.metricName || "metric"]: params.metric,
2124 + ...secondaryMetrics,
2125 + };
2126 + const commitMsg = `${params.description}\n\nResult: ${JSON.stringify(resultData)}`;
2127 + const execOpts = { cwd, timeout: 10000 };
2129 + const addResult = await pi.exec("git", ["add", "-A"], execOpts);
2130 + if (addResult.code !== 0) {
2131 + const addErr = (addResult.stdout + addResult.stderr).trim();
2132 + throw new Error(`git add failed: ${addErr.slice(0, 200)}`);
2135 + const diffResult = await pi.exec(
2136 + "git",
2137 + ["diff", "--cached", "--quiet"],
2138 + execOpts,
2139 + );
2140 + if (diffResult.code === 0) {
2141 + text += "\n📝 Git: nothing to commit";
2142 + } else {
2143 + const gitResult = await pi.exec(
2144 + "git",
2145 + ["commit", "-m", commitMsg],
2146 + execOpts,
2147 + );
2148 + const gitOutput = (gitResult.stdout + gitResult.stderr).trim();
2149 + if (gitResult.code === 0) {
2150 + text += `\n📝 Git: committed — ${gitOutput.split("\n")[0]}`;
2151 + try {
2152 + const shaResult = await pi.exec(
2153 + "git",
2154 + ["rev-parse", "--short=7", "HEAD"],
2155 + { cwd, timeout: 5000 },
2156 + );
2157 + const newSha = (shaResult.stdout || "").trim();
2158 + if (newSha && newSha.length >= 7) experiment.commit = newSha;
2159 + } catch {
2160 + /* keep original hash */
2162 + } else {
2163 + text += `\n⚠️ Git commit failed: ${gitOutput.slice(0, 200)}`;
2166 + } catch (e) {
2167 + text += `\n⚠️ Git error: ${e instanceof Error ? e.message : String(e)}`;
2171 + // Append to JSONL
2172 + const jsonlEntry: Record<string, unknown> = {
2173 + run: state.results.length,
2174 + ...experiment,
2175 + };
2176 + if (!mergedASI) delete jsonlEntry.asi;
2177 + try {
2178 + fs.appendFileSync(autoresearchJsonlPath(cwd), JSON.stringify(jsonlEntry) + "\n");
2179 + broadcastDashboardUpdate(cwd);
2180 + } catch (e) {
2181 + text += `\n⚠️ Failed to write session.jsonl: ${e instanceof Error ? e.message : String(e)}`;
2184 + // Auto-revert on non-keep (preserve .pi/autoresearch/)
2185 + if (params.status !== "keep") {
2186 + try {
2187 + const revertScript = `
2188 + git checkout -- . ':(exclude,glob).pi/autoresearch/**' ':(exclude,glob).pi/autoresearch/*'
2189 + git clean -fd -e '.pi/autoresearch' -e '.pi/autoresearch/**' 2>/dev/null
2190 + `;
2191 + await pi.exec("bash", ["-c", revertScript], { cwd, timeout: 10000 });
2192 + text += `\n📝 Git: reverted changes (${params.status}) — .pi/autoresearch/ preserved`;
2193 + } catch (e) {
2194 + text += `\n⚠️ Git revert failed: ${e instanceof Error ? e.message : String(e)}`;
2198 + // Fire hooks
2199 + const afterSteer = await fireHook({
2200 + event: "after",
2201 + cwd,
2202 + run_entry: jsonlEntry,
2203 + session: buildSessionSnapshot(state),
2204 + });
2205 + if (afterSteer) pi.sendUserMessage(afterSteer, { deliverAs: "steer" });
2207 + const wallClockSeconds = runtime.lastRunDuration;
2208 + runtime.runningExperiment = null;
2209 + runtime.lastRunChecks = null;
2210 + runtime.lastRunDuration = null;
2212 + const limitReached =
2213 + state.maxExperiments !== null && segmentCount >= state.maxExperiments;
2214 + if (limitReached) {
2215 + text += `\n\n🛑 Maximum experiments reached (${state.maxExperiments}). STOP.`;
2216 + runtime.autoresearchMode = false;
2217 + ctx.abort();
2218 + } else if (runtime.autoresearchMode) {
2219 + const beforeSteer = await fireHook({
2220 + event: "before",
2221 + cwd,
2222 + next_run: state.results.length + 1,
2223 + last_run: jsonlEntry,
2224 + session: buildSessionSnapshot(state),
2225 + });
2226 + if (beforeSteer) pi.sendUserMessage(beforeSteer, { deliverAs: "steer" });
2229 + updateWidget(ctx);
2230 + if (overlayTui) overlayTui.requestRender();
2232 + return {
2233 + content: [{ type: "text", text }],
2234 + details: {
2235 + experiment: { ...experiment, metrics: { ...experiment.metrics } },
2236 + state: cloneExperimentState(state),
2237 + wallClockSeconds,
2238 + } as LogDetails,
2239 + };
2240 + },
2242 + renderCall(args, theme) {
2243 + const color =
2244 + args.status === "keep"
2245 + ? "success"
2246 + : args.status === "crash" || args.status === "checks_failed"
2247 + ? "error"
2248 + : "warning";
2249 + return new Text(
2250 + theme.fg("toolTitle", theme.bold("log_experiment ")) +
2251 + theme.fg(color, args.status) +
2252 + " " +
2253 + theme.fg("dim", args.description),
2254 + 0,
2255 + 0,
2256 + );
2257 + },
2259 + renderResult(result, _options, theme) {
2260 + const d = result.details as LogDetails | undefined;
2261 + if (!d) {
2262 + const t = result.content[0];
2263 + return new Text(t?.type === "text" ? t.text : "", 0, 0);
2266 + const { experiment: exp, state: s } = d;
2267 + const color =
2268 + exp.status === "keep"
2269 + ? "success"
2270 + : exp.status === "crash" || exp.status === "checks_failed"
2271 + ? "error"
2272 + : "warning";
2273 + const icon =
2274 + exp.status === "keep"
2275 + ? "✓"
2276 + : exp.status === "crash"
2277 + ? "✗"
2278 + : exp.status === "checks_failed"
2279 + ? "⚠"
2280 + : "–";
2282 + let text =
2283 + theme.fg(color, `${icon} `) + theme.fg("accent", `#${s.results.length}`);
2285 + const metricParts: string[] = [];
2286 + if (d.wallClockSeconds != null)
2287 + metricParts.push(`wall: ${d.wallClockSeconds.toFixed(1)}s`);
2288 + if (exp.metric > 0)
2289 + metricParts.push(`${s.metricName}: ${formatNum(exp.metric, s.metricUnit)}`);
2290 + if (metricParts.length > 0) {
2291 + text +=
2292 + theme.fg("dim", " (") +
2293 + theme.fg("warning", metricParts.join(theme.fg("dim", ", "))) +
2294 + theme.fg("dim", ")");
2297 + text += " " + theme.fg("muted", exp.description);
2299 + if (s.bestMetric !== null) {
2300 + let best = s.bestMetric;
2301 + for (const r of s.results) {
2302 + if (
2303 + r.segment === s.currentSegment &&
2304 + r.status === "keep" &&
2305 + r.metric > 0
2306 + ) {
2307 + if (isBetter(r.metric, best, s.bestDirection)) best = r.metric;
2310 + text +=
2311 + theme.fg("dim", " │ ") +
2312 + theme.fg("warning", `★ best: ${formatNum(best, s.metricUnit)}`);
2315 + if (Object.keys(exp.metrics).length > 0) {
2316 + const parts: string[] = [];
2317 + for (const [name, value] of Object.entries(exp.metrics)) {
2318 + const def = s.secondaryMetrics.find((m) => m.name === name);
2319 + parts.push(`${name}=${formatNum(value, def?.unit ?? "")}`);
2321 + text += theme.fg("dim", ` ${parts.join(" ")}`);
2324 + return new Text(text, 0, 0);
2325 + },
2326 + });
2328 + // ── Shortcuts ───────────────────────────────────────────────────────
2330 + if (shortcuts.toggleDashboard) {
2331 + pi.registerShortcut(shortcuts.toggleDashboard, {
2332 + description: "Toggle autoresearch dashboard",
2333 + handler: async (ctx) => {
2334 + const runtime = getRuntime(ctx);
2335 + if (runtime.state.results.length === 0) {
2336 + ctx.ui.notify("No experiments yet", "info");
2337 + return;
2339 + runtime.dashboardExpanded = !runtime.dashboardExpanded;
2340 + updateWidget(ctx);
2341 + },
2342 + });
2345 + if (shortcuts.fullscreenDashboard) {
2346 + pi.registerShortcut(shortcuts.fullscreenDashboard, {
2347 + description: "Fullscreen autoresearch dashboard",
2348 + handler: async (ctx) => {
2349 + const runtime = getRuntime(ctx);
2350 + const state = runtime.state;
2351 + if (state.results.length === 0) {
2352 + ctx.ui.notify("No experiments yet", "info");
2353 + return;
2356 + await ctx.ui.custom<void>((tui, theme, _kb, done) => {
2357 + let scrollOffset = 0;
2358 + let lastViewportRows = 8;
2359 + let lastTotalRows = 0;
2360 + overlayTui = tui;
2362 + spinnerInterval = setInterval(() => {
2363 + spinnerFrame = (spinnerFrame + 1) % SPINNER.length;
2364 + if (runtime.runningExperiment) tui.requestRender();
2365 + }, 80);
2367 + const buildOverlayContent = (renderWidth: number): string[] => {
2368 + const content = renderDashboardLines(state, renderWidth, theme, 0);
2369 + if (runtime.runningExperiment) {
2370 + const elapsed = formatElapsed(
2371 + Date.now() - runtime.runningExperiment.startedAt,
2372 + );
2373 + const frame = SPINNER[spinnerFrame % SPINNER.length];
2374 + const nextIdx = state.results.length + 1;
2375 + content.push(
2376 + truncateToWidth(
2377 + ` ${theme.fg("dim", String(nextIdx).padEnd(3))}` +
2378 + theme.fg("warning", `${frame} running… ${elapsed}`),
2379 + renderWidth,
2380 + "…",
2381 + true,
2382 + ),
2383 + );
2385 + return content;
2386 + };
2388 + return {
2389 + render(width: number): string[] {
2390 + const { height } = getTuiSize(tui);
2391 + const safeWidth = Math.max(1, width || getTuiSize(tui).width);
2392 + const viewportRows = Math.max(4, height - 4);
2393 + const content = buildOverlayContent(safeWidth);
2394 + const totalRows = content.length;
2395 + const maxScroll = Math.max(0, totalRows - viewportRows);
2396 + scrollOffset = clamp(scrollOffset, 0, maxScroll);
2397 + lastViewportRows = viewportRows;
2398 + lastTotalRows = totalRows;
2400 + const out: string[] = [];
2401 + const title = truncateDisplayText(
2402 + `🔬 autoresearch${state.name ? `: ${state.name}` : ""}`,
2403 + Math.max(0, safeWidth - 5),
2404 + );
2405 + const fillLen = Math.max(
2406 + 0,
2407 + safeWidth - 3 - 1 - visibleWidth(title) - 1,
2408 + );
2409 + out.push(
2410 + truncateToWidth(
2411 + theme.fg("borderMuted", "───") +
2412 + theme.fg("accent", ` ${title} `) +
2413 + theme.fg("borderMuted", "─".repeat(fillLen)),
2414 + safeWidth,
2415 + "…",
2416 + true,
2417 + ),
2418 + );
2420 + const visible = content.slice(scrollOffset, scrollOffset + viewportRows);
2421 + for (const line of visible)
2422 + out.push(truncateToWidth(line, safeWidth, "…", true));
2423 + for (let i = visible.length; i < viewportRows; i++) out.push("");
2425 + const scrollInfo =
2426 + totalRows > viewportRows
2427 + ? ` ${scrollOffset + 1}-${Math.min(scrollOffset + viewportRows, totalRows)}/${totalRows}`
2428 + : "";
2429 + const helpText =
2430 + safeWidth >= 85
2431 + ? ` ↑↓/j/k scroll • pgup/pgdn • g/G • esc close${scrollInfo} `
2432 + : ` j/k scroll • esc close${scrollInfo} `;
2433 + const footFill = Math.max(0, safeWidth - visibleWidth(helpText));
2434 + out.push(
2435 + truncateToWidth(
2436 + theme.fg("borderMuted", "─".repeat(footFill)) +
2437 + theme.fg("dim", helpText),
2438 + safeWidth,
2439 + "…",
2440 + true,
2441 + ),
2442 + );
2443 + return out;
2444 + },
2446 + handleInput(data: string): void {
2447 + const maxScroll = Math.max(0, lastTotalRows - lastViewportRows);
2448 + if (matchesKey(data, "escape") || data === "q") {
2449 + done(undefined);
2450 + return;
2452 + if (matchesKey(data, "up") || data === "k")
2453 + scrollOffset = Math.max(0, scrollOffset - 1);
2454 + else if (matchesKey(data, "down") || data === "j")
2455 + scrollOffset = Math.min(maxScroll, scrollOffset + 1);
2456 + else if (matchesKey(data, "pageUp") || data === "u")
2457 + scrollOffset = Math.max(0, scrollOffset - lastViewportRows);
2458 + else if (matchesKey(data, "pageDown") || data === "d")
2459 + scrollOffset = Math.min(maxScroll, scrollOffset + lastViewportRows);
2460 + else if (data === "g") scrollOffset = 0;
2461 + else if (data === "G") scrollOffset = maxScroll;
2462 + tui.requestRender();
2463 + },
2465 + invalidate(): void {},
2466 + dispose(): void {
2467 + clearOverlay();
2468 + },
2469 + };
2470 + }, {
2471 + overlay: true,
2472 + overlayOptions: {
2473 + width: "95%",
2474 + maxHeight: "90%",
2475 + anchor: "center" as const,
2476 + },
2477 + });
2478 + },
2479 + });
2482 + // ── Export dashboard server ─────────────────────────────────────────
2484 + let dashboardServer: Server | null = null;
2485 + let dashboardServerPort: number | null = null;
2486 + const dashboardSseClients = new Set<ServerResponse>();
2488 + const TITLE_PLACEHOLDER = "__AUTORESEARCH_TITLE__";
2489 + const LOGO_PLACEHOLDER = "__AUTORESEARCH_LOGO__";
2491 + let cachedPackageRoot: string | null = null;
2492 + function packageRoot(): string {
2493 + if (cachedPackageRoot) return cachedPackageRoot;
2494 + const extensionDir = fs.realpathSync(
2495 + path.dirname(fileURLToPath(import.meta.url)),
2496 + );
2497 + cachedPackageRoot = path.resolve(extensionDir, "../..");
2498 + return cachedPackageRoot;
2501 + function readTemplate(): string {
2502 + const templateFile = path.join(packageRoot(), "assets/template.html");
2503 + return fs.existsSync(templateFile) ? fs.readFileSync(templateFile, "utf-8") : "";
2506 + function injectDataIntoTemplate(template: string, title: string): string {
2507 + return template.replace(
2508 + TITLE_PLACEHOLDER,
2509 + () =>
2510 + title
2511 + .replace(/&/g, "&amp;")
2512 + .replace(/</g, "&lt;")
2513 + .replace(/>/g, "&gt;"),
2514 + );
2517 + function broadcastDashboardUpdate(cwd: string): void {
2518 + if (!dashboardServer) return;
2519 + for (const res of dashboardSseClients) {
2520 + try {
2521 + res.write("event: jsonl-updated\n");
2522 + res.write(`data: ${Date.now()}\n\n`);
2523 + } catch {
2524 + dashboardSseClients.delete(res);
2529 + function stopDashboardServer(): void {
2530 + for (const client of dashboardSseClients) {
2531 + try {
2532 + client.end();
2533 + } catch {
2534 + /* ignore */
2537 + dashboardSseClients.clear();
2538 + if (dashboardServer) {
2539 + try {
2540 + dashboardServer.close();
2541 + } catch {
2542 + /* ignore */
2545 + dashboardServer = null;
2546 + dashboardServerPort = null;
2549 + function openInBrowser(url: string): void {
2550 + if (process.platform === "win32") {
2551 + spawn("cmd", ["/c", "start", "", url], { detached: true, shell: true, stdio: "ignore" }).unref();
2552 + return;
2554 + const openCmd = process.platform === "darwin" ? "open" : "xdg-open";
2555 + spawn(openCmd, [url], { detached: true, stdio: "ignore" }).unref();
2558 + async function exportDashboard(ctx: ExtensionContext): Promise<void> {
2559 + const jsonlPath = autoresearchJsonlPath(ctx.cwd);
2560 + if (!fs.existsSync(jsonlPath)) {
2561 + ctx.ui.notify("No session.jsonl found — run some experiments first", "error");
2562 + return;
2565 + try {
2566 + const template = readTemplate();
2567 + if (!template) {
2568 + ctx.ui.notify("No dashboard template found (assets/template.html)", "error");
2569 + return;
2572 + const jsonlContent = fs.readFileSync(jsonlPath, "utf-8").trim();
2573 + const sessionName = extractAutoresearchSessionName(jsonlContent);
2574 + const html = injectDataIntoTemplate(template, sessionName);
2575 + const exportDir = fs.mkdtempSync(path.join(tmpdir(), "pi-autoresearch-dashboard-"));
2576 + const dest = path.join(exportDir, "index.html");
2577 + fs.writeFileSync(dest, html);
2579 + if (!dashboardServer) {
2580 + const server = createServer((req, res) => {
2581 + const url = new URL(req.url ?? "/", "http://127.0.0.1");
2582 + if (url.pathname === "/events") {
2583 + res.writeHead(200, {
2584 + "Content-Type": "text/event-stream",
2585 + "Cache-Control": "no-cache",
2586 + Connection: "keep-alive",
2587 + });
2588 + res.write("retry: 1000\n\n");
2589 + dashboardSseClients.add(res);
2590 + res.on("close", () => dashboardSseClients.delete(res));
2591 + return;
2593 + const filePath =
2594 + url.pathname === "/" ? dest : url.pathname === "/session.jsonl" ? jsonlPath : null;
2595 + if (!filePath) {
2596 + res.writeHead(404);
2597 + res.end();
2598 + return;
2600 + fs.readFile(filePath, (err, data) => {
2601 + if (err) {
2602 + res.writeHead(404);
2603 + res.end();
2604 + return;
2606 + res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
2607 + res.end(data);
2608 + });
2609 + });
2611 + const port = await new Promise<number>((resolve, reject) => {
2612 + server.listen(0, "127.0.0.1", () => {
2613 + const addr = server.address();
2614 + if (!addr || typeof addr === "string") {
2615 + reject(new Error("Failed to bind"));
2616 + return;
2618 + resolve(addr.port);
2619 + });
2620 + server.on("error", reject);
2621 + });
2623 + dashboardServer = server;
2624 + dashboardServerPort = port;
2627 + const url = `http://127.0.0.1:${dashboardServerPort}`;
2628 + openInBrowser(url);
2629 + ctx.ui.notify(`Dashboard at ${url} (live updates)`, "info");
2630 + } catch (error) {
2631 + ctx.ui.notify(
2632 + `Export failed: ${error instanceof Error ? error.message : String(error)}`,
2633 + "error",
2634 + );
2638 + // ── /autoresearch command ───────────────────────────────────────────
2640 + pi.registerCommand("autoresearch", {
2641 + description: "Start, stop, clear, or resume autoresearch mode",
2642 + handler: async (args, ctx) => {
2643 + const runtime = getRuntime(ctx);
2644 + const trimmedArgs = (args ?? "").trim();
2645 + const command = trimmedArgs.toLowerCase();
2647 + if (!trimmedArgs) {
2648 + ctx.ui.notify(autoresearchHelp(), "info");
2649 + return;
2652 + if (command === "off") {
2653 + const wasRunning = !ctx.isIdle();
2654 + runtime.autoresearchMode = false;
2655 + runtime.dashboardExpanded = false;
2656 + runtime.autoResumeTurns = 0;
2657 + runtime.experimentsThisSession = 0;
2658 + runtime.lastRunChecks = null;
2659 + runtime.lastRunDuration = null;
2660 + runtime.runningExperiment = null;
2661 + cancelPendingResume(runtime);
2662 + stopDashboardServer();
2663 + clearSessionUi(ctx);
2664 + if (wasRunning) ctx.abort();
2665 + ctx.ui.notify(
2666 + wasRunning
2667 + ? "Autoresearch mode OFF — aborting current run"
2668 + : "Autoresearch mode OFF",
2669 + "info",
2670 + );
2671 + return;
2674 + if (command === "export") {
2675 + await exportDashboard(ctx);
2676 + return;
2679 + if (command === "clear") {
2680 + const jsonlPath = autoresearchJsonlPath(ctx.cwd);
2681 + runtime.autoresearchMode = false;
2682 + runtime.dashboardExpanded = false;
2683 + runtime.autoResumeTurns = 0;
2684 + runtime.experimentsThisSession = 0;
2685 + runtime.lastRunChecks = null;
2686 + runtime.runningExperiment = null;
2687 + cancelPendingResume(runtime);
2688 + runtime.state = createExperimentState();
2689 + stopDashboardServer();
2690 + updateWidget(ctx);
2692 + if (fs.existsSync(jsonlPath)) {
2693 + try {
2694 + fs.unlinkSync(jsonlPath);
2695 + ctx.ui.notify("Deleted session.jsonl and turned autoresearch OFF", "info");
2696 + } catch (error) {
2697 + ctx.ui.notify(
2698 + `Failed to delete session.jsonl: ${error instanceof Error ? error.message : String(error)}`,
2699 + "error",
2700 + );
2702 + } else {
2703 + ctx.ui.notify("No session.jsonl found. Autoresearch OFF", "info");
2705 + return;
2708 + if (runtime.autoresearchMode) {
2709 + ctx.ui.notify("Already active — use '/autoresearch off' to stop", "info");
2710 + return;
2713 + runtime.autoresearchMode = true;
2714 + runtime.autoResumeTurns = 0;
2716 + const rulesLoaded = hasAutoresearchRules(ctx);
2717 + const kickoff = rulesLoaded
2718 + ? `Autoresearch mode active. ${trimmedArgs} ${BENCHMARK_GUARDRAIL}`
2719 + : `Start autoresearch: ${trimmedArgs} ${BENCHMARK_GUARDRAIL}`;
2721 + ctx.ui.notify(
2722 + rulesLoaded
2723 + ? "Autoresearch ON — rules loaded from session.md"
2724 + : "Autoresearch ON — no session.md found, setting up",
2725 + "info",
2726 + );
2728 + const activationSteer = await fireHook({
2729 + event: "before",
2730 + cwd: ctx.cwd,
2731 + next_run: runtime.state.results.length + 1,
2732 + last_run: readLastRun(ctx.cwd),
2733 + session: buildSessionSnapshot(runtime.state),
2734 + });
2736 + sendWhenReady(
2737 + ctx,
2738 + activationSteer ? `${activationSteer}\n\n${kickoff}` : kickoff,
2739 + );
2740 + },
2741 + });

extensions/autoresearch/jsonl.ts

Added
new file mode 100644
1 +/**
2 + * JSONL session log — parse and reconstruct autoresearch state.
3 + *
4 + * One JSON line per entry. First entry is a `config` header; subsequent
5 + * entries are run results. Segments are delimited by additional config
6 + * headers (re-init).
7 + */
9 +// ── Types ─────────────────────────────────────────────────────────────────
11 +export type JsonlEntry = Record<string, unknown>;
13 +export interface AutoresearchConfigEntry extends JsonlEntry {
14 + type: "config";
15 + name?: string;
16 + metricName?: string;
17 + metricUnit?: string;
18 + bestDirection?: "lower" | "higher";
21 +export interface AutoresearchRunEntry extends JsonlEntry {
22 + run: number;
25 +export interface ReconstructedMetricDef {
26 + name: string;
27 + unit: string;
30 +export interface ReconstructedRun {
31 + run: number;
32 + commit: string;
33 + metric: number;
34 + metrics: Record<string, number>;
35 + status: "keep" | "discard" | "crash" | "checks_failed";
36 + description: string;
37 + timestamp: number;
38 + segment: number;
39 + confidence: number | null;
40 + asi?: Record<string, unknown>;
43 +export interface ReconstructedJsonlState {
44 + name: string | null;
45 + metricName: string;
46 + metricUnit: string;
47 + bestDirection: "lower" | "higher";
48 + currentSegment: number;
49 + results: ReconstructedRun[];
50 + secondaryMetrics: ReconstructedMetricDef[];
53 +// ── Constants ─────────────────────────────────────────────────────────────
55 +const DEFAULT_METRIC_NAME = "metric";
56 +const DEFAULT_METRIC_UNIT = "";
57 +const DEFAULT_DIRECTION = "lower" as const;
59 +// ── Helpers ───────────────────────────────────────────────────────────────
61 +function isObjectRecord(value: unknown): value is JsonlEntry {
62 + return value !== null && typeof value === "object" && !Array.isArray(value);
65 +function nonEmptyLines(text: string): string[] {
66 + return text.split("\n").filter(Boolean);
69 +function inferMetricUnit(name: string): string {
70 + if (name.endsWith("µs")) return "µs";
71 + if (name.endsWith("_ms")) return "ms";
72 + if (name.endsWith("_s") || name.endsWith("_sec")) return "s";
73 + if (name.endsWith("_kb")) return "kb";
74 + if (name.endsWith("_mb")) return "mb";
75 + return "";
78 +function metricMapFrom(value: unknown): Record<string, number> {
79 + if (!isObjectRecord(value)) return {};
80 + const metrics: Record<string, number> = {};
81 + for (const [name, metric] of Object.entries(value)) {
82 + if (typeof metric === "number") metrics[name] = metric;
83 + }
84 + return metrics;
87 +function statusFrom(value: unknown): ReconstructedRun["status"] {
88 + if (value === "discard") return "discard";
89 + if (value === "crash") return "crash";
90 + if (value === "checks_failed") return "checks_failed";
91 + return "keep";
94 +function directionFrom(value: unknown): ReconstructedJsonlState["bestDirection"] {
95 + return value === "higher" ? "higher" : DEFAULT_DIRECTION;
98 +function asiFrom(value: unknown): Record<string, unknown> | undefined {
99 + return isObjectRecord(value) ? value : undefined;
102 +function reconstructedState(): ReconstructedJsonlState {
103 + return {
104 + name: null,
105 + metricName: DEFAULT_METRIC_NAME,
106 + metricUnit: DEFAULT_METRIC_UNIT,
107 + bestDirection: DEFAULT_DIRECTION,
108 + currentSegment: 0,
109 + results: [],
110 + secondaryMetrics: [],
111 + };
114 +function updateConfig(state: ReconstructedJsonlState, entry: AutoresearchConfigEntry): void {
115 + if (typeof entry.name === "string") state.name = entry.name;
116 + if (typeof entry.metricName === "string") state.metricName = entry.metricName;
117 + if (typeof entry.metricUnit === "string") state.metricUnit = entry.metricUnit;
118 + state.bestDirection = directionFrom(entry.bestDirection);
121 +function nextSegment(state: ReconstructedJsonlState, segment: number): number {
122 + if (state.results.length === 0) return segment;
123 + state.secondaryMetrics = [];
124 + return segment + 1;
127 +function runFrom(entry: AutoresearchRunEntry, segment: number): ReconstructedRun {
128 + return {
129 + run: typeof entry.run === "number" ? entry.run : 0,
130 + commit: typeof entry.commit === "string" ? entry.commit : "",
131 + metric: typeof entry.metric === "number" ? entry.metric : 0,
132 + metrics: metricMapFrom(entry.metrics),
133 + status: statusFrom(entry.status),
134 + description: typeof entry.description === "string" ? entry.description : "",
135 + timestamp: typeof entry.timestamp === "number" ? entry.timestamp : 0,
136 + segment,
137 + confidence: typeof entry.confidence === "number" ? entry.confidence : null,
138 + asi: asiFrom(entry.asi),
139 + };
142 +function registerSecondaryMetrics(
143 + state: ReconstructedJsonlState,
144 + metrics: Record<string, number>,
145 +): void {
146 + for (const name of Object.keys(metrics)) {
147 + if (state.secondaryMetrics.find((metric) => metric.name === name)) continue;
148 + state.secondaryMetrics.push({ name, unit: inferMetricUnit(name) });
152 +// ── Public API ────────────────────────────────────────────────────────────
154 +export function parseJsonlEntry(line: string): JsonlEntry | null {
155 + try {
156 + const parsed = JSON.parse(line);
157 + return isObjectRecord(parsed) ? parsed : null;
158 + } catch {
159 + return null;
163 +export function isAutoresearchConfigEntry(entry: unknown): entry is AutoresearchConfigEntry {
164 + return isObjectRecord(entry) && entry.type === "config";
167 +export function isAutoresearchRunEntry(entry: unknown): entry is AutoresearchRunEntry {
168 + return isObjectRecord(entry) && typeof entry.run === "number";
171 +function firstConfigEntry(jsonlContent: string): AutoresearchConfigEntry | null {
172 + for (const line of nonEmptyLines(jsonlContent)) {
173 + const entry = parseJsonlEntry(line);
174 + if (isAutoresearchConfigEntry(entry)) return entry;
176 + return null;
179 +export function hasAutoresearchConfigHeader(jsonlContent: string): boolean {
180 + return firstConfigEntry(jsonlContent) !== null;
183 +export function extractAutoresearchSessionName(jsonlContent: string): string {
184 + return firstConfigEntry(jsonlContent)?.name || "Autoresearch";
187 +export function reconstructJsonlState(jsonlContent: string): ReconstructedJsonlState {
188 + const state = reconstructedState();
189 + let segment = 0;
191 + for (const line of nonEmptyLines(jsonlContent)) {
192 + const entry = parseJsonlEntry(line);
193 + if (!entry) continue;
195 + if (isAutoresearchConfigEntry(entry)) {
196 + updateConfig(state, entry);
197 + segment = nextSegment(state, segment);
198 + state.currentSegment = segment;
199 + continue;
202 + if (!isAutoresearchRunEntry(entry)) continue;
204 + const run = runFrom(entry, segment);
205 + state.results.push(run);
206 + registerSecondaryMetrics(state, run.metrics);
209 + return state;

extensions/autoresearch/package.json

Added
new file mode 100644
1 +{
2 + "name": "@bugabinga/pi-ext-autoresearch",
3 + "type": "module",
4 + "main": "index.ts",
5 + "peerDependencies": {
6 + "@earendil-works/pi-ai": "*",
7 + "@earendil-works/pi-coding-agent": "*",
8 + "@earendil-works/pi-tui": "*",
9 + "typebox": "*"
10 + },
11 + "license": "MIT",
12 + "description": "Autonomous experiment loop for Pi.",
13 + "keywords": [
14 + "pi",
15 + "pi-extension"
16 + ],
17 + "devDependencies": {
18 + "@marcfargas/pi-test-harness": "^0.6.1"
19 + },
20 + "scripts": {
21 + "test:harness": "bun test ./__tests__/harness.test.ts",
22 + "test": "bun test ./__tests__/*.test.ts"
23 + },
24 + "private": true

extensions/autoresearch/shortcuts.ts

Added
new file mode 100644
1 +/**
2 + * Keyboard shortcut configuration for autoresearch dashboard.
3 + *
4 + * Config file: <agent-dir>/extensions/autoresearch.json
5 + * Keys: shortcuts.toggleDashboard, shortcuts.fullscreenDashboard
6 + */
8 +import { existsSync, readFileSync } from "node:fs";
9 +import { join } from "node:path";
10 +import { getAgentDir } from "@earendil-works/pi-coding-agent";
12 +// ── Constants ─────────────────────────────────────────────────────────────
14 +export const DEFAULT_TOGGLE_DASHBOARD_SHORTCUT = "ctrl+shift+t";
15 +export const DEFAULT_FULLSCREEN_DASHBOARD_SHORTCUT = "ctrl+shift+f";
17 +const CONFIG_FILE_NAME = "autoresearch.json";
19 +// ── Types ─────────────────────────────────────────────────────────────────
21 +export interface AutoresearchShortcuts {
22 + toggleDashboard: string | null;
23 + fullscreenDashboard: string | null;
26 +interface AutoresearchShortcutConfig {
27 + toggleDashboard?: unknown;
28 + fullscreenDashboard?: unknown;
31 +// ── Helpers ───────────────────────────────────────────────────────────────
33 +function isRecord(value: unknown): value is Record<string, unknown> {
34 + return typeof value === "object" && value !== null && !Array.isArray(value);
37 +function isValidShortcutConfigValue(value: unknown): value is string | null | undefined {
38 + return (
39 + value === undefined ||
40 + value === null ||
41 + (typeof value === "string" && value !== "")
42 + );
45 +function hasValidShortcutValues(shortcuts: Record<string, unknown>): boolean {
46 + return (
47 + isValidShortcutConfigValue(shortcuts.toggleDashboard) &&
48 + isValidShortcutConfigValue(shortcuts.fullscreenDashboard)
49 + );
52 +function shortcutFromConfig(configured: unknown, fallback: string): string | null {
53 + if (configured === null) return null;
54 + return typeof configured === "string" ? configured : fallback;
57 +function defaultAutoresearchShortcuts(): AutoresearchShortcuts {
58 + return {
59 + toggleDashboard: DEFAULT_TOGGLE_DASHBOARD_SHORTCUT,
60 + fullscreenDashboard: DEFAULT_FULLSCREEN_DASHBOARD_SHORTCUT,
61 + };
64 +function warnUsingDefaults(reason: "Could not read" | "Invalid", configPath: string): void {
65 + console.warn(
66 + `${reason} autoresearch config at ${configPath}; using default shortcuts.`,
67 + );
70 +// ── Public API ────────────────────────────────────────────────────────────
72 +export function autoresearchShortcutsConfigPath(agentDir: string = getAgentDir()): string {
73 + return join(agentDir, "extensions", CONFIG_FILE_NAME);
76 +export function resolveAutoresearchShortcuts(
77 + configPath: string = autoresearchShortcutsConfigPath(),
78 +): AutoresearchShortcuts {
79 + if (!existsSync(configPath)) return defaultAutoresearchShortcuts();
81 + let parsed: unknown;
82 + try {
83 + parsed = JSON.parse(readFileSync(configPath, "utf-8"));
84 + } catch {
85 + warnUsingDefaults("Could not read", configPath);
86 + return defaultAutoresearchShortcuts();
87 + }
89 + const shortcuts = isRecord(parsed) ? parsed.shortcuts : undefined;
90 + if (shortcuts === undefined) return defaultAutoresearchShortcuts();
92 + if (!isRecord(shortcuts) || !hasValidShortcutValues(shortcuts)) {
93 + warnUsingDefaults("Invalid", configPath);
94 + return defaultAutoresearchShortcuts();
95 + }
97 + return {
98 + toggleDashboard: shortcutFromConfig(
99 + shortcuts.toggleDashboard,
100 + DEFAULT_TOGGLE_DASHBOARD_SHORTCUT,
101 + ),
102 + fullscreenDashboard: shortcutFromConfig(
103 + shortcuts.fullscreenDashboard,
104 + DEFAULT_FULLSCREEN_DASHBOARD_SHORTCUT,
105 + ),
106 + };

skills/acli/SKILL.md

Modified
2 2 name: acli
3 3 description: >
4 - Atlassian CLI (acli) for Jira, Confluence, Rovo Dev, and org admin.
5 - Use when: working with Jira issues/projects/boards/sprints, Confluence
6 - pages/spaces/blogs, Atlassian org users, or Rovo Dev. Triggers on:
7 - jira, confluence, rovo, atlassian, work item, sprint, JQL, confluence page/space/blog.
4 + Atlassian tools for Jira, Confluence, and org admin. Triggers on: jira,
5 + confluence, rovo, atlassian, work item, sprint, JQL, confluence page/space/blog.
10 -# Atlassian CLI (`acli`)
8 +# Atlassian Tools
12 -CLI for Atlassian Cloud. Docs: <https://developer.atlassian.com/cloud/acli/>
10 +## Tool Selection
14 -> **Note:** Official docs are incomplete. The command reference was last updated Oct 2024.
15 -> The official changelog stops at v1.3.15 (Mar 2026) — v1.3.16–1.3.18 have no release notes.
16 -> The `confluence` product is entirely absent from docs and changelog but works in the CLI.
17 -> This skill was built by testing against a real Atlassian Cloud instance.
12 +```
13 +acli (preferred) → atlassian-cli (fallback) → web UI (last resort)
14 +```
16 +| | acli | atlassian-cli |
17 +| ------------------------ | --------------- | ----------------- |
18 +| **Jira issues** | ✅ | ✅ |
19 +| **Jira projects/boards** | ✅ | ✅ |
20 +| **Confluence pages CRUD**| ❌ view only | ✅ create/edit/del|
21 +| **Confluence blogs CRUD**| ❌ create only | ✅ full CRUD |
22 +| **Confluence attachments**| ❌ | ✅ upload/download |
23 +| **Confluence search** | ❌ | ✅ CQL + text |
24 +| **Bitbucket** | ❌ | ✅ |
25 +| **JSM** | ❌ | ✅ |
26 +| **Auth** | OAuth (browser) | API token |
28 +Docs: <https://developer.atlassian.com/cloud/acli/>
30 +> **Note:** acli's Confluence commands are undocumented and incomplete (no page
31 +> CRUD, no blog update/delete, no attachments). atlassian-cli fills those gaps
32 +> using the Confluence REST API v2 with basic auth (API token).
19 -> **Warning:** Don't confuse this with `atlassian-cli` (third-party Rust CLI by omar16100)
20 -> or Appfire ACLI (paid marketplace app). This skill covers only the official `acli` binary.
34 +> **Warning:** Don't confuse with `atlassian-cli` (third-party Rust, omar16100)
35 +> or Appfire ACLI (paid marketplace app). This skill covers only `acli` (official)
36 +> and `atlassian-cli` (omar16100).
22 38 ## Prerequisites — STOP if missing
24 -Before any acli operation, verify dependencies:
26 40 ```bash
41 +# Primary: acli (OAuth)
27 42 acli --version # must succeed
28 -acli jira auth status || acli confluence auth status # at least one product authed
43 +acli jira auth status || acli confluence auth status
45 +# Fallback: atlassian-cli (API token)
46 +atlassian-cli --version # must succeed
47 +atlassian-cli auth list # must show a profile
31 -**Missing `acli`?** Install: `brew install acli` or
32 -<https://developer.atlassian.com/cloud/acli/guides/install-acli/>
50 +**Missing `acli`?** Install: <https://developer.atlassian.com/cloud/acli/guides/install-acli/>
34 -**Not authenticated?** Run `acli <product> auth login`, then retry.
52 +**Missing `atlassian-cli`?** `brew install omar16100/atlassian-cli/atlassian-cli`
53 +or `cargo install atlassian-cli`.
36 -**Missing `pandoc` for Confluence publishing?** `md2confluence.py` requires
37 -`pandoc`. If absent, plain HTML works but code blocks won't have syntax
38 -highlighting. Report the gap — don't fall back to REST API.
40 -**Policy: never bypass acli with raw `curl`/REST API calls.** If acli can't do
41 -it, that's a documented gap (see "Known Gaps"). Stop and tell the user.
43 -## Command Structure
45 -```
46 -acli <product> <resource> <action> [flags]
47 -```
49 -Products: `jira`, `confluence`, `rovodev`, `admin`
51 -## Auth
55 +**Missing API token for atlassian-cli?**
56 +Create one at <https://id.atlassian.com/manage-profile/security/api-tokens>
57 +(click **Create API token**, not "with scopes"), then:
53 59 ```bash
54 -# Jira / Confluence — OAuth via browser
55 -acli jira auth login
56 -acli confluence auth login
58 -# Admin — requires email + API token
59 -acli admin auth login --email admin@example.com --token < token.txt
61 -# Rovo Dev — requires dedicated API token
62 -acli rovodev auth login # token from https://go.atlassian.com/rovo-dev-api-token
64 -# Check status
65 -acli jira auth status
66 -acli confluence auth status
60 +atlassian-cli auth login --profile default \
61 + --base-url https://YOUR-SITE.atlassian.net \
62 + --email you@example.com \
63 + --token "$ATLASSIAN_API_TOKEN" --default
66 +**Policy: never bypass both tools with raw `curl`/REST API calls.** If neither
67 +tool can do it, that's a documented gap → use web UI.
69 +## atlassian-cli parse errors
71 +atlassian-cli v0.3.x has a known JSON deserialization bug on list and delete
72 +responses (null fields in Confluence API v2). **Operations still succeed** —
73 +ignore the error and verify separately:
75 +```bash
76 +# This prints an error BUT the operation succeeds:
77 +atlassian-cli confluence page delete 12345 --force
78 +# Verify: acli confluence page view --id 12345 → should 404 or show "trashed"
79 +```
81 +Rule of thumb: if you see `Failed to parse JSON response` the operation likely
82 +worked. Check status separately.
69 84 ## Jira
71 86 ### Work Items (issues)
73 88 ```bash
74 89 # Create
75 90 acli jira workitem create --summary "Title" --project PROJ --type Task
76 -acli jira workitem create --summary "Bug" --project PROJ --type Bug --assignee @me --label "backend,urgent"
77 -acli jira workitem create --description "plain text only" --description-file desc.txt -p PROJ -t Story -s "Title"
79 -# Create with rich formatting — use ADF JSON
80 -acli jira workitem create --generate-json > workitem.json # scaffold
81 -# edit workitem.json (see "ADF for rich Jira descriptions" below)
91 +acli jira workitem create --assignee @me --label "backend,urgent" -p PROJ -t Story -s "Title"
92 +acli jira workitem create --generate-json > workitem.json # scaffold for rich ADF
82 93 acli jira workitem create --from-json workitem.json
84 95 # Bulk create
85 96 acli jira workitem create-bulk --from-csv issues.csv
86 97 acli jira workitem create-bulk --from-json issues.json
88 -# View
99 +# View / Search
89 100 acli jira workitem view KEY-123
90 -acli jira workitem view KEY-123 --fields summary,status,assignee,description --json
91 -acli jira workitem view KEY-123 --web
93 -# Search (JQL)
101 +acli jira workitem view KEY-123 --fields summary,status --json
94 102 acli jira workitem search --jql "project = PROJ AND status = Open" --paginate
95 -acli jira workitem search --jql "assignee = currentUser() AND sprint in openSprints()" --fields "key,summary,priority" --json
96 -acli jira workitem search --jql "project = PROJ" --csv --limit 50
97 -acli jira workitem search --filter 10001 # by saved filter ID
103 +acli jira workitem search --jql "assignee = currentUser()" --csv --limit 50
104 +acli jira workitem search --filter 10001
99 -# Edit
100 -acli jira workitem edit --key KEY-123 --summary "Updated title"
101 -acli jira workitem edit --key KEY-1,KEY-2 --assignee user@example.com
102 -acli jira workitem edit --jql "project = PROJ AND status = 'To Do'" --assignee @me
106 +# Edit / Transition
107 +acli jira workitem edit --key KEY-123 --summary "Updated"
108 +acli jira workitem edit --jql "project = PROJ" --assignee @me
109 +acli jira workitem transition --key KEY-123 --status Done --yes
110 +acli jira workitem transition --jql "project = PROJ" --status "In Progress"
104 -# Transition (change status)
105 -acli jira workitem transition --key KEY-123 --status "In Progress"
106 -acli jira workitem transition --jql "project = PROJ" --status Done --yes
108 -# Clone
112 +# Clone / Delete
109 113 acli jira workitem clone --key KEY-123 --to-project OTHER
114 +acli jira workitem delete --key KEY-123 --yes
111 116 # Comments
112 -acli jira workitem comment create --key KEY-123 --body "comment text"
113 -acli jira workitem comment create --key KEY-123 --body-file comment.txt
117 +acli jira workitem comment create --key KEY-123 --body "text"
114 118 acli jira workitem comment list --key KEY-123
115 -acli jira workitem comment update --key KEY-123 --id COMMENT_ID --body "updated"
116 -acli jira workitem comment delete --key KEY-123 --id COMMENT_ID
117 -acli jira workitem comment visibility --role --project PROJ # check visibility options
118 -acli jira workitem comment visibility --group
119 +acli jira workitem comment update --key KEY-123 --id ID --body "updated"
120 +acli jira workitem comment delete --key KEY-123 --id ID
121 +acli jira workitem comment visibility --role --project PROJ
120 123 # Links
121 124 acli jira workitem link create --key KEY-1 --target KEY-2 --type "Blocks"
122 125 acli jira workitem link list --key KEY-1
123 126 acli jira workitem link delete --key KEY-1 --target KEY-2 --type "Blocks"
124 -acli jira workitem link type # list available link types
127 +acli jira workitem link type
126 -# Attachments (list/delete only — no upload)
129 +# Attachments (list/delete via acli; upload via atlassian-cli)
127 130 acli jira workitem attachment list --key KEY-123
128 -acli jira workitem attachment delete --key KEY-123 --id ATTACHMENT_ID
131 +acli jira workitem attachment delete --key KEY-123 --id ID
130 133 # Other
131 134 acli jira workitem assign --key KEY-123 --assignee user@example.com
132 135 acli jira workitem archive --key KEY-123
133 136 acli jira workitem unarchive --key KEY-123
134 -acli jira workitem delete --key KEY-123 --yes
135 137 acli jira workitem watcher list --key KEY-123
136 138 acli jira workitem watcher remove --key KEY-123 --user user@example.com
139 -### Projects
141 +### Projects, Boards, Sprints, Filters, Fields
141 143 ```bash
142 -acli jira project list --limit 20 # --limit or --paginate required
144 +acli jira project list --limit 20 # --limit or --paginate required
143 145 acli jira project view PROJ
144 -acli jira project create --key PROJ --name "Project Name"
145 -acli jira project update PROJ --name "New Name"
146 -acli jira project archive PROJ
147 -acli jira project delete PROJ
148 -```
146 +acli jira project create --key PROJ --name "Name"
150 -### Boards & Sprints
152 -```bash
153 148 acli jira board search --project PROJ
154 -acli jira board get BOARD_ID --json
155 149 acli jira board list-sprints BOARD_ID
156 150 acli jira sprint create --board BOARD_ID --name "Sprint 1"
157 -acli jira sprint view SPRINT_ID
158 151 acli jira sprint list-workitems SPRINT_ID
159 -acli jira sprint update SPRINT_ID --state closed
160 -```
162 -### Filters
164 -```bash
165 153 acli jira filter list
166 -acli jira filter search --jql "project = PROJ"
167 -acli jira filter get --id FILTER_ID
168 -acli jira filter add-favourite --id FILTER_ID
169 -acli jira filter update --id FILTER_ID --jql "..."
170 -```
172 -### Fields
174 -```bash
175 -acli jira field create --name "My Field" --type text
176 -acli jira field update --id customfield_12345 --name "New Name"
177 -acli jira field delete --id customfield_12345
178 -acli jira field cancel-delete --id customfield_12345 # restore from trash
179 -```
181 -### Dashboards
183 -```bash
184 -acli jira dashboard search
154 +acli jira field create --name "Field" --type text
187 157 ## Confluence
189 -> Not documented in official acli docs. Verified against a real Confluence Cloud
190 -> instance (v1.3.18). REST API also out of scope — no way to reuse acli's OAuth
191 -> token, and maintaining a separate API token is too much ceremony. Gaps = web UI.
193 -### Pages (view only)
159 +### Pages — use atlassian-cli for create/edit/delete
195 161 ```bash
162 +# View (acli or atlassian-cli)
196 163 acli confluence page view --id PAGE_ID
197 164 acli confluence page view --id PAGE_ID --json
198 165 acli confluence page view --id PAGE_ID --body-format storage
199 -acli confluence page view --id PAGE_ID --body-format atlas_doc_format
200 -acli confluence page view --id PAGE_ID --include-labels --include-version
201 166 acli confluence page view --id PAGE_ID --include-direct-children
168 +# List pages (atlassian-cli — note: may show parse error, results still valid)
169 +atlassian-cli confluence page list --space SPACE_ID --limit 25
171 +# Get page (atlassian-cli)
172 +atlassian-cli confluence page get PAGE_ID
174 +# Create page (--body is a FILE PATH, not inline text)
175 +echo '<p>Content here</p>' > /tmp/page.html
176 +atlassian-cli confluence page create \
177 + --space SPACE_ID --title "New Page" --body /tmp/page.html
178 +# Create as child page
179 +atlassian-cli confluence page create \
180 + --space SPACE_ID --title "Child" --parent PARENT_ID --body /tmp/page.html
182 +# Update page
183 +echo '<p>Updated content</p>' > /tmp/page_v2.html
184 +atlassian-cli confluence page update PAGE_ID --body /tmp/page_v2.html --message "update note"
186 +# Delete page (ignore parse error — check status separately)
187 +atlassian-cli confluence page delete PAGE_ID --force
189 +# Labels
190 +atlassian-cli confluence page add-label --id PAGE_ID --label mylabel
191 +atlassian-cli confluence page remove-label --id PAGE_ID --label mylabel
193 +# Comments
194 +atlassian-cli confluence page comments PAGE_ID
195 +atlassian-cli confluence page add-comment --id PAGE_ID --body "comment text"
196 +```
198 +### Blogs
200 +```bash
201 +# Create (acli or atlassian-cli)
202 +acli confluence blog create --space-id SPACE_ID --title "Post" --body "<p>Text</p>"
203 +acli confluence blog create --space-id SPACE_ID --title "Post" --from-file content.html
204 +acli confluence blog create --from-json payload.json
206 +# View / List
207 +acli confluence blog view --id BLOG_ID
208 +acli confluence blog list --space-id SPACE_ID
210 +# Update / Delete (atlassian-cli only)
211 +echo '<p>Updated</p>' > /tmp/blog.html
212 +atlassian-cli confluence blog update BLOG_ID --body /tmp/blog.html
213 +atlassian-cli confluence blog delete BLOG_ID --force
204 216 ### Spaces
206 218 ```bash
207 219 acli confluence space list
208 220 acli confluence space view --key SPACEKEY
209 -acli confluence space create --key SPACEKEY --name "Space Name" --description "desc"
221 +acli confluence space create --key SPACEKEY --name "Name"
210 222 acli confluence space update --key SPACEKEY --name "New Name"
211 223 acli confluence space archive --key SPACEKEY
212 224 acli confluence space restore --key SPACEKEY
215 -### Blogs
227 +### Attachments — atlassian-cli only
217 229 ```bash
218 -acli confluence blog create --space-id SPACE_ID --title "Post" --body "<p>Content</p>"
219 -acli confluence blog create --space-id SPACE_ID --title "Draft" --status draft --body "text"
220 -acli confluence blog create --space-id SPACE_ID --title "Post" --from-file content.html
221 -acli confluence blog create --from-json payload.json
222 -acli confluence blog list --space-id SPACE_ID
223 -acli confluence blog view --id BLOG_ID
230 +atlassian-cli confluence attachment upload --page-id PAGE_ID --file ./diagram.png
231 +atlassian-cli confluence attachment list --page-id PAGE_ID
232 +atlassian-cli confluence attachment download --id ATTACHMENT_ID --output ./out.png
233 +atlassian-cli confluence attachment delete --id ATTACHMENT_ID
234 +```
236 +### Search — atlassian-cli only
238 +```bash
239 +atlassian-cli confluence search cql --cql "space = DEV and type = page" --limit 10
240 +atlassian-cli confluence search text --query "meeting notes" --limit 10
241 +atlassian-cli confluence search in-space --space DEV --query "api docs"
226 244 ### Finding your space ID
236 -## Rovo Dev
254 +## Auth Reference
238 -AI coding agent (beta). Requires separate API token from
239 -<https://go.atlassian.com/rovo-dev-api-token>.
256 +### acli — OAuth (browser)
241 258 ```bash
242 -acli rovodev auth login
259 +acli jira auth login # browser OAuth
260 +acli confluence auth login # browser OAuth
261 +acli admin auth login --email admin@example.com --token < token.txt
262 +acli rovodev auth login # token from https://go.atlassian.com/rovo-dev-api-token
263 +```
265 +### atlassian-cli — API token
267 +```bash
268 +# Interactive
269 +atlassian-cli auth login --profile default \
270 + --base-url https://SITE.atlassian.net --email you@example.com
272 +# Or via env vars (no config needed)
273 +export ATLASSIAN_URL="https://SITE.atlassian.net"
274 +export ATLASSIAN_EMAIL="you@example.com"
275 +export ATLASSIAN_API_TOKEN="your-token"
276 +```
278 +Create token: <https://id.atlassian.com/manage-profile/security/api-tokens>
280 +## Rovo Dev
282 +```bash
283 +acli rovodev auth login # needs token from https://go.atlassian.com/rovo-dev-api-token
243 284 acli rovodev run
246 287 ## Admin
248 289 ```bash
249 -# Auth requires --email + --token (API key from admin.atlassian.com → settings → API Keys)
250 -acli admin auth login --email admin@example.com --token < token.txt
252 290 acli admin user activate --account-id USER_ID
253 291 acli admin user deactivate --account-id USER_ID
254 292 acli admin user delete --account-id USER_ID
255 -acli admin user cancel-delete --account-id USER_ID
258 295 ## Output Flags
297 +**acli:**
260 299 | Flag | Effect |
261 300 | ------------ | -------------------------- |
262 301 | `--json` | JSON output |
263 -| `--csv` | CSV output (search only) |
302 +| `--csv` | CSV (search only) |
264 303 | `--web` | Open in browser |
265 -| `--paginate` | Fetch all pages of results |
304 +| `--paginate` | Fetch all pages |
266 305 | `--limit N` | Cap results |
267 -| `--yes`/`-y` | Skip confirmation prompts |
306 +| `--yes`/`-y` | Skip confirmation |
308 +**atlassian-cli:**
310 +| Flag | Effect |
311 +| ----------------- | ------------------------------- |
312 +| `-f json` | JSON output |
313 +| `-f csv` | CSV output |
314 +| `-f yaml` | YAML output |
315 +| `-f table` | Table (default) |
316 +| `-f quiet` | IDs only |
269 318 ## JQL Quick Reference
284 333 Combine with `AND` / `OR` / `NOT`. Group with `()`.
285 -Use `--paginate` for large result sets.
287 335 ## Rich Formatting
289 -### ADF for rich Jira descriptions and comments
337 +### ADF for rich Jira descriptions (acli)
291 -acli's `--description` and `--body` accept **plain text only**. Jira wiki markup
292 -(`h1.`, `*bold*`, `{code}`) is stored as literal text — NOT rendered.
294 -For rich formatting, build ADF JSON and use `--from-json`:
339 +acli's `--description` accepts **plain text only**. Jira wiki markup is stored
340 +as literal text. For rich formatting, use ADF JSON via `--from-json`:
296 342 ```bash
297 -acli jira workitem create --generate-json > template.json # scaffold
343 +acli jira workitem create --generate-json > template.json
300 -Verified ADF node types:
346 +Verified ADF nodes: `heading`, `paragraph`, `text` (marks: `strong`/`em`/`code`),
347 +`codeBlock`, `bulletList`, `orderedList`, `table`, `blockquote`.
302 -| ADF node | Renders as |
303 -| ------------- | ------------------ |
304 -| `heading` | h1–h6 heading |
305 -| `paragraph` | text paragraph |
306 -| `text` + marks| bold/em/code/... |
307 -| `codeBlock` | syntax highlighted |
308 -| `bulletList` | unordered list |
309 -| `orderedList` | numbered list |
310 -| `table` | data table |
311 -| `blockquote` | block quote |
349 +### Confluence pages — HTML storage format (atlassian-cli)
313 -Mark types: `strong`, `em`, `code`, `strike`, `underline`, `link`.
315 -Example ADF paragraph:
317 -```json
319 - "type": "paragraph",
320 - "content": [
321 - {"type": "text", "text": "Normal "},
322 - {"type": "text", "text": "bold", "marks": [{"type": "strong"}]},
323 - {"type": "text", "text": " "},
324 - {"type": "text", "text": "italic", "marks": [{"type": "em"}]},
325 - {"type": "text", "text": " "},
326 - {"type": "text", "text": "code", "marks": [{"type": "code"}]}
327 - ]
329 -```
331 -### Confluence: Markdown → HTML with Syntax Highlighting
333 -Confluence accepts HTML in `--body` / `--from-file`. Plain pandoc HTML works for
334 -most elements but **code blocks render as unstyled text** — Confluence ignores
335 -pandoc's CSS `<span>` classes.
337 -Use `md2confluence.py` (in this skill's directory). Runs
338 -`pandoc -f markdown -t html --no-highlight` then replaces `<pre class="LANG">`
339 -blocks with `<ac:structured-macro ac:name="code">` for proper Confluence syntax
340 -highlighting.
351 +atlassian-cli's `--body` takes a **file path** containing Confluence storage
352 +format HTML. For markdown with syntax-highlighted code blocks, use
353 +`md2confluence.py` (in this skill's directory):
342 355 ```bash
343 -python3 md2confluence.py input.md > output.html
344 -acli confluence blog create --space-id SPACE_ID --title "Title" --from-file output.html
356 +python3 md2confluence.py input.md > /tmp/page.html
357 +atlassian-cli confluence page create --space SPACE_ID --title "Title" --body /tmp/page.html
347 -**Requires:** `pandoc` in PATH. If missing, report the gap to the user.
349 -### Pandoc Jira markup — read only
351 -```bash
352 -# Jira wiki markup → Markdown (for reading existing content)
353 -pandoc -f jira -t markdown input.jira
355 -# Markdown → Jira wiki markup (limited utility — acli doesn't accept it as input)
356 -pandoc -f markdown -t jira input.md
357 -```
359 -acli does NOT accept Jira wiki markup for descriptions or comments. Only useful
360 -for converting existing wiki markup to readable markdown.
360 +**Requires:** `pandoc` in PATH. Converts pandoc code blocks to
361 +`<ac:structured-macro ac:name="code">` for proper Confluence highlighting.
362 363 ## Common Patterns
367 368 acli jira workitem search --jql "assignee = currentUser() AND type = Bug AND sprint in openSprints()" --paginate --json
371 +### Create a Confluence page from markdown
373 +```bash
374 +python3 md2confluence.py report.md > /tmp/report.html
375 +atlassian-cli confluence page create --space SPACE_ID --title "Report" --body /tmp/report.html
376 +```
378 +### Upload attachment to a page
380 +```bash
381 +atlassian-cli confluence attachment upload --page-id PAGE_ID --file ./screenshot.png
382 +```
370 384 ### Bulk transition to Done
372 386 ```bash
382 396 ### Export issues as CSV
384 398 ```bash
385 -acli jira workitem search --jql "project = PROJ" --fields "key,summary,status,assignee" --csv > issues.csv
399 +acli jira workitem search --jql "project = PROJ" --fields "key,summary,status" --csv > issues.csv
388 -### Publish markdown as Confluence blog with code highlighting
390 -```bash
391 -python3 md2confluence.py report.md > /tmp/report.html
392 -acli confluence blog create --space-id SPACE_ID --title "Report" --from-file /tmp/report.html
393 -```
395 -## Known Gaps (acli v1.3.18)
402 +## Known Gaps
397 404 If you hit any of these, **stop and report to the user.** Do not fall back to
398 405 REST API.
400 407 | Gap | Status |
401 408 | --------------------------------------------- | ----------------------- |
402 -| No `confluence page create/update/delete` | ⛔ use web UI |
403 -| No `confluence blog update/delete` | ⛔ use web UI |
404 -| No `jira workitem attachment` upload | ⛔ use web UI |
405 -| No raw API proxy subcommand | ⛔ not possible via acli|
406 -| REST API access (separate token required) | ⛔ out of scope — web UI |
407 -| `project list` requires `--limit`/`--paginate`| always pass one |
408 -| `--json` on `auth status` not supported | use plain text output |
409 -| `--description` only accepts plain text | use `--from-json` + ADF |
410 -| Jira wiki markup not rendered by acli | use ADF JSON |
411 -| Pandoc HTML code blocks unstyled in Confluence| use `md2confluence.py` |
412 -| Confluence commands absent from official docs | undocumented, may change|
413 -| v1.3.16–1.3.18 have no changelog entries | unknown what else changed|
414 -| No `acli jira auth login --web` in docs | works anyway (OAuth) |
409 +| acli: no `confluence page create/update/delete`| ✅ use atlassian-cli |
410 +| acli: no `confluence blog update/delete` | ✅ use atlassian-cli |
411 +| acli: no attachment upload | ✅ use atlassian-cli |
412 +| acli: no Confluence search | ✅ use atlassian-cli |
413 +| acli: Confluence commands absent from docs | undocumented, may change|
414 +| atlassian-cli: page list parse error | cosmetic — list works |
415 +| atlassian-cli: delete ops show parse error | ops succeed — verify separately |
416 +| atlassian-cli: `--body` is file path only | write temp file |
417 +| No `jira workitem attachment` upload (acli) | use web UI |
418 +| v1.3.16–1.3.18 have no changelog entries | unknown what changed |
416 420 ## Troubleshooting
418 422 ### "failed to parse JQL query"
420 -JQL field values are case-sensitive. Quote strings with spaces.
421 -Operators: `=` (exact), `~` (fuzzy/contains), `!=`, `!~` (not contains).
424 +JQL values are case-sensitive. Quote strings with spaces.
425 +Operators: `=` `~` `!=` `!~`.
423 -### Auth errors
427 +### "Failed to parse JSON response" (atlassian-cli)
425 -```bash
426 -acli jira auth status
427 -acli jira auth login # re-authenticate
428 -```
429 +Known bug in v0.3.x — the operation usually succeeded. Verify separately:
430 +`acli confluence page view --id ID` or `atlassian-cli confluence page get ID`.
430 -### "site admin must authorize this app"
432 +### "site admin must authorize this app" (acli)
432 -Since v1.3.15 — OAuth scopes changed. Site admin must re-approve:
433 -`acli jira auth login` → select "Web" → approve the site.
434 +Since v1.3.15 — OAuth scopes changed. Site admin re-approves via
435 +`acli jira auth login` → select "Web".
435 437 ### Rate limiting
437 -Use `--limit` to cap results. Avoid `--paginate` in tight loops.
439 +acli: use `--limit` to cap results. Avoid `--paginate` in tight loops.
439 441 ### Pandoc not found
441 -`md2confluence.py` requires `pandoc`. Install: `brew install pandoc` or system
442 -package manager. Plain `pandoc -t html` still works for non-code content.
443 +`md2confluence.py` requires `pandoc`. Install: `brew install pandoc`.