@skaft/hamr 0.4.1

package/examples/extensions/hamr-browser/src/targeting.ts

@@ -0,0 +1,79 @@
+import type { Locator, Page } from "playwright";
+
+export type ParsedTarget =
+	| { kind: "css"; value: string }
+	| { kind: "text"; value: string }
+	| { kind: "role"; role: string; name: string };
+
+const DEFAULT_SCROLL_PIXELS = 600;
+
+function looksLikeCssSelector(target: string): boolean {
+	return /^[#.\[]/.test(target) || /^[a-z][\w-]*(?:[#.\[:\s>+~]|$)/.test(target);
+}
+
+export function parseTarget(input: string): ParsedTarget {
+	const target = input.trim();
+	if (!target) {
+		throw new Error("Target is required");
+	}
+
+	if (target.startsWith("css=")) {
+		return { kind: "css", value: target.slice("css=".length).trim() };
+	}
+	if (target.startsWith("text=")) {
+		return { kind: "text", value: target.slice("text=".length).trim() };
+	}
+	if (target.startsWith("role=")) {
+		const roleTarget = target.slice("role=".length);
+		const separator = roleTarget.indexOf(":");
+		if (separator === -1) {
+			throw new Error("Role target must look like role=button:Submit");
+		}
+		return {
+			kind: "role",
+			role: roleTarget.slice(0, separator).trim(),
+			name: roleTarget.slice(separator + 1).trim(),
+		};
+	}
+	if (looksLikeCssSelector(target)) {
+		return { kind: "css", value: target };
+	}
+	return { kind: "text", value: target };
+}
+
+export function locatorForTarget(page: Page, target: string): Locator {
+	const parsed = parseTarget(target);
+	switch (parsed.kind) {
+		case "css":
+			return page.locator(parsed.value).first();
+		case "role":
+			return page.getByRole(parsed.role as never, { name: parsed.name }).first();
+		case "text":
+			return page.getByText(parsed.value, { exact: false }).first();
+	}
+}
+
+export function normalizeScrollAmount(directionOrPixels: string | number): { x: number; y: number } {
+	if (typeof directionOrPixels === "number") {
+		return { x: 0, y: directionOrPixels };
+	}
+
+	const value = directionOrPixels.trim().toLowerCase();
+	const numeric = Number(value);
+	if (Number.isFinite(numeric)) {
+		return { x: 0, y: numeric };
+	}
+
+	switch (value) {
+		case "up":
+			return { x: 0, y: -DEFAULT_SCROLL_PIXELS };
+		case "down":
+			return { x: 0, y: DEFAULT_SCROLL_PIXELS };
+		case "left":
+			return { x: -DEFAULT_SCROLL_PIXELS, y: 0 };
+		case "right":
+			return { x: DEFAULT_SCROLL_PIXELS, y: 0 };
+		default:
+			throw new Error("Scroll must be up, down, left, right, or a pixel count");
+	}
+}

package/examples/extensions/hamr-browser/test/deps.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { getBrowserDepsDir, getBrowserDepsInstallCommand, getHamrAgentDir } from "../src/deps.ts";
+
+describe("Hamr Browser dependency install paths", () => {
+	it("uses the Hamr agent dir for lazy browser dependencies", () => {
+		expect(getHamrAgentDir({ HAMR_CODING_AGENT_DIR: "/tmp/hamr-agent" })).toBe("/tmp/hamr-agent");
+		expect(getBrowserDepsDir({ HAMR_CODING_AGENT_DIR: "/tmp/hamr-agent" })).toBe("/tmp/hamr-agent/browser-deps");
+	});
+
+	it("allows explicitly overriding the dependency directory", () => {
+		expect(getBrowserDepsDir({ HAMR_BROWSER_DEPS_DIR: "/tmp/browser-deps" })).toBe("/tmp/browser-deps");
+	});
+
+	it("installs Playwright into the lazy dependency directory", () => {
+		expect(getBrowserDepsInstallCommand("/tmp/browser-deps")).toEqual([
+			"npm",
+			"install",
+			"--prefix",
+			"/tmp/browser-deps",
+			"playwright@^1.57.0",
+		]);
+	});
+});

package/examples/extensions/hamr-browser/test/paths.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { getDefaultBrowserProfileDir, getDefaultScreenshotDir } from "../src/paths.ts";
+
+describe("Hamr Browser paths", () => {
+  it("uses ~/.hamr/browser-profile on macOS and Linux", () => {
+    expect(getDefaultBrowserProfileDir("darwin", "/Users/alice", {})).toBe("/Users/alice/.hamr/browser-profile");
+    expect(getDefaultBrowserProfileDir("linux", "/home/alice", {})).toBe("/home/alice/.hamr/browser-profile");
+  });
+
+  it("uses LOCALAPPDATA on Windows when available", () => {
+    expect(
+      getDefaultBrowserProfileDir("win32", "C:/Users/Alice", { LOCALAPPDATA: "C:/Users/Alice/AppData/Local" }),
+    ).toBe("C:/Users/Alice/AppData/Local/Hamr/browser-profile");
+  });
+
+  it("falls back to home AppData/Local on Windows", () => {
+    expect(getDefaultBrowserProfileDir("win32", "C:/Users/Alice", {})).toBe(
+      "C:/Users/Alice/AppData/Local/Hamr/browser-profile",
+    );
+  });
+
+  it("stores screenshots under a Hamr browser artifacts directory", () => {
+    expect(getDefaultScreenshotDir("/home/alice")).toBe("/home/alice/.hamr/browser-artifacts/screenshots");
+  });
+});

package/examples/extensions/hamr-browser/test/targeting.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { normalizeScrollAmount, parseTarget } from "../src/targeting.ts";
+
+describe("target parsing", () => {
+  it("keeps explicit css selectors", () => {
+    expect(parseTarget("css=#submit")).toEqual({ kind: "css", value: "#submit" });
+  });
+
+  it("recognizes role targets", () => {
+    expect(parseTarget("role=button:Submit")).toEqual({ kind: "role", role: "button", name: "Submit" });
+  });
+
+  it("uses text matching for plain strings", () => {
+    expect(parseTarget("Continue")).toEqual({ kind: "text", value: "Continue" });
+  });
+});
+
+describe("scroll amount parsing", () => {
+  it("maps directions to default pixel amounts", () => {
+    expect(normalizeScrollAmount("down")).toEqual({ x: 0, y: 600 });
+    expect(normalizeScrollAmount("up")).toEqual({ x: 0, y: -600 });
+  });
+
+  it("accepts numeric pixel strings", () => {
+    expect(normalizeScrollAmount("-250")).toEqual({ x: 0, y: -250 });
+  });
+});

package/examples/extensions/hamr-browser/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.examples.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node", "vitest/globals"],
+    "lib": ["ES2022", "DOM"],
+    "skipLibCheck": true
+  },
+  "include": ["index.ts", "src/**/*.ts", "test/**/*.ts"]
+}

