surgent 0.7.0-alpha.0

package/src/ui/components/scrollable-view.ts

@@ -0,0 +1,155 @@
+import { DynamicBorder, getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+  Key,
+  Markdown,
+  isFocusable,
+  type Component,
+  type Focusable,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import { Lines } from "./lines.js";
+import { Frame } from "./frame.js";
+import type { Keybindings } from "./keybound.js";
+
+export type ScrollableViewOptions = {
+  markdown: string;
+  input?: Component & Partial<Focusable>;
+};
+
+export class ScrollableView extends Frame implements Focusable {
+  onCancel?: () => void;
+
+  private readonly markdownView: Markdown;
+  private input: (Component & Partial<Focusable>) | undefined;
+  private contentScrollOffset = 0;
+  private lastViewportHeight = 1;
+  private lastMarkdownLineCount = 0;
+  private editing: boolean = false;
+  private _focused = false;
+
+  constructor(
+    private readonly tui: TUI,
+    theme: Theme,
+    options: ScrollableViewOptions,
+  ) {
+    super(theme);
+
+    this.input = options.input;
+    this.markdownView = new Markdown(options.markdown, 0, 0, getMarkdownTheme());
+
+    const keybindings: Keybindings = [
+      { key: Key.escape, hint: "discard and exit", handler: () => this.onCancel?.() },
+      {
+        key: { navigation: "vertical" },
+        hint: "navigate",
+        navigate: (data) => this.scrollBy(data as "up" | "down"),
+      },
+      {
+        key: { navigation: "page" },
+        hint: "page",
+        navigate: (data) => this.scrollBy(data as "pageUp" | "pageDown"),
+      },
+    ];
+
+    if (this.input) {
+      keybindings.push({
+        key: Key.tab,
+        hint: "switch focus",
+        handler: () => {
+          this.editing = !this.editing;
+          this.setArrowKeyAccess({ navigation: "page" }, !this.editing);
+          this.setArrowKeyAccess({ navigation: "vertical" }, { consumable: !this.editing });
+          this.syncInputFocus();
+        },
+      });
+    }
+
+    this.registerKeybindings(keybindings);
+    this.syncInputFocus();
+  }
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.syncInputFocus();
+  }
+
+  override get hints(): [string, string][] {
+    return [["enter", "select"], ...super.hints];
+  }
+
+  override invalidate() {
+    super.invalidate();
+    this.markdownView.invalidate();
+    this.input?.invalidate();
+  }
+
+  handleInput(data: string) {
+    if (data === "\n" || this.handleKb(data) || !this.editing) return;
+    this.input?.handleInput?.(data);
+  }
+
+  protected override children(width: number): string[] {
+    const contentWidth = Math.max(6, width - 1);
+    const childHeightBudget = Math.max(1, this.tui.terminal.rows - 10);
+
+    const lines = new Lines(contentWidth);
+    const border = new DynamicBorder((s) => this.theme.fg(this.editing ? "accent" : "dim", s));
+
+    const inputCandidates = this.input ? this.input.render(contentWidth) : [];
+    const maxInputLineCount = inputCandidates.length > 0 ? Math.max(0, childHeightBudget - 1) : 0;
+    const inputLines = inputCandidates.slice(-maxInputLineCount);
+    const inputSectionRows = inputLines.length > 0 ? inputLines.length + 1 : 0;
+
+    this.lastViewportHeight = Math.max(0, childHeightBudget - inputSectionRows);
+
+    const markdownLines = this.markdownView.render(contentWidth);
+    this.lastMarkdownLineCount = markdownLines.length;
+    this.clampScrollOffset(markdownLines.length);
+
+    const viewportStartIndex = this.contentScrollOffset;
+    const viewportEndIndex = viewportStartIndex + this.lastViewportHeight;
+    const visibleMarkdownLines = markdownLines.slice(viewportStartIndex, viewportEndIndex);
+
+    for (const markdownLine of visibleMarkdownLines) {
+      lines.add(markdownLine);
+    }
+
+    lines.space();
+    lines.add(border.render(contentWidth)[0]!);
+
+    if (inputLines.length > 0) {
+      lines.space();
+      for (const inputLine of inputLines) {
+        lines.add(inputLine);
+      }
+    }
+
+    return lines.get();
+  }
+
+  private scrollBy(data: "up" | "down" | "pageUp" | "pageDown") {
+    let amount: number;
+    if (data === "up") amount = -2;
+    else if (data === "down") amount = 2;
+    else if (data === "pageUp") amount = -Math.max(1, this.lastViewportHeight - 1);
+    else amount = Math.max(1, this.lastViewportHeight - 1);
+
+    this.contentScrollOffset += amount;
+    this.clampScrollOffset();
+  }
+
+  private clampScrollOffset(totalMarkdownLines?: number) {
+    const lineCount = totalMarkdownLines ?? this.lastMarkdownLineCount;
+    const maxOffset = Math.max(0, lineCount - this.lastViewportHeight);
+    this.contentScrollOffset = Math.max(0, Math.min(maxOffset, this.contentScrollOffset));
+  }
+
+  private syncInputFocus() {
+    if (!this.input || !isFocusable(this.input)) return;
+    this.input.focused = this._focused && this.editing;
+  }
+}

