@dungle-scrubs/tallow 0.8.0

package/extensions/slash-command-bridge/index.ts

@@ -0,0 +1,271 @@
+/**
+ * Slash Command Bridge Extension
+ *
+ * Exposes a curated set of slash commands as tools the model can invoke.
+ * Phase 1: uses ExtensionContext methods directly for commands whose logic
+ * is available in tool execution context (show-system-prompt, context, compact).
+ *
+ * Phase 2 (future): framework-level `allowModelInvocation` flag on command
+ * registration, with auto-generated tool schemas and full command handler access.
+ */
+
+import type { ContextUsage, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+
+/**
+ * Deferred compact request — set by the tool handler, consumed by the
+ * `agent_end` hook. Deferring avoids the spinner-hang bug where
+ * `ctx.compact()` aborts the agent mid-tool-call, orphaning the tool
+ * execution UI component. See plans 95 and 98 for full analysis.
+ */
+let pendingCompact: { customInstructions?: string } | null = null;
+
+/**
+ * Commands the model is allowed to invoke.
+ * Maps command name → whether it's executable from tool context.
+ *
+ * - `true`: can be executed using ExtensionContext methods
+ * - `false`: requires ExtensionCommandContext (not available in tools)
+ */
+const ALLOWED_COMMANDS: ReadonlyMap<string, boolean> = new Map([
+	["show-system-prompt", true],
+	["context", true],
+	["compact", true],
+]);
+
+/** Human-readable descriptions for each bridged command. */
+const COMMAND_DESCRIPTIONS: ReadonlyMap<string, string> = new Map([
+	["show-system-prompt", "Returns the current system prompt text"],
+	["context", "Returns context window usage breakdown (tokens used/remaining per category)"],
+	["compact", "Triggers session compaction to free up context window space"],
+]);
+
+/**
+ * Formats context usage into a readable summary.
+ *
+ * @param usage - Context usage data from the session
+ * @returns Formatted string with token breakdown
+ */
+function formatContextUsage(usage: ContextUsage): string {
+	const tokens = usage.tokens ?? 0;
+	const pct = usage.contextWindow > 0 ? ((tokens / usage.contextWindow) * 100).toFixed(1) : "0";
+
+	const lines = [
+		`Context Usage: ${tokens.toLocaleString()} / ${usage.contextWindow.toLocaleString()} tokens (${pct}%)`,
+		`Free: ${Math.max(0, usage.contextWindow - tokens).toLocaleString()} tokens`,
+	];
+
+	return lines.join("\n");
+}
+
+/**
+ * Registers the slash-command-bridge tool and context injection.
+ *
+ * @param pi - Extension API for registering tools and event handlers
+ */
+export default function slashCommandBridge(pi: ExtensionAPI): void {
+	// Build the list of available command names for the tool description
+	const commandList = Array.from(ALLOWED_COMMANDS.keys())
+		.map((name) => `- ${name}: ${COMMAND_DESCRIPTIONS.get(name) ?? "No description"}`)
+		.join("\n");
+
+	pi.registerTool({
+		name: "run_slash_command",
+		label: "run_slash_command",
+		description: `Invoke a slash command programmatically. Use this when you need to perform session management or introspection actions.
+
+Available commands:
+${commandList}
+
+WHEN TO USE:
+- Need to check the system prompt for debugging
+- Need to see context window usage before deciding to compact
+- Need to compact the session to free up context space
+
+WHEN NOT TO USE:
+- The user already ran the command themselves
+- You want to start a new session (suggest the user run /clear instead)`,
+		parameters: Type.Object({
+			command: Type.String({
+				description:
+					"Slash command name (without the / prefix). " +
+					`One of: ${Array.from(ALLOWED_COMMANDS.keys()).join(", ")}`,
+			}),
+		}),
+
+		/**
+		 * Renders the tool call header showing which command is being invoked.
+		 *
+		 * @param args - Tool arguments containing the command name
+		 * @param theme - Theme for styling
+		 * @returns Text component with styled command display
+		 */
+		renderCall(args, theme) {
+			const cmd = args.command ?? "...";
+			return new Text(
+				theme.fg("toolTitle", theme.bold("run_slash_command ")) + theme.fg("accent", `/${cmd}`),
+				0,
+				0
+			);
+		},
+
+		/**
+		 * Executes the requested slash command.
+		 *
+		 * @param _toolCallId - Unique tool call identifier
+		 * @param params - Parameters containing the command name
+		 * @param _signal - Abort signal (unused)
+		 * @param _onUpdate - Update callback (unused)
+		 * @param ctx - Extension context with session access
+		 * @returns Tool result with command output
+		 */
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const { command } = params;
+
+			// Reject unknown commands
+			if (!ALLOWED_COMMANDS.has(command)) {
+				const available = Array.from(ALLOWED_COMMANDS.keys()).join(", ");
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Unknown command: "${command}". Available commands: ${available}`,
+						},
+					],
+					details: { command, error: "unknown_command" },
+					isError: true,
+				};
+			}
+
+			// Reject commands that need ExtensionCommandContext
+			if (!ALLOWED_COMMANDS.get(command)) {
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								`Command "/${command}" cannot be invoked by the model yet — it requires ` +
+								"user-level session control. Suggest the user run it directly.",
+						},
+					],
+					details: { command, error: "requires_command_context" },
+					isError: true,
+				};
+			}
+
+			// Dispatch to the appropriate handler
+			switch (command) {
+				case "show-system-prompt": {
+					const prompt = ctx.getSystemPrompt();
+					return {
+						content: [{ type: "text", text: prompt }],
+						details: { command, length: prompt.length },
+					};
+				}
+
+				case "context": {
+					const usage = ctx.getContextUsage();
+					if (!usage) {
+						return {
+							content: [
+								{
+									type: "text",
+									text: "No context usage data available yet. A message must be processed first.",
+								},
+							],
+							details: { command, error: "no_usage_data" },
+							isError: true,
+						};
+					}
+					return {
+						content: [{ type: "text", text: formatContextUsage(usage) }],
+						details: {
+							command,
+							tokens: usage.tokens ?? 0,
+							contextWindow: usage.contextWindow,
+						},
+					};
+				}
+
+				case "compact": {
+					// Don't call ctx.compact() here — it aborts the agent mid-tool-call,
+					// orphaning the tool execution spinner (plan 95/98). Defer to the
+					// agent_end hook so the tool completes normally first.
+					pendingCompact = { customInstructions: undefined };
+
+					return {
+						content: [
+							{
+								type: "text",
+								text:
+									"Session compaction will begin after this response completes. " +
+									"Do NOT call any more tools — finish your response so " +
+									"compaction can start.",
+							},
+						],
+						details: { command },
+					};
+				}
+
+				default: {
+					// Exhaustiveness guard — should never reach here
+					return {
+						content: [{ type: "text", text: `Unhandled command: ${command}` }],
+						details: { command, error: "unhandled" },
+						isError: true,
+					};
+				}
+			}
+		},
+	});
+
+	// ── Context injection ────────────────────────────────────────
+
+	pi.on("before_agent_start", async () => {
+		const bridgedCommands = Array.from(ALLOWED_COMMANDS.keys())
+			.map((name) => `/${name}`)
+			.join(", ");
+
+		return {
+			message: {
+				customType: "slash-command-bridge-context",
+				content:
+					`You can invoke these slash commands programmatically via the run_slash_command tool: ${bridgedCommands}. ` +
+					"For other slash commands, suggest the user run them directly.",
+				display: false,
+			},
+		};
+	});
+
+	// ── Deferred compact ─────────────────────────────────────────
+
+	/**
+	 * Fires compact after the agent finishes its turn. This avoids the
+	 * spinner-hang caused by aborting the agent mid-tool-execution.
+	 * The tool sets `pendingCompact`, then agent_end picks it up.
+	 */
+	pi.on("agent_end", (_event, ctx) => {
+		if (!pendingCompact) return;
+
+		const options = pendingCompact;
+		pendingCompact = null;
+
+		ctx.compact({
+			customInstructions: options.customInstructions,
+			onComplete: () => {
+				// Framework's executeCompaction rebuilds the UI and
+				// shows the compaction summary. No extra action needed.
+			},
+			onError: () => {
+				// Framework's executeCompaction handles error/cancel
+				// display. No extra handling needed.
+			},
+		});
+	});
+
+	/** Clear pending compact if the session switches before the turn ends. */
+	pi.on("session_before_switch", () => {
+		pendingCompact = null;
+	});
+}

package/extensions/stats/__tests__/aggregator.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Tests for stats aggregation: filtering, streaks, and aggregate calculations.
+ */
+import { describe, expect, it } from "bun:test";
+import {
+	aggregate,
+	calculateStreaks,
+	filterSessions,
+	parseCustomRange,
+	resolvePreset,
+} from "../aggregator.js";
+import type { SessionStats } from "../stats-log.js";
+
+// ── Fixtures ─────────────────────────────────────────────────────────────────
+
+/** Creates a minimal valid SessionStats for testing. */
+function makeStats(overrides: Partial<SessionStats> = {}): SessionStats {
+	return {
+		sessionId: "test-1",
+		startTime: "2026-02-15T10:00:00Z",
+		endTime: "2026-02-15T10:30:00Z",
+		durationMs: 1_800_000,
+		model: "claude-sonnet-4-5",
+		cwd: "/tmp",
+		totalInput: 1000,
+		totalOutput: 500,
+		totalCacheRead: 2000,
+		totalCacheWrite: 300,
+		totalCost: 0.05,
+		toolCounts: { read: 3, bash: 2 },
+		messageCount: 8,
+		...overrides,
+	};
+}
+
+// ── resolvePreset ────────────────────────────────────────────────────────────
+
+describe("resolvePreset", () => {
+	it("today starts at midnight", () => {
+		const range = resolvePreset("today");
+		expect(range.start.getHours()).toBe(0);
+		expect(range.start.getMinutes()).toBe(0);
+		expect(range.end.getTime()).toBeCloseTo(Date.now(), -3);
+	});
+
+	it("week goes back 7 days", () => {
+		const range = resolvePreset("week");
+		const diff = range.end.getTime() - range.start.getTime();
+		// Should be between 7 and 8 days (start is midnight, end is now)
+		expect(diff).toBeGreaterThan(6 * 86_400_000);
+		expect(diff).toBeLessThan(8 * 86_400_000);
+	});
+
+	it("month goes back 30 days", () => {
+		const range = resolvePreset("month");
+		const diff = range.end.getTime() - range.start.getTime();
+		expect(diff).toBeGreaterThan(29 * 86_400_000);
+		expect(diff).toBeLessThan(31 * 86_400_000);
+	});
+
+	it("all starts at epoch", () => {
+		const range = resolvePreset("all");
+		expect(range.start.getTime()).toBe(0);
+	});
+});
+
+// ── parseCustomRange ─────────────────────────────────────────────────────────
+
+describe("parseCustomRange", () => {
+	it("parses valid date range", () => {
+		const range = parseCustomRange("2026-01-01", "2026-01-31");
+		expect(range).not.toBeNull();
+		expect(range?.start.getFullYear()).toBe(2026);
+		expect(range?.end.getHours()).toBe(23);
+	});
+
+	it("returns null for invalid dates", () => {
+		expect(parseCustomRange("not-a-date", "2026-01-31")).toBeNull();
+		expect(parseCustomRange("2026-01-01", "nope")).toBeNull();
+	});
+
+	it("end date is inclusive (end of day)", () => {
+		const range = parseCustomRange("2026-02-01", "2026-02-01");
+		expect(range).not.toBeNull();
+		expect(range?.end.getHours()).toBe(23);
+		expect(range?.end.getMinutes()).toBe(59);
+	});
+});
+
+// ── filterSessions ───────────────────────────────────────────────────────────
+
+describe("filterSessions", () => {
+	const sessions = [
+		makeStats({ sessionId: "dec", startTime: "2025-12-15T12:00:00Z" }),
+		makeStats({ sessionId: "jan", startTime: "2026-01-15T12:00:00Z" }),
+		makeStats({ sessionId: "feb", startTime: "2026-02-15T12:00:00Z" }),
+	];
+
+	it("filters by time range", () => {
+		const range = parseCustomRange("2026-01-01", "2026-01-31") as NonNullable<
+			ReturnType<typeof parseCustomRange>
+		>;
+		const result = filterSessions(sessions, range);
+		expect(result).toHaveLength(1);
+		expect(result[0].sessionId).toBe("jan");
+	});
+
+	it("returns all for epoch-to-now range", () => {
+		const range = resolvePreset("all");
+		const result = filterSessions(sessions, range);
+		expect(result).toHaveLength(3);
+	});
+
+	it("returns empty for range with no sessions", () => {
+		const range = parseCustomRange("2024-01-01", "2024-12-31") as NonNullable<
+			ReturnType<typeof parseCustomRange>
+		>;
+		const result = filterSessions(sessions, range);
+		expect(result).toHaveLength(0);
+	});
+
+	it("filters by model (case-insensitive substring)", () => {
+		const mixed = [
+			makeStats({ sessionId: "s1", model: "claude-sonnet-4-5" }),
+			makeStats({ sessionId: "s2", model: "claude-opus-4" }),
+			makeStats({ sessionId: "s3", model: "gpt-4o" }),
+		];
+		const range = resolvePreset("all");
+
+		expect(filterSessions(mixed, range, "opus")).toHaveLength(1);
+		expect(filterSessions(mixed, range, "claude")).toHaveLength(2);
+		expect(filterSessions(mixed, range, "GPT")).toHaveLength(1);
+	});
+});
+
+// ── calculateStreaks ─────────────────────────────────────────────────────────
+
+describe("calculateStreaks", () => {
+	it("returns zeros for empty sessions", () => {
+		const result = calculateStreaks([]);
+		expect(result.current).toBe(0);
+		expect(result.longest).toBe(0);
+	});
+
+	it("counts single day as streak of 1", () => {
+		const today = new Date().toISOString();
+		const result = calculateStreaks([makeStats({ startTime: today })]);
+		expect(result.current).toBe(1);
+		expect(result.longest).toBe(1);
+	});
+
+	it("counts consecutive days", () => {
+		const now = Date.now();
+		const sessions = [
+			makeStats({ startTime: new Date(now).toISOString() }),
+			makeStats({ startTime: new Date(now - 86_400_000).toISOString() }),
+			makeStats({ startTime: new Date(now - 2 * 86_400_000).toISOString() }),
+		];
+		const result = calculateStreaks(sessions);
+		expect(result.current).toBe(3);
+		expect(result.longest).toBe(3);
+	});
+
+	it("handles gap in streak", () => {
+		const now = Date.now();
+		const sessions = [
+			makeStats({ startTime: new Date(now).toISOString() }),
+			// gap: skip yesterday
+			makeStats({ startTime: new Date(now - 3 * 86_400_000).toISOString() }),
+			makeStats({ startTime: new Date(now - 4 * 86_400_000).toISOString() }),
+		];
+		const result = calculateStreaks(sessions);
+		expect(result.current).toBe(1);
+		expect(result.longest).toBe(2);
+	});
+
+	it("multiple sessions on same day count as one", () => {
+		const today = new Date().toISOString().slice(0, 10);
+		const sessions = [
+			makeStats({ startTime: `${today}T09:00:00Z` }),
+			makeStats({ startTime: `${today}T14:00:00Z` }),
+			makeStats({ startTime: `${today}T20:00:00Z` }),
+		];
+		const result = calculateStreaks(sessions);
+		expect(result.current).toBe(1);
+		expect(result.longest).toBe(1);
+	});
+
+	it("current streak is 0 when last session was >1 day ago", () => {
+		const old = new Date(Date.now() - 5 * 86_400_000).toISOString();
+		const result = calculateStreaks([makeStats({ startTime: old })]);
+		expect(result.current).toBe(0);
+		expect(result.longest).toBe(1);
+	});
+
+	it("yesterday counts as current streak", () => {
+		const yesterday = new Date(Date.now() - 86_400_000).toISOString();
+		const result = calculateStreaks([makeStats({ startTime: yesterday })]);
+		expect(result.current).toBe(1);
+	});
+});
+
+// ── aggregate ────────────────────────────────────────────────────────────────
+
+describe("aggregate", () => {
+	it("returns zeros for empty sessions", () => {
+		const range = resolvePreset("all");
+		const result = aggregate([], [], range, "all");
+		expect(result.sessionCount).toBe(0);
+		expect(result.totalCost).toBe(0);
+		expect(result.rangeLabel).toBe("All time");
+	});
+
+	it("sums tokens and costs correctly", () => {
+		const sessions = [
+			makeStats({ totalInput: 100, totalOutput: 50, totalCost: 0.01 }),
+			makeStats({ totalInput: 200, totalOutput: 75, totalCost: 0.02 }),
+		];
+		const range = resolvePreset("all");
+		const result = aggregate(sessions, sessions, range);
+
+		expect(result.totalInput).toBe(300);
+		expect(result.totalOutput).toBe(125);
+		expect(result.totalCost).toBeCloseTo(0.03);
+		expect(result.sessionCount).toBe(2);
+	});
+
+	it("calculates averages", () => {
+		const sessions = [
+			makeStats({ totalCost: 0.1, messageCount: 10 }),
+			makeStats({ totalCost: 0.2, messageCount: 20 }),
+		];
+		const range = resolvePreset("all");
+		const result = aggregate(sessions, sessions, range);
+
+		expect(result.avgCostPerSession).toBeCloseTo(0.15);
+		expect(result.avgMessagesPerSession).toBe(15);
+	});
+
+	it("merges tool counts across sessions", () => {
+		const sessions = [
+			makeStats({ toolCounts: { read: 5, bash: 3 } }),
+			makeStats({ toolCounts: { read: 2, write: 1 } }),
+		];
+		const range = resolvePreset("all");
+		const result = aggregate(sessions, sessions, range);
+
+		expect(result.toolCounts.read).toBe(7);
+		expect(result.toolCounts.bash).toBe(3);
+		expect(result.toolCounts.write).toBe(1);
+	});
+
+	it("builds model breakdown sorted by session count", () => {
+		const sessions = [
+			makeStats({ model: "sonnet" }),
+			makeStats({ model: "sonnet" }),
+			makeStats({ model: "opus" }),
+		];
+		const range = resolvePreset("all");
+		const result = aggregate(sessions, sessions, range);
+
+		expect(result.modelBreakdown).toHaveLength(2);
+		expect(result.modelBreakdown[0].model).toBe("sonnet");
+		expect(result.modelBreakdown[0].sessions).toBe(2);
+		expect(result.modelBreakdown[1].model).toBe("opus");
+	});
+
+	it("uses preset label for named ranges", () => {
+		const range = resolvePreset("week");
+		const result = aggregate([], [], range, "week");
+		expect(result.rangeLabel).toBe("Last 7 days");
+	});
+
+	it("uses date label for custom ranges", () => {
+		const range = parseCustomRange("2026-01-01", "2026-01-31") as NonNullable<
+			ReturnType<typeof parseCustomRange>
+		>;
+		const result = aggregate([], [], range);
+		expect(result.rangeLabel).toBe("2026-01-01 to 2026-01-31");
+	});
+});

package/extensions/stats/__tests__/stats-log.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Tests for stats-log JSONL persistence: append, read, countSessions.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { SessionStats } from "../stats-log.js";
+import { appendStats, countSessions, readAllStats } from "../stats-log.js";
+
+// ── Fixtures ─────────────────────────────────────────────────────────────────
+
+/** Creates a minimal valid SessionStats for testing. */
+function makeStats(overrides: Partial<SessionStats> = {}): SessionStats {
+	return {
+		sessionId: "test-session-1",
+		startTime: "2026-02-15T10:00:00Z",
+		endTime: "2026-02-15T10:30:00Z",
+		durationMs: 1_800_000,
+		model: "claude-sonnet-4-5",
+		cwd: "/tmp/test",
+		totalInput: 1000,
+		totalOutput: 500,
+		totalCacheRead: 2000,
+		totalCacheWrite: 300,
+		totalCost: 0.05,
+		toolCounts: { read: 3, bash: 2 },
+		messageCount: 8,
+		...overrides,
+	};
+}
+
+// ── Test setup ───────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let logPath: string;
+
+beforeEach(() => {
+	tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "stats-test-"));
+	logPath = path.join(tmpDir, "stats.jsonl");
+});
+
+afterEach(() => {
+	fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// ── readAllStats ─────────────────────────────────────────────────────────────
+
+describe("readAllStats", () => {
+	it("returns empty array when file does not exist", () => {
+		expect(readAllStats(logPath)).toEqual([]);
+	});
+
+	it("returns empty array for empty file", () => {
+		fs.writeFileSync(logPath, "");
+		expect(readAllStats(logPath)).toEqual([]);
+	});
+
+	it("skips malformed lines", () => {
+		fs.writeFileSync(logPath, "not json\n{bad\n");
+		expect(readAllStats(logPath)).toEqual([]);
+	});
+
+	it("reads valid entries", () => {
+		const stats = makeStats();
+		fs.writeFileSync(logPath, `${JSON.stringify(stats)}\n`);
+
+		const result = readAllStats(logPath);
+		expect(result).toHaveLength(1);
+		expect(result[0].sessionId).toBe("test-session-1");
+		expect(result[0].totalCost).toBe(0.05);
+	});
+
+	it("reads multiple entries preserving order", () => {
+		const s1 = makeStats({ sessionId: "s1" });
+		const s2 = makeStats({ sessionId: "s2" });
+		fs.writeFileSync(logPath, `${JSON.stringify(s1)}\n${JSON.stringify(s2)}\n`);
+
+		const result = readAllStats(logPath);
+		expect(result).toHaveLength(2);
+		expect(result[0].sessionId).toBe("s1");
+		expect(result[1].sessionId).toBe("s2");
+	});
+
+	it("skips malformed lines but keeps valid ones", () => {
+		const valid = makeStats({ sessionId: "valid" });
+		fs.writeFileSync(logPath, `garbage\n${JSON.stringify(valid)}\n{broken\n`);
+
+		const result = readAllStats(logPath);
+		expect(result).toHaveLength(1);
+		expect(result[0].sessionId).toBe("valid");
+	});
+});
+
+// ── appendStats ──────────────────────────────────────────────────────────────
+
+describe("appendStats", () => {
+	it("creates file and parent dirs if missing", () => {
+		const nested = path.join(tmpDir, "a", "b", "stats.jsonl");
+		appendStats(makeStats(), nested);
+
+		expect(fs.existsSync(nested)).toBe(true);
+		const result = readAllStats(nested);
+		expect(result).toHaveLength(1);
+	});
+
+	it("appends to existing file", () => {
+		appendStats(makeStats({ sessionId: "first" }), logPath);
+		appendStats(makeStats({ sessionId: "second" }), logPath);
+
+		const result = readAllStats(logPath);
+		expect(result).toHaveLength(2);
+		expect(result[0].sessionId).toBe("first");
+		expect(result[1].sessionId).toBe("second");
+	});
+
+	it("writes valid JSON per line", () => {
+		appendStats(makeStats(), logPath);
+
+		const raw = fs.readFileSync(logPath, "utf-8");
+		const lines = raw.trim().split("\n");
+		expect(lines).toHaveLength(1);
+		expect(() => JSON.parse(lines[0])).not.toThrow();
+	});
+});
+
+// ── countSessions ────────────────────────────────────────────────────────────
+
+describe("countSessions", () => {
+	it("returns 0 when file does not exist", () => {
+		expect(countSessions(logPath)).toBe(0);
+	});
+
+	it("counts non-empty lines", () => {
+		appendStats(makeStats({ sessionId: "a" }), logPath);
+		appendStats(makeStats({ sessionId: "b" }), logPath);
+		appendStats(makeStats({ sessionId: "c" }), logPath);
+
+		expect(countSessions(logPath)).toBe(3);
+	});
+});