package/examples/extensions/handoff.ts

@@ -0,0 +1,191 @@
+/**
+ * Handoff extension - transfer context to a new focused session
+ *
+ * Instead of compacting (which is lossy), handoff extracts what matters
+ * for your next task and creates a new session with a generated prompt.
+ *
+ * Usage:
+ *   /handoff now implement this for teams as well
+ *   /handoff execute phase one of the plan
+ *   /handoff check other places that need this fix
+ *
+ * The generated prompt appears as a draft in the editor for review/editing.
+ */
+
+import type { AgentMessage } from "@hamr/agent";
+import { complete, type Message } from "@hamr/ai";
+import type { ExtensionAPI, SessionEntry } from "@hamr/coding-agent";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@hamr/coding-agent";
+
+const SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:
+
+1. Summarizes relevant context from the conversation (decisions made, approaches taken, key findings)
+2. Lists any relevant files that were discussed or modified
+3. Clearly states the next task based on the user's goal
+4. Is self-contained - the new thread should be able to proceed without the old conversation
+
+Format your response as a prompt the user can send to start the new thread. Be concise but include all necessary context. Do not include any preamble like "Here's the prompt" - just output the prompt itself.
+
+Example output format:
+## Context
+We've been working on X. Key decisions:
+- Decision 1
+- Decision 2
+
+Files involved:
+- path/to/file1.ts
+- path/to/file2.ts
+
+## Task
+[Clear description of what to do next based on user's goal]`;
+
+function entryToMessage(entry: SessionEntry): AgentMessage | undefined {
+	if (entry.type === "message") {
+		return entry.message;
+	}
+	if (entry.type === "compaction") {
+		return {
+			role: "compactionSummary",
+			summary: entry.summary,
+			tokensBefore: entry.tokensBefore,
+			timestamp: new Date(entry.timestamp).getTime(),
+		};
+	}
+	return undefined;
+}
+
+function getHandoffMessages(branch: SessionEntry[]): AgentMessage[] {
+	let compactionIndex = -1;
+	for (let i = branch.length - 1; i >= 0; i--) {
+		if (branch[i].type === "compaction") {
+			compactionIndex = i;
+			break;
+		}
+	}
+	if (compactionIndex < 0) {
+		return branch.map(entryToMessage).filter((message) => message !== undefined);
+	}
+
+	const compaction = branch[compactionIndex];
+	const firstKeptIndex =
+		compaction.type === "compaction" ? branch.findIndex((entry) => entry.id === compaction.firstKeptEntryId) : -1;
+	const compactedBranch = [
+		compaction,
+		...(firstKeptIndex >= 0 ? branch.slice(firstKeptIndex, compactionIndex) : []),
+		...branch.slice(compactionIndex + 1),
+	];
+	return compactedBranch.map(entryToMessage).filter((message) => message !== undefined);
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("handoff", {
+		description: "Transfer context to a new focused session",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("handoff requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+				return;
+			}
+
+			// Gather conversation context from current branch. If the branch was compacted,
+			// include the compaction summary plus entries from firstKeptEntryId onward.
+			const messages = getHandoffMessages(ctx.sessionManager.getBranch());
+
+			if (messages.length === 0) {
+				ctx.ui.notify("No conversation to hand off", "error");
+				return;
+			}
+
+			// Convert to LLM format and serialize
+			const llmMessages = convertToLlm(messages);
+			const conversationText = serializeConversation(llmMessages);
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+			// Generate the handoff prompt with loader UI
+			const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+				const loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);
+				loader.onAbort = () => done(null);
+
+				const doGenerate = async () => {
+					const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model!);
+					if (!auth.ok || !auth.apiKey) {
+						throw new Error(auth.ok ? `No API key for ${ctx.model!.provider}` : auth.error);
+					}
+
+					const userMessage: Message = {
+						role: "user",
+						content: [
+							{
+								type: "text",
+								text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
+							},
+						],
+						timestamp: Date.now(),
+					};
+
+					const response = await complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey: auth.apiKey, headers: auth.headers, signal: loader.signal },
+					);
+
+					if (response.stopReason === "aborted") {
+						return null;
+					}
+
+					return response.content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				};
+
+				doGenerate()
+					.then(done)
+					.catch((err) => {
+						console.error("Handoff generation failed:", err);
+						done(null);
+					});
+
+				return loader;
+			});
+
+			if (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Let user edit the generated prompt
+			const editedPrompt = await ctx.ui.editor("Edit handoff prompt", result);
+
+			if (editedPrompt === undefined) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Create new session with parent tracking. Use the replacement-session
+			// context for post-switch UI work; the original ctx is stale after a
+			// successful session replacement.
+			const newSessionResult = await ctx.newSession({
+				parentSession: currentSessionFile,
+				withSession: async (replacementCtx) => {
+					replacementCtx.ui.setEditorText(editedPrompt);
+					replacementCtx.ui.notify("Handoff ready. Submit when ready.", "info");
+				},
+			});
+
+			if (newSessionResult.cancelled) {
+				ctx.ui.notify("New session cancelled", "info");
+			}
+		},
+	});
+}

package/examples/extensions/hello.ts

@@ -0,0 +1,26 @@
+/**
+ * Hello Tool - Minimal custom tool example
+ */
+
+import { Type } from "@hamr/ai";
+import { defineTool, type ExtensionAPI } from "@hamr/coding-agent";
+
+const helloTool = defineTool({
+	name: "hello",
+	label: "Hello",
+	description: "A simple greeting tool",
+	parameters: Type.Object({
+		name: Type.String({ description: "Name to greet" }),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+		return {
+			content: [{ type: "text", text: `Hello, ${params.name}!` }],
+			details: { greeted: params.name },
+		};
+	},
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool(helloTool);
+}

package/examples/extensions/hidden-thinking-label.ts

@@ -0,0 +1,53 @@
+/**
+ * Hidden Thinking Label Extension
+ *
+ * Demonstrates `ctx.ui.setHiddenThinkingLabel()` for customizing the label shown
+ * when thinking blocks are hidden.
+ *
+ * Usage:
+ *   pi --extension examples/extensions/hidden-thinking-label.ts
+ *
+ * Test:
+ *   1. Load this extension
+ *   2. Hide thinking blocks with Ctrl+T
+ *   3. Ask for something that produces reasoning output
+ *   4. The collapsed thinking block label will show the custom text
+ *
+ * Commands:
+ *   /thinking-label <text>   Set a custom hidden thinking label
+ *   /thinking-label          Reset to the default label
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@hamr/coding-agent";
+
+const DEFAULT_LABEL = "Pondering...";
+
+export default function (pi: ExtensionAPI) {
+	let label = DEFAULT_LABEL;
+
+	const applyLabel = (ctx: ExtensionContext) => {
+		ctx.ui.setHiddenThinkingLabel(label);
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		applyLabel(ctx);
+	});
+
+	pi.registerCommand("thinking-label", {
+		description: "Set the hidden thinking label. Use without args to reset.",
+		handler: async (args, ctx) => {
+			const nextLabel = args.trim();
+
+			if (!nextLabel) {
+				label = DEFAULT_LABEL;
+				ctx.ui.setHiddenThinkingLabel();
+				ctx.ui.notify(`Hidden thinking label reset to: ${DEFAULT_LABEL}`);
+				return;
+			}
+
+			label = nextLabel;
+			ctx.ui.setHiddenThinkingLabel(label);
+			ctx.ui.notify(`Hidden thinking label set to: ${label}`);
+		},
+	});
+}

package/examples/extensions/inline-bash.ts

@@ -0,0 +1,94 @@
+/**
+ * Inline Bash Extension - expands inline bash commands in user prompts.
+ *
+ * Start pi with this extension:
+ *   pi -e ./examples/extensions/inline-bash.ts
+ *
+ * Then type prompts with inline bash:
+ *   What's in !{pwd}?
+ *   The current branch is !{git branch --show-current} and status: !{git status --short}
+ *   My node version is !{node --version}
+ *
+ * The !{command} patterns are executed and replaced with their output before
+ * the prompt is sent to the agent.
+ *
+ * Note: Regular !command syntax (whole-line bash) is preserved and works as before.
+ */
+import type { ExtensionAPI } from "@hamr/coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	const PATTERN = /!\{([^}]+)\}/g;
+	const TIMEOUT_MS = 30000;
+
+	pi.on("input", async (event, ctx) => {
+		const text = event.text;
+
+		// Don't process if it's a whole-line bash command (starts with !)
+		// This preserves the existing !command behavior
+		if (text.trimStart().startsWith("!") && !text.trimStart().startsWith("!{")) {
+			return { action: "continue" };
+		}
+
+		// Check if there are any inline bash patterns
+		if (!PATTERN.test(text)) {
+			return { action: "continue" };
+		}
+
+		// Reset regex state after test()
+		PATTERN.lastIndex = 0;
+
+		let result = text;
+		const expansions: Array<{ command: string; output: string; error?: string }> = [];
+
+		// Find all matches first (to avoid issues with replacing while iterating)
+		const matches: Array<{ full: string; command: string }> = [];
+		let match = PATTERN.exec(text);
+		while (match) {
+			matches.push({ full: match[0], command: match[1] });
+			match = PATTERN.exec(text);
+		}
+
+		// Execute each command and collect results
+		for (const { full, command } of matches) {
+			try {
+				const bashResult = await pi.exec("bash", ["-c", command], {
+					timeout: TIMEOUT_MS,
+				});
+
+				const output = bashResult.stdout || bashResult.stderr || "";
+				const trimmed = output.trim();
+
+				if (bashResult.code !== 0 && bashResult.stderr) {
+					expansions.push({
+						command,
+						output: trimmed,
+						error: `exit code ${bashResult.code}`,
+					});
+				} else {
+					expansions.push({ command, output: trimmed });
+				}
+
+				result = result.replace(full, trimmed);
+			} catch (err) {
+				const errorMsg = err instanceof Error ? err.message : String(err);
+				expansions.push({ command, output: "", error: errorMsg });
+				result = result.replace(full, `[error: ${errorMsg}]`);
+			}
+		}
+
+		// Show what was expanded (if UI available)
+		if (ctx.hasUI && expansions.length > 0) {
+			const summary = expansions
+				.map((e) => {
+					const status = e.error ? ` (${e.error})` : "";
+					const preview = e.output.length > 50 ? `${e.output.slice(0, 50)}...` : e.output;
+					return `!{${e.command}}${status} -> "${preview}"`;
+				})
+				.join("\n");
+
+			ctx.ui.notify(`Expanded ${expansions.length} inline command(s):\n${summary}`, "info");
+		}
+
+		return { action: "transform", text: result, images: event.images };
+	});
+}

package/examples/extensions/input-transform-streaming.ts

@@ -0,0 +1,39 @@
+/**
+ * Streaming-Aware Input Gate
+ *
+ * Demonstrates `event.streamingBehavior` to skip expensive pre-processing
+ * during mid-stream steering, where low latency matters.
+ *
+ * This extension prepends `git diff --stat` output when the user mentions
+ * file changes, giving the model immediate context. During steering the
+ * exec call is skipped so the correction reaches the model without delay.
+ *
+ * Start pi with this extension:
+ *   pi -e ./examples/extensions/input-transform-streaming.ts
+ */
+import type { ExtensionAPI } from "@hamr/coding-agent";
+
+const TRIGGER = /\b(changes?|diff|modified)\b/i;
+
+export default function (pi: ExtensionAPI) {
+	pi.on("input", async (event) => {
+		// During steering, skip the exec call — corrections should be fast
+		if (event.streamingBehavior === "steer") {
+			return { action: "continue" };
+		}
+
+		if (!TRIGGER.test(event.text)) {
+			return { action: "continue" };
+		}
+
+		const { stdout, code } = await pi.exec("git", ["diff", "--stat"]);
+		if (code !== 0 || !stdout.trim()) {
+			return { action: "continue" };
+		}
+
+		return {
+			action: "transform",
+			text: `${event.text}\n\nCurrent uncommitted changes:\n\`\`\`\n${stdout.trim()}\n\`\`\``,
+		};
+	});
+}

package/examples/extensions/input-transform.ts

@@ -0,0 +1,43 @@
+/**
+ * Input Transform Example - demonstrates the `input` event for intercepting user input.
+ *
+ * Start pi with this extension:
+ *   pi -e ./examples/extensions/input-transform.ts
+ *
+ * Then type these inside pi:
+ *   ?quick What is TypeScript?  → "Respond briefly: What is TypeScript?"
+ *   ping                        → "pong" (instant, no LLM)
+ *   time                        → current time (instant, no LLM)
+ */
+import type { ExtensionAPI } from "@hamr/coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("input", async (event, ctx) => {
+		// Source-based logic: skip processing for extension-injected messages
+		if (event.source === "extension") {
+			return { action: "continue" };
+		}
+
+		// Transform: ?quick prefix for brief responses
+		if (event.text.startsWith("?quick ")) {
+			const query = event.text.slice(7).trim();
+			if (!query) {
+				ctx.ui.notify("Usage: ?quick <question>", "warning");
+				return { action: "handled" };
+			}
+			return { action: "transform", text: `Respond briefly in 1-2 sentences: ${query}` };
+		}
+
+		// Handle: instant responses without LLM (extension shows its own feedback)
+		if (event.text.toLowerCase() === "ping") {
+			ctx.ui.notify("pong", "info");
+			return { action: "handled" };
+		}
+		if (event.text.toLowerCase() === "time") {
+			ctx.ui.notify(new Date().toLocaleString(), "info");
+			return { action: "handled" };
+		}
+
+		return { action: "continue" };
+	});
+}