@companion-ai/feynman 0.2.0

package/dist/search/commands.js

@@ -0,0 +1,12 @@
+import { getPiWebAccessStatus } from "../pi/web-access.js";
+import { printInfo } from "../ui/terminal.js";
+export function printSearchStatus() {
+    const status = getPiWebAccessStatus();
+    printInfo("Managed by: pi-web-access");
+    printInfo(`Search route: ${status.routeLabel}`);
+    printInfo(`Request route: ${status.requestProvider}`);
+    printInfo(`Perplexity API configured: ${status.perplexityConfigured ? "yes" : "no"}`);
+    printInfo(`Gemini API configured: ${status.geminiApiConfigured ? "yes" : "no"}`);
+    printInfo(`Browser profile: ${status.chromeProfile ?? "default Chromium profile"}`);
+    printInfo(`Config path: ${status.configPath}`);
+}

package/dist/setup/doctor.js

@@ -0,0 +1,126 @@
+import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+import { getUserName as getAlphaUserName, isLoggedIn as isAlphaLoggedIn } from "@companion-ai/alpha-hub/lib";
+import { formatPiWebAccessDoctorLines, getPiWebAccessStatus } from "../pi/web-access.js";
+import { BROWSER_FALLBACK_PATHS, PANDOC_FALLBACK_PATHS, resolveExecutable } from "../system/executables.js";
+import { readJson } from "../pi/settings.js";
+import { validatePiInstallation } from "../pi/runtime.js";
+import { printInfo, printPanel, printSection } from "../ui/terminal.js";
+import { getCurrentModelSpec } from "../model/commands.js";
+import { buildModelStatusSnapshotFromRecords, getAvailableModelRecords, getSupportedModelRecords } from "../model/catalog.js";
+export function collectStatusSnapshot(options) {
+    const pandocPath = resolveExecutable("pandoc", PANDOC_FALLBACK_PATHS);
+    const browserPath = process.env.PUPPETEER_EXECUTABLE_PATH ?? resolveExecutable("google-chrome", BROWSER_FALLBACK_PATHS);
+    const missingPiBits = validatePiInstallation(options.appRoot);
+    const webStatus = getPiWebAccessStatus();
+    const modelStatus = buildModelStatusSnapshotFromRecords(getSupportedModelRecords(options.authPath), getAvailableModelRecords(options.authPath), getCurrentModelSpec(options.settingsPath));
+    return {
+        model: modelStatus.current,
+        modelValid: modelStatus.currentValid,
+        recommendedModel: modelStatus.recommended,
+        recommendedModelReason: modelStatus.recommendationReason,
+        authenticatedModelCount: modelStatus.availableModels.length,
+        authenticatedProviderCount: modelStatus.providers.filter((provider) => provider.configured).length,
+        modelGuidance: modelStatus.guidance,
+        alphaLoggedIn: isAlphaLoggedIn(),
+        alphaUser: isAlphaLoggedIn() ? getAlphaUserName() ?? undefined : undefined,
+        webRouteLabel: webStatus.routeLabel,
+        previewConfigured: Boolean(pandocPath),
+        sessionDir: options.sessionDir,
+        pandocReady: Boolean(pandocPath),
+        browserReady: Boolean(browserPath),
+        piReady: missingPiBits.length === 0,
+        missingPiBits,
+    };
+}
+export function runStatus(options) {
+    const snapshot = collectStatusSnapshot(options);
+    printPanel("Feynman Status", [
+        "Current setup summary for the research shell.",
+    ]);
+    printSection("Core");
+    printInfo(`Model: ${snapshot.model ?? "not configured"}`);
+    printInfo(`Model valid: ${snapshot.modelValid ? "yes" : "no"}`);
+    printInfo(`Authenticated models: ${snapshot.authenticatedModelCount}`);
+    printInfo(`Authenticated providers: ${snapshot.authenticatedProviderCount}`);
+    printInfo(`Recommended model: ${snapshot.recommendedModel ?? "not available"}`);
+    printInfo(`alphaXiv: ${snapshot.alphaLoggedIn ? snapshot.alphaUser ?? "configured" : "not configured"}`);
+    printInfo(`Web access: pi-web-access (${snapshot.webRouteLabel})`);
+    printInfo(`Preview: ${snapshot.previewConfigured ? "configured" : "not configured"}`);
+    printSection("Paths");
+    printInfo(`Sessions: ${snapshot.sessionDir}`);
+    printSection("Runtime");
+    printInfo(`Pi runtime: ${snapshot.piReady ? "ready" : "missing files"}`);
+    printInfo(`Pandoc: ${snapshot.pandocReady ? "ready" : "missing"}`);
+    printInfo(`Browser preview: ${snapshot.browserReady ? "ready" : "missing"}`);
+    if (snapshot.missingPiBits.length > 0) {
+        for (const entry of snapshot.missingPiBits) {
+            printInfo(`  missing: ${entry}`);
+        }
+    }
+    if (snapshot.modelGuidance.length > 0) {
+        printSection("Next Steps");
+        for (const line of snapshot.modelGuidance) {
+            printInfo(line);
+        }
+    }
+}
+export function runDoctor(options) {
+    const settings = readJson(options.settingsPath);
+    const modelRegistry = new ModelRegistry(AuthStorage.create(options.authPath));
+    const availableModels = modelRegistry.getAvailable();
+    const pandocPath = resolveExecutable("pandoc", PANDOC_FALLBACK_PATHS);
+    const browserPath = process.env.PUPPETEER_EXECUTABLE_PATH ?? resolveExecutable("google-chrome", BROWSER_FALLBACK_PATHS);
+    const missingPiBits = validatePiInstallation(options.appRoot);
+    printPanel("Feynman Doctor", [
+        "Checks config, auth, runtime wiring, and preview dependencies.",
+    ]);
+    console.log(`working dir: ${options.workingDir}`);
+    console.log(`session dir: ${options.sessionDir}`);
+    console.log("");
+    console.log(`alphaXiv auth: ${isAlphaLoggedIn() ? "ok" : "missing"}`);
+    if (isAlphaLoggedIn()) {
+        const name = getAlphaUserName();
+        if (name) {
+            console.log(`  user: ${name}`);
+        }
+    }
+    console.log(`models available: ${availableModels.length}`);
+    if (availableModels.length > 0) {
+        const sample = availableModels
+            .slice(0, 6)
+            .map((model) => `${model.provider}/${model.id}`)
+            .join(", ");
+        console.log(`  sample: ${sample}`);
+    }
+    console.log(`default model: ${typeof settings.defaultProvider === "string" && typeof settings.defaultModel === "string"
+        ? `${settings.defaultProvider}/${settings.defaultModel}`
+        : "not set"}`);
+    const modelStatus = collectStatusSnapshot(options);
+    console.log(`default model valid: ${modelStatus.modelValid ? "yes" : "no"}`);
+    console.log(`authenticated providers: ${modelStatus.authenticatedProviderCount}`);
+    console.log(`authenticated models: ${modelStatus.authenticatedModelCount}`);
+    console.log(`recommended model: ${modelStatus.recommendedModel ?? "not available"}`);
+    if (modelStatus.recommendedModelReason) {
+        console.log(`  why: ${modelStatus.recommendedModelReason}`);
+    }
+    console.log(`pandoc: ${pandocPath ?? "missing"}`);
+    console.log(`browser preview runtime: ${browserPath ?? "missing"}`);
+    for (const line of formatPiWebAccessDoctorLines()) {
+        console.log(line);
+    }
+    console.log(`quiet startup: ${settings.quietStartup === true ? "enabled" : "disabled"}`);
+    console.log(`theme: ${typeof settings.theme === "string" ? settings.theme : "not set"}`);
+    if (missingPiBits.length > 0) {
+        console.log("pi runtime: missing files");
+        for (const entry of missingPiBits) {
+            console.log(`  ${entry}`);
+        }
+    }
+    else {
+        console.log("pi runtime: ok");
+    }
+    for (const line of modelStatus.modelGuidance) {
+        console.log(`next step: ${line}`);
+    }
+    console.log("setup hint: feynman setup");
+}