package/src/ui/index.ts

@@ -0,0 +1,40 @@
+import { VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+import ModeIndicatorEditor from "./components/input-mode-indicator.js";
+import { readFileSync } from "node:fs";
+
+const PACKAGE_JSON_PATH = new URL("../../package.json", import.meta.url);
+const packageJson = JSON.parse(readFileSync(PACKAGE_JSON_PATH, "utf8")) as {
+  name: string;
+  version: string;
+};
+
+const APP_NAME = packageJson.name;
+const APP_VERSION = packageJson.version;
+const BASH_MODE_HOTKEY = Key.ctrlAlt("b");
+
+export default function (pi: ExtensionAPI) {
+  let activeEditor: ModeIndicatorEditor | undefined;
+
+  pi.registerShortcut(BASH_MODE_HOTKEY, {
+    description: "Cycle input mode (prompt / bash (included in context) / normal bash)",
+    handler: () => activeEditor?.cycleMode(),
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    ctx.ui.setHeader((_tui, theme) => ({
+      render: () => [
+        `${theme.bold(theme.fg("accent", APP_NAME))}${theme.fg("dim", ` v${APP_VERSION} · built on top of pi v${PI_VERSION}`)}`,
+      ],
+      invalidate() {},
+    }));
+
+    ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+      activeEditor = new ModeIndicatorEditor(tui, theme, keybindings, ctx.ui.theme);
+      return activeEditor;
+    });
+  });
+}

package/src/utils.ts

@@ -0,0 +1,206 @@
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  keyHint,
+  SettingsManager,
+  Theme,
+  truncateToVisualLines,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { Spacer, Text } from "@earendil-works/pi-tui";
+import { Container } from "@earendil-works/pi-tui";
+
+const PI_PATHS = {
+  web: "web-results",
+  agents: "agents",
+  settings: "settings.json",
+  mcp: "mcp.json",
+  permissions: "permissions.json",
+  checkpoints: "checkpoints",
+  subsessions: "subsessions.json",
+  subsessionsDir: "subsessions",
+  plans: "plans",
+  grammars: "grammars",
+  system: "SYSTEM.md",
+} as const;
+
+type PathKey = keyof typeof PI_PATHS;
+
+export function getPiPath(key: PathKey, scope: "global", ...path: string[]): string;
+export function getPiPath(key: PathKey, cwd: string, ...path: string[]): string;
+export function getPiPath(key: PathKey): string;
+export function getPiPath(key: PathKey, ...full: string[]): string {
+  const path = PI_PATHS[key];
+  const remaining = path.includes(".") ? [] : full.slice(1);
+  const isGlobal = !full[0] || full[0] === "global";
+  const baseDir = isGlobal ? homedir() : full[0]!;
+  const piPath = isGlobal ? [".pi", "agent"] : [".pi"];
+  return join(baseDir, ...piPath, path, ...remaining);
+}
+
+export async function readJson<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8")) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeJson(filePath: string, data: unknown) {
+  await writeFile(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+export async function runCommand(
+  cwd: string,
+  command: string,
+  argumentsList: string[],
+  options?: { signal?: AbortSignal; successExitCodes?: number[]; abortMessage?: string },
+): Promise<{ stdout: string; stderr: string; exitCode: number | null }> {
+  const abortMessage = options?.abortMessage ?? "command aborted";
+  if (options?.signal?.aborted) {
+    throw new Error(abortMessage);
+  }
+
+  return await new Promise<{ stdout: string; stderr: string; exitCode: number | null }>(
+    (resolveCommand, rejectCommand) => {
+      const executable = process.platform === "win32" ? `${command}.cmd` : command;
+      const childProcess = spawn(executable, argumentsList, {
+        cwd,
+        env: process.env,
+        signal: options?.signal,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      childProcess.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+
+      childProcess.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+
+      childProcess.on("error", (error) => {
+        rejectCommand(error);
+      });
+
+      childProcess.on("close", (exitCode) => {
+        if (options?.signal?.aborted) {
+          rejectCommand(new Error(abortMessage));
+          return;
+        }
+
+        const successExitCodes = options?.successExitCodes ?? [0];
+        if (!successExitCodes.includes(exitCode ?? -1)) {
+          const commandText = `${command} ${argumentsList.join(" ")}`;
+          const stderrText = stderr.trim();
+          rejectCommand(
+            new Error(
+              `${commandText} failed with exit code ${exitCode ?? "unknown"}${stderrText ? `: ${stderrText}` : ""}`,
+            ),
+          );
+          return;
+        }
+
+        resolveCommand({ stdout, stderr, exitCode });
+      });
+    },
+  );
+}
+
+export async function openInEditor(
+  ctx: ExtensionCommandContext,
+  filePath: string,
+): Promise<boolean> {
+  const command = SettingsManager.create(ctx.cwd, undefined, {
+    projectTrusted: ctx.isProjectTrusted(),
+  }).getExternalEditorCommand();
+  const commandParts = tokenizeArgs(command);
+  const editor = commandParts.shift();
+  if (!editor) {
+    ctx.ui.notify("External editor command is empty", "error");
+    return false;
+  }
+
+  const exitCode = await new Promise<number | null>((resolvePromise) => {
+    const child = spawn(editor, [...commandParts, filePath], {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    child.on("error", () => resolvePromise(null));
+    child.on("close", (code) => resolvePromise(code));
+  });
+
+  if (exitCode === 0) return true;
+  ctx.ui.notify(`Failed to open ${filePath}. Set externalEditor, VISUAL, or EDITOR.`, "error");
+  return false;
+}
+
+export function normalizeText(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function unique<T>(values: Iterable<T>): T[] {
+  return [...new Set(values)];
+}
+
+export function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function tokenizeArgs(args: string): string[] {
+  return args
+    .split(/\s+/)
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+export function customText(text: string, pad?: { x?: number; y?: number }) {
+  const { x = 0, y = 0 } = pad ?? {};
+  return new Text(text, x, y);
+}
+
+export function isMissingFileError(error: any) {
+  return Boolean(error) && typeof error === "object" && "code" in error && error.code === "ENOENT";
+}
+
+export function isUuidv7(input: string): boolean {
+  const pattern = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return pattern.test(input);
+}
+
+export function renderCallText(text: string, isPartial: boolean) {
+  const container = new Container();
+  container.addChild(new Text(text, 0, 0));
+  if (!isPartial) {
+    container.addChild(new Spacer(1));
+  }
+  return container;
+}
+
+export function renderResultText(text: string, theme: Theme, expanded: boolean) {
+  if (expanded) {
+    return new Text(theme.fg("toolOutput", text), 0, 0);
+  }
+  return {
+    render(width: number) {
+      const result = truncateToVisualLines(text, 10, width);
+      const lines = result.visualLines.map((line) => theme.fg("toolOutput", line));
+      if (result.skippedCount > 0) {
+        lines.push(
+          `${theme.fg("toolOutput", `... (${result.skippedCount} more lines,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("toolOutput", ")")}`,
+        );
+      }
+      return lines;
+    },
+    invalidate() {},
+  };
+}

package/src/web-tools/index.ts

@@ -0,0 +1,15 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import webLoginCommand from "./web-login/index.js";
+import webFetchTool from "./web-fetch/index.js";
+import { getArgumentCompletions } from "./web-login/helpers.js";
+import webSearchTool from "./web-search/index.js";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("web-login", {
+    description: "Configure API keys for authenticated web providers",
+    getArgumentCompletions,
+    handler: webLoginCommand,
+  });
+  pi.registerTool(webFetchTool);
+  pi.registerTool(webSearchTool);
+}

package/src/web-tools/providers/brave.ts

@@ -0,0 +1,55 @@
+import { getHttpError, joinSnippets, normalizeSearchResult } from "../web-search/helpers.js";
+import type { WebSearchResult } from "../web-search/types.js";
+import { isDefined } from "../../utils.js";
+import type { WebSearchProvider } from "./index.js";
+
+interface BraveSearchItem {
+  title?: string;
+  description?: string;
+  snippet?: string;
+  url?: string;
+  extra_snippets?: string[];
+  meta_url?: { href?: string };
+}
+
+interface BraveSearchResponse {
+  news?: { results?: BraveSearchItem[] };
+  web?: { results?: BraveSearchItem[] };
+}
+
+export class BraveWebSearchProvider implements WebSearchProvider {
+  constructor(private readonly apiKey: string) {}
+
+  async search(query: string, news: boolean, max: number): Promise<WebSearchResult[]> {
+    const endpoint = news ? "news/search" : "web/search";
+    const searchParams = new URLSearchParams({
+      count: String(max),
+      extra_snippets: "true",
+      q: query,
+    });
+
+    const response = await fetch(
+      `https://api.search.brave.com/res/v1/${endpoint}?${searchParams.toString()}`,
+      {
+        headers: { Accept: "application/json", "X-Subscription-Token": this.apiKey },
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error(await getHttpError(response));
+    }
+
+    const payload = (await response.json()) as BraveSearchResponse;
+    const items = (news ? payload.news : payload.web)?.results ?? [];
+
+    return items
+      .map((item) =>
+        normalizeSearchResult({
+          description: item.description ?? item.snippet ?? joinSnippets(item.extra_snippets),
+          title: item.title,
+          url: item.url ?? item.meta_url?.href,
+        }),
+      )
+      .filter(isDefined);
+  }
+}

package/src/web-tools/providers/firecrawl.ts

@@ -0,0 +1,66 @@
+import { formatErrorMessage, normalizeFetchedContent } from "../web-fetch/helpers.js";
+import type { WebFetchResponse } from "../web-fetch/types.js";
+import { normalizeSearchResult } from "../web-search/helpers.js";
+import type { WebSearchResult } from "../web-search/types.js";
+import { isDefined } from "../../utils.js";
+import Firecrawl from "@mendable/firecrawl-js";
+import type { WebFetchProvider, WebSearchProvider } from "./index.js";
+
+interface FirecrawlSearchItem {
+  title?: string;
+  description?: string;
+  snippet?: string;
+  url?: string;
+}
+
+interface FirecrawlSearchResponse {
+  news?: FirecrawlSearchItem[];
+  web?: FirecrawlSearchItem[];
+}
+
+interface FirecrawlDocument {
+  markdown?: string;
+  metadata?: { sourceURL?: string; ogUrl?: string };
+}
+
+export class FirecrawlProvider implements WebSearchProvider, WebFetchProvider {
+  constructor(private readonly apiKey: string) {}
+
+  async search(query: string, news: boolean, max: number): Promise<WebSearchResult[]> {
+    const client = new Firecrawl({ apiKey: this.apiKey });
+    const source = news ? "news" : "web";
+    const response = (await client.search(query, {
+      limit: max,
+      sources: [source],
+    })) as FirecrawlSearchResponse;
+    const items = news ? (response.news ?? []) : (response.web ?? []);
+
+    return items
+      .map((item) =>
+        normalizeSearchResult({
+          description: item.description ?? item.snippet,
+          title: item.title,
+          url: item.url,
+        }),
+      )
+      .filter(isDefined);
+  }
+
+  async fetch(url: string): Promise<WebFetchResponse> {
+    const client = new Firecrawl({ apiKey: this.apiKey });
+    try {
+      const document = (await client.scrape(url, {
+        formats: ["markdown", "html"],
+      })) as FirecrawlDocument;
+      const content = normalizeFetchedContent(document?.markdown);
+
+      if (!content) {
+        return { provider: "firecrawl", url, error: "Firecrawl returned no markdown content." };
+      }
+
+      return { provider: "firecrawl", content, url };
+    } catch (error) {
+      return { provider: "firecrawl", url, error: formatErrorMessage(error) };
+    }
+  }
+}

package/src/web-tools/providers/index.ts

@@ -0,0 +1,50 @@
+import type { WebFetchProviderId, WebFetchResponse } from "../web-fetch/types.js";
+import type { WebToolsProviderId } from "../web-login/types.js";
+import type { WebSearchProviderId, WebSearchResult } from "../web-search/types.js";
+import { BraveWebSearchProvider } from "./brave.js";
+import { FirecrawlProvider } from "./firecrawl.js";
+import { JinaWebFetchProvider } from "./jina.js";
+import { NativeWebFetchProvider } from "./native.js";
+import { TavilyProvider } from "./tavily.js";
+
+export interface WebSearchProvider {
+  search(query: string, news: boolean, max: number): Promise<WebSearchResult[]>;
+}
+
+export interface WebFetchProvider {
+  fetch(url: string): Promise<WebFetchResponse>;
+}
+
+export class WebToolsFactory {
+  createWebSearcher(name: WebSearchProviderId, apiKey?: string): WebSearchProvider {
+    switch (name) {
+      case "brave-search":
+        return new BraveWebSearchProvider(this.requireApiKey(name, apiKey));
+      case "firecrawl":
+        return new FirecrawlProvider(this.requireApiKey(name, apiKey));
+      case "tavily":
+        return new TavilyProvider(this.requireApiKey(name, apiKey));
+    }
+  }
+
+  createWebFetcher(name: WebFetchProviderId, apiKey?: string): WebFetchProvider {
+    switch (name) {
+      case "native":
+        return new NativeWebFetchProvider();
+      case "jina":
+        return new JinaWebFetchProvider(apiKey);
+      case "firecrawl":
+        return new FirecrawlProvider(this.requireApiKey(name, apiKey));
+      case "tavily":
+        return new TavilyProvider(this.requireApiKey(name, apiKey));
+    }
+  }
+
+  private requireApiKey(name: WebToolsProviderId, apiKey?: string): string {
+    if (!apiKey) {
+      throw new Error(`Provider ${name} requires an API key.`);
+    }
+
+    return apiKey;
+  }
+}

package/src/web-tools/providers/jina.ts

@@ -0,0 +1,48 @@
+import { formatErrorMessage, getHttpError, normalizeFetchedContent } from "../web-fetch/helpers.js";
+import type { WebFetchResponse } from "../web-fetch/types.js";
+import type { WebFetchProvider } from "./index.js";
+
+export class JinaWebFetchProvider implements WebFetchProvider {
+  constructor(private readonly apiKey?: string) {}
+
+  async fetch(url: string): Promise<WebFetchResponse> {
+    try {
+      const response = await fetch(this.toJinaUrl(url), {
+        headers: {
+          Accept: "text/plain, text/markdown;q=0.9",
+          ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(await getHttpError(response));
+      }
+
+      const body = normalizeFetchedContent(await response.text());
+      const content = this.extractJinaMarkdown(body);
+
+      if (!content) {
+        throw new Error("Jina returned empty content.");
+      }
+
+      return { provider: "jina", content, url };
+    } catch (error) {
+      return { provider: "jina", url, error: formatErrorMessage(error) };
+    }
+  }
+
+  private toJinaUrl(url: string): string {
+    return `https://r.jina.ai/http://${url.replace(/^https?:\/\//, "")}`;
+  }
+
+  private extractJinaMarkdown(body: string): string {
+    const marker = "Markdown Content:";
+    const markerIndex = body.indexOf(marker);
+
+    if (markerIndex === -1) {
+      return body;
+    }
+
+    return body.slice(markerIndex + marker.length).trim();
+  }
+}

package/src/web-tools/providers/native.ts

@@ -0,0 +1,57 @@
+import TurndownService from "turndown";
+import {
+  formatErrorMessage,
+  getHttpError,
+  isTextLikeContentType,
+  normalizeFetchedContent,
+} from "../web-fetch/helpers.js";
+import type { WebFetchResponse } from "../web-fetch/types.js";
+import type { WebFetchProvider } from "./index.js";
+
+export class NativeWebFetchProvider implements WebFetchProvider {
+  private readonly turndown = new TurndownService();
+
+  async fetch(url: string): Promise<WebFetchResponse> {
+    try {
+      const response = await fetch(url, {
+        headers: {
+          Accept: "text/html, text/plain, text/markdown;q=0.9, */*;q=0.1",
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(await getHttpError(response));
+      }
+
+      const contentType = response.headers.get("content-type");
+      if (!isTextLikeContentType(contentType)) {
+        throw new Error(`Unsupported content type: ${contentType ?? "unknown"}`);
+      }
+
+      const rawBody = await response.text();
+      const content = this.normalizeContent(rawBody, contentType);
+
+      if (!content) {
+        throw new Error("Native fetch returned empty content.");
+      }
+
+      return { provider: "native", content, url };
+    } catch (error) {
+      return { provider: "native", url, error: formatErrorMessage(error) };
+    }
+  }
+
+  private normalizeContent(body: string, contentType: string | null): string {
+    if (this.looksLikeHtml(body, contentType)) {
+      return normalizeFetchedContent(this.turndown.turndown(body));
+    }
+
+    return normalizeFetchedContent(body);
+  }
+
+  private looksLikeHtml(body: string, contentType: string | null): boolean {
+    const normalizedType = (contentType ?? "").toLowerCase();
+
+    return normalizedType.includes("html") || /<html[\s>]/i.test(body) || /<body[\s>]/i.test(body);
+  }
+}