package/dist/setup/preview.js

@@ -0,0 +1,20 @@
+import { spawnSync } from "node:child_process";
+import { BREW_FALLBACK_PATHS, PANDOC_FALLBACK_PATHS, resolveExecutable } from "../system/executables.js";
+export function setupPreviewDependencies() {
+    const pandocPath = resolveExecutable("pandoc", PANDOC_FALLBACK_PATHS);
+    if (pandocPath) {
+        return { status: "ready", message: `pandoc already installed at ${pandocPath}` };
+    }
+    const brewPath = resolveExecutable("brew", BREW_FALLBACK_PATHS);
+    if (process.platform === "darwin" && brewPath) {
+        const result = spawnSync(brewPath, ["install", "pandoc"], { stdio: "inherit" });
+        if (result.status !== 0) {
+            throw new Error("Failed to install pandoc via Homebrew.");
+        }
+        return { status: "installed", message: "Preview dependency installed: pandoc" };
+    }
+    return {
+        status: "manual",
+        message: "pandoc is required for preview support. Install it manually and rerun `feynman --doctor`.",
+    };
+}

package/dist/setup/prompts.js

@@ -0,0 +1,29 @@
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+export async function promptText(question, defaultValue = "") {
+    if (!input.isTTY || !output.isTTY) {
+        throw new Error("feynman setup requires an interactive terminal.");
+    }
+    const rl = createInterface({ input, output });
+    try {
+        const suffix = defaultValue ? ` [${defaultValue}]` : "";
+        const value = (await rl.question(`${question}${suffix}: `)).trim();
+        return value || defaultValue;
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function promptChoice(question, choices, defaultIndex = 0) {
+    console.log(question);
+    for (const [index, choice] of choices.entries()) {
+        const marker = index === defaultIndex ? "*" : " ";
+        console.log(`  ${marker} ${index + 1}. ${choice}`);
+    }
+    const answer = await promptText("Select", String(defaultIndex + 1));
+    const parsed = Number(answer);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > choices.length) {
+        return defaultIndex;
+    }
+    return parsed - 1;
+}

package/dist/setup/setup.js

@@ -0,0 +1,119 @@
+import { isLoggedIn as isAlphaLoggedIn, login as loginAlpha } from "@companion-ai/alpha-hub/lib";
+import { getDefaultSessionDir, getFeynmanHome } from "../config/paths.js";
+import { getPiWebAccessStatus, getPiWebSearchConfigPath } from "../pi/web-access.js";
+import { normalizeFeynmanSettings } from "../pi/settings.js";
+import { getCurrentModelSpec, runModelSetup } from "../model/commands.js";
+import { buildModelStatusSnapshotFromRecords, getAvailableModelRecords, getSupportedModelRecords } from "../model/catalog.js";
+import { PANDOC_FALLBACK_PATHS, resolveExecutable } from "../system/executables.js";
+import { promptText } from "./prompts.js";
+import { setupPreviewDependencies } from "./preview.js";
+import { runDoctor } from "./doctor.js";
+import { printInfo, printPanel, printSection, printSuccess } from "../ui/terminal.js";
+async function explainWebAccess() {
+    const status = getPiWebAccessStatus();
+    printSection("Web Access");
+    printInfo("Feynman uses the bundled `pi-web-access` package directly.");
+    printInfo("Default v1 path: sign into gemini.google.com in a supported Chromium browser.");
+    printInfo(`Current search route: ${status.routeLabel}`);
+    printInfo(`Pi config path: ${status.configPath}`);
+    printInfo("Advanced users can edit the Pi config directly if they want API keys or a different route.");
+}
+function isPreviewConfigured() {
+    return Boolean(resolveExecutable("pandoc", PANDOC_FALLBACK_PATHS));
+}
+function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function printNonInteractiveSetupGuidance() {
+    printPanel("Feynman Setup", [
+        "Non-interactive terminal detected.",
+    ]);
+    printInfo("Use the explicit commands instead of the interactive setup wizard:");
+    printInfo("  feynman status");
+    printInfo("  feynman model login <provider>");
+    printInfo("  feynman model set <provider/model>");
+    printInfo("  feynman search status");
+    printInfo(`  edit ${getPiWebSearchConfigPath()}    # optional advanced web config`);
+    printInfo("  feynman alpha login");
+    printInfo("  feynman doctor");
+    printInfo("  feynman   # Pi's /login flow still works inside chat if you prefer it");
+}
+async function runPreviewSetup() {
+    const result = setupPreviewDependencies();
+    printSuccess(result.message);
+}
+function printConfigurationLocation(appRoot) {
+    printSection("Configuration Location");
+    printInfo(`Data folder:  ${getFeynmanHome()}`);
+    printInfo(`Sessions:     ${getDefaultSessionDir()}`);
+    printInfo(`Install dir:  ${appRoot}`);
+}
+function printSetupSummary(settingsPath, authPath) {
+    const modelStatus = buildModelStatusSnapshotFromRecords(getSupportedModelRecords(authPath), getAvailableModelRecords(authPath), getCurrentModelSpec(settingsPath));
+    printSection("Setup Summary");
+    printInfo(`Model: ${getCurrentModelSpec(settingsPath) ?? "not set"}`);
+    printInfo(`Model valid: ${modelStatus.currentValid ? "yes" : "no"}`);
+    printInfo(`Recommended model: ${modelStatus.recommended ?? "not available"}`);
+    printInfo(`alphaXiv: ${isAlphaLoggedIn() ? "configured" : "missing"}`);
+    printInfo(`Web access: pi-web-access (${getPiWebAccessStatus().routeLabel})`);
+    printInfo(`Preview: ${isPreviewConfigured() ? "configured" : "not configured"}`);
+    for (const line of modelStatus.guidance) {
+        printInfo(line);
+    }
+}
+async function runFullSetup(options) {
+    printConfigurationLocation(options.appRoot);
+    await runModelSetup(options.settingsPath, options.authPath);
+    if (!isAlphaLoggedIn()) {
+        await loginAlpha();
+        printSuccess("alphaXiv login complete");
+    }
+    else {
+        printInfo("alphaXiv login already configured");
+    }
+    await explainWebAccess();
+    await runPreviewSetup();
+    normalizeFeynmanSettings(options.settingsPath, options.bundledSettingsPath, options.defaultThinkingLevel ?? "medium", options.authPath);
+    runDoctor({
+        settingsPath: options.settingsPath,
+        authPath: options.authPath,
+        sessionDir: options.sessionDir,
+        workingDir: options.workingDir,
+        appRoot: options.appRoot,
+    });
+    printSetupSummary(options.settingsPath, options.authPath);
+}
+function hasExistingSetup(settingsPath, authPath) {
+    const modelStatus = buildModelStatusSnapshotFromRecords(getSupportedModelRecords(authPath), getAvailableModelRecords(authPath), getCurrentModelSpec(settingsPath));
+    return Boolean(modelStatus.current ||
+        modelStatus.availableModels.length > 0 ||
+        isAlphaLoggedIn() ||
+        isPreviewConfigured());
+}
+async function runDefaultInteractiveSetup(options) {
+    const existing = hasExistingSetup(options.settingsPath, options.authPath);
+    printPanel("Feynman Setup Wizard", [
+        "Guided setup for the research-first Pi agent.",
+        "Press Ctrl+C at any time to exit.",
+    ]);
+    if (existing) {
+        printSection("Full Setup");
+        printInfo("Existing configuration detected. Rerunning the full guided setup.");
+    }
+    else {
+        printInfo("We'll walk you through:");
+        printInfo("  1. Model Selection");
+        printInfo("  2. alphaXiv Login");
+        printInfo("  3. Preview Dependencies");
+    }
+    printInfo("Press Enter to begin, or Ctrl+C to exit.");
+    await promptText("Press Enter to start");
+    await runFullSetup(options);
+}
+export async function runSetup(options) {
+    if (!isInteractiveTerminal()) {
+        printNonInteractiveSetupGuidance();
+        return;
+    }
+    await runDefaultInteractiveSetup(options);
+}

package/dist/system/executables.js

@@ -0,0 +1,38 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+export const PANDOC_FALLBACK_PATHS = [
+    "/opt/homebrew/bin/pandoc",
+    "/usr/local/bin/pandoc",
+];
+export const BREW_FALLBACK_PATHS = [
+    "/opt/homebrew/bin/brew",
+    "/usr/local/bin/brew",
+];
+export const BROWSER_FALLBACK_PATHS = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+];
+export const MERMAID_FALLBACK_PATHS = [
+    "/opt/homebrew/bin/mmdc",
+    "/usr/local/bin/mmdc",
+];
+export function resolveExecutable(name, fallbackPaths = []) {
+    for (const candidate of fallbackPaths) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    const result = spawnSync("sh", ["-lc", `command -v ${name}`], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.status === 0) {
+        const resolved = result.stdout.trim();
+        if (resolved) {
+            return resolved;
+        }
+    }
+    return undefined;
+}

package/dist/system/promise-polyfill.js

@@ -0,0 +1,12 @@
+if (typeof Promise.withResolvers !== "function") {
+    Promise.withResolvers = function withResolvers() {
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        return { promise, resolve, reject };
+    };
+}
+export {};

package/dist/ui/terminal.js

@@ -0,0 +1,53 @@
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+function rgb(red, green, blue) {
+    return `\x1b[38;2;${red};${green};${blue}m`;
+}
+// Match the outer CLI to the bundled Feynman Pi theme instead of generic magenta panels.
+const INK = rgb(211, 198, 170);
+const STONE = rgb(157, 169, 160);
+const ASH = rgb(133, 146, 137);
+const DARK_ASH = rgb(92, 106, 114);
+const SAGE = rgb(167, 192, 128);
+const TEAL = rgb(127, 187, 179);
+const ROSE = rgb(230, 126, 128);
+function paint(text, ...codes) {
+    return `${codes.join("")}${text}${RESET}`;
+}
+export function printInfo(text) {
+    console.log(paint(`  ${text}`, ASH));
+}
+export function printSuccess(text) {
+    console.log(paint(`✓ ${text}`, SAGE, BOLD));
+}
+export function printWarning(text) {
+    console.log(paint(`⚠ ${text}`, STONE, BOLD));
+}
+export function printError(text) {
+    console.log(paint(`✗ ${text}`, ROSE, BOLD));
+}
+export function printSection(title) {
+    console.log("");
+    console.log(paint(`◆ ${title}`, TEAL, BOLD));
+}
+export function printPanel(title, subtitleLines = []) {
+    const inner = 53;
+    const border = "─".repeat(inner + 2);
+    const renderLine = (text, color, bold = false) => {
+        const content = text.length > inner ? `${text.slice(0, inner - 3)}...` : text;
+        const codes = bold ? `${color}${BOLD}` : color;
+        return `${DARK_ASH}${BOLD}│${RESET} ${codes}${content.padEnd(inner)}${RESET} ${DARK_ASH}${BOLD}│${RESET}`;
+    };
+    console.log("");
+    console.log(paint(`┌${border}┐`, DARK_ASH, BOLD));
+    console.log(renderLine(title, TEAL, true));
+    if (subtitleLines.length > 0) {
+        console.log(paint(`├${border}┤`, DARK_ASH, BOLD));
+        for (const line of subtitleLines) {
+            console.log(renderLine(line, INK));
+        }
+    }
+    console.log(paint(`└${border}┘`, DARK_ASH, BOLD));
+    console.log("");
+}

package/dist/web-search.js

@@ -0,0 +1 @@
+export { formatPiWebAccessDoctorLines, getPiWebAccessStatus, getPiWebSearchConfigPath, loadPiWebAccessConfig, } from "./pi/web-access.js";

package/extensions/research-tools/alpha.ts

@@ -0,0 +1,212 @@
+import {
+	annotatePaper,
+	askPaper,
+	clearPaperAnnotation,
+	disconnect,
+	getPaper,
+	getUserName as getAlphaUserName,
+	isLoggedIn as isAlphaLoggedIn,
+	listPaperAnnotations,
+	login as loginAlpha,
+	logout as logoutAlpha,
+	readPaperCode,
+	searchPapers,
+} from "@companion-ai/alpha-hub/lib";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+import { getExtensionCommandSpec } from "../../metadata/commands.mjs";
+import { formatToolText } from "./shared.js";
+
+export function registerAlphaCommands(pi: ExtensionAPI): void {
+	pi.registerCommand("alpha-login", {
+		description: getExtensionCommandSpec("alpha-login")?.description ?? "Sign in to alphaXiv from inside Feynman.",
+		handler: async (_args, ctx) => {
+			if (isAlphaLoggedIn()) {
+				const name = getAlphaUserName();
+				ctx.ui.notify(name ? `alphaXiv already connected as ${name}` : "alphaXiv already connected", "info");
+				return;
+			}
+
+			await loginAlpha();
+			const name = getAlphaUserName();
+			ctx.ui.notify(name ? `alphaXiv connected as ${name}` : "alphaXiv login complete", "info");
+		},
+	});
+
+	pi.registerCommand("alpha-logout", {
+		description: getExtensionCommandSpec("alpha-logout")?.description ?? "Clear alphaXiv auth from inside Feynman.",
+		handler: async (_args, ctx) => {
+			logoutAlpha();
+			ctx.ui.notify("alphaXiv auth cleared", "info");
+		},
+	});
+
+	pi.registerCommand("alpha-status", {
+		description: getExtensionCommandSpec("alpha-status")?.description ?? "Show alphaXiv authentication status.",
+		handler: async (_args, ctx) => {
+			if (!isAlphaLoggedIn()) {
+				ctx.ui.notify("alphaXiv not connected", "warning");
+				return;
+			}
+
+			const name = getAlphaUserName();
+			ctx.ui.notify(name ? `alphaXiv connected as ${name}` : "alphaXiv connected", "info");
+		},
+	});
+}
+
+export function registerAlphaTools(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "alpha_search",
+		label: "Alpha Search",
+		description: "Search papers through alphaXiv using semantic, keyword, both, agentic, or all retrieval modes.",
+		parameters: Type.Object({
+			query: Type.String({ description: "Paper search query." }),
+			mode: Type.Optional(
+				Type.String({
+					description: "Search mode: semantic, keyword, both, agentic, or all.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params) {
+			try {
+				const result = await searchPapers(params.query, params.mode?.trim() || "all");
+				return {
+					content: [{ type: "text", text: formatToolText(result) }],
+					details: result,
+				};
+			} finally {
+				await disconnect();
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_get_paper",
+		label: "Alpha Get Paper",
+		description: "Fetch a paper report or full text, plus any local annotation, using alphaXiv.",
+		parameters: Type.Object({
+			paper: Type.String({
+				description: "arXiv ID, arXiv URL, or alphaXiv URL.",
+			}),
+			fullText: Type.Optional(
+				Type.Boolean({
+					description: "Return raw full text instead of the AI report.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params) {
+			try {
+				const result = await getPaper(params.paper, { fullText: params.fullText });
+				return {
+					content: [{ type: "text", text: formatToolText(result) }],
+					details: result,
+				};
+			} finally {
+				await disconnect();
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_ask_paper",
+		label: "Alpha Ask Paper",
+		description: "Ask a targeted question about a paper using alphaXiv's PDF analysis.",
+		parameters: Type.Object({
+			paper: Type.String({
+				description: "arXiv ID, arXiv URL, or alphaXiv URL.",
+			}),
+			question: Type.String({
+				description: "Question to ask about the paper.",
+			}),
+		}),
+		async execute(_toolCallId, params) {
+			try {
+				const result = await askPaper(params.paper, params.question);
+				return {
+					content: [{ type: "text", text: formatToolText(result) }],
+					details: result,
+				};
+			} finally {
+				await disconnect();
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_annotate_paper",
+		label: "Alpha Annotate Paper",
+		description: "Write or clear a persistent local annotation for a paper.",
+		parameters: Type.Object({
+			paper: Type.String({
+				description: "Paper ID to annotate.",
+			}),
+			note: Type.Optional(
+				Type.String({
+					description: "Annotation text. Omit when clear=true.",
+				}),
+			),
+			clear: Type.Optional(
+				Type.Boolean({
+					description: "Clear the existing annotation instead of writing one.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params) {
+			const result = params.clear
+				? await clearPaperAnnotation(params.paper)
+				: params.note
+					? await annotatePaper(params.paper, params.note)
+					: (() => {
+							throw new Error("Provide either note or clear=true.");
+						})();
+
+			return {
+				content: [{ type: "text", text: formatToolText(result) }],
+				details: result,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_list_annotations",
+		label: "Alpha List Annotations",
+		description: "List all persistent local paper annotations.",
+		parameters: Type.Object({}),
+		async execute() {
+			const result = await listPaperAnnotations();
+			return {
+				content: [{ type: "text", text: formatToolText(result) }],
+				details: result,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_read_code",
+		label: "Alpha Read Code",
+		description: "Read files from a paper's GitHub repository through alphaXiv.",
+		parameters: Type.Object({
+			githubUrl: Type.String({
+				description: "GitHub repository URL for the paper implementation.",
+			}),
+			path: Type.Optional(
+				Type.String({
+					description: "Repository path to inspect. Use / for the repo overview.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params) {
+			try {
+				const result = await readPaperCode(params.githubUrl, params.path?.trim() || "/");
+				return {
+					content: [{ type: "text", text: formatToolText(result) }],
+					details: result,
+				};
+			} finally {
+				await disconnect();
+			}
+		},
+	});
+}