@mammothb/pi-web 6.0.0

package/src/lib/searxng-manager.ts

@@ -0,0 +1,293 @@
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { expandTilde } from "@mammothb/pi-shared";
+
+const __dirname = new URL(".", import.meta.url).pathname;
+
+function getScriptPath(): string {
+  // From src/lib/ go up 2 levels to package root, then bin/searxng
+  return join(__dirname, "..", "..", "bin", "searxng");
+}
+
+export function getInstancesDir(): string {
+  return join(getAgentDir(), "searxng-instances");
+}
+
+/** Result of a shutdown health check. */
+export interface ShutdownState {
+  /** Number of PID files whose process is dead (unclean shutdown). */
+  uncleanCount: number;
+  /** Number of PID files whose process is still alive (shutdown in progress). */
+  stillRunning: number;
+  /**
+   * Remove the shutdown PID files that were just inspected.
+   * Call after reporting health status so stale files don't
+   * trigger false positives on the next startup.
+   */
+  cleanup(): void;
+}
+
+/**
+ * Check whether a PID is alive by sending signal 0.
+ */
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove lock files belonging to dead PIDs.
+ */
+export function cleanStaleLocks(dir: string): void {
+  if (!existsSync(dir)) {
+    return;
+  }
+  for (const entry of readdirSync(dir)) {
+    const pid = parseInt(entry.replace(/\.lock$/, ""), 10);
+    if (!Number.isNaN(pid) && !isProcessAlive(pid)) {
+      rmSync(join(dir, entry), { force: true });
+    }
+  }
+}
+
+/**
+ * Run the searxng management script (up/down).
+ * Uses the provided scriptPath, or falls back to the built-in `bin/searxng`.
+ *
+ * Waits for the child process to complete and captures stdout/stderr.
+ * Use this when you need the exit code and output (e.g., for the `up` command).
+ */
+export async function runScript(
+  command: "up" | "down",
+  scriptPath?: string,
+): Promise<void>;
+
+/**
+ * Run the searxng management script in detached mode.
+ *
+ * The child process is detached from the parent and will survive parent exit.
+ * No output is captured and no exit code is available. Use this for
+ * fire-and-forget commands (e.g., `docker compose down` during shutdown).
+ *
+ * @param opts.shutdownPidDir When set, the command is wrapped in a bash script
+ *   that creates a `shutdown-<pid>.pid` file before running the command and
+ *   removes it on exit. Enables cross-session health checks via
+ *   {@link inspectShutdownState}.
+ */
+export function runScript(
+  command: "up" | "down",
+  scriptPath: string | undefined,
+  opts: { detached: true; shutdownPidDir?: string },
+): void;
+
+export function runScript(
+  command: "up" | "down",
+  scriptPath?: string,
+  opts?: { detached?: boolean; shutdownPidDir?: string },
+): Promise<void> | void {
+  const script = scriptPath ? expandTilde(scriptPath) : getScriptPath();
+
+  // Detached mode: fire-and-forget, child survives parent exit
+  if (opts?.detached) {
+    if (opts.shutdownPidDir) {
+      // Bash wrapper that tracks the down command via a PID file.
+      // The wrapper creates shutdown-<pid>.pid, runs the script, then
+      // removes the file. If the file remains on next startup, the
+      // shutdown was unclean.
+      const child = spawn(
+        "bash",
+        [
+          "-c",
+          `
+          PID_FILE="${opts.shutdownPidDir}/shutdown-$$.pid"
+          echo $$ > "$PID_FILE"
+          "${script}" ${command}
+          EXIT=$?
+          rm -f "$PID_FILE"
+          exit $EXIT
+          `,
+        ],
+        {
+          stdio: "ignore",
+          detached: true,
+        },
+      );
+      child.unref();
+      child.on("error", (err) => {
+        console.error(
+          `pi-web: failed to run searxng ${command}: ${err.message}`,
+        );
+      });
+    } else {
+      const child = spawn("bash", [script, command], {
+        stdio: "ignore",
+        detached: true,
+      });
+      child.unref();
+      child.on("error", (err) => {
+        console.error(
+          `pi-web: failed to run searxng ${command}: ${err.message}`,
+        );
+      });
+    }
+    return;
+  }
+
+  // Default mode: wait for completion, capture output
+  return new Promise((resolve, reject) => {
+    const child = spawn("bash", [script, command], {
+      stdio: "pipe",
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout?.on("data", (d) => {
+      stdout += d.toString();
+    });
+    child.stderr?.on("data", (d) => {
+      stderr += d.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        if (stdout.trim()) {
+          console.log(stdout.trim());
+        }
+        resolve();
+      } else {
+        reject(
+          new Error(
+            `searxng ${command} failed (exit ${code}): ${stderr || stdout}`,
+          ),
+        );
+      }
+    });
+
+    child.on("error", reject);
+  });
+}
+
+/**
+ * Check for leftover shutdown PID files from previous sessions.
+ *
+ * Returns counts of unclean and still-running shutdowns, plus a
+ * `cleanup()` method that removes the inspected PID files. Call
+ * `cleanup()` after reporting to prevent false positives on the
+ * next startup.
+ */
+export function inspectShutdownState(dir: string): ShutdownState {
+  const pids: string[] = [];
+  let uncleanCount = 0;
+  let stillRunning = 0;
+
+  if (existsSync(dir)) {
+    for (const entry of readdirSync(dir)) {
+      const match = entry.match(/^shutdown-(\d+)\.pid$/);
+      if (!match) {
+        continue;
+      }
+
+      const pidStr = match[1];
+      if (!pidStr) {
+        continue;
+      }
+
+      pids.push(entry);
+      const pid = parseInt(pidStr, 10);
+      if (isProcessAlive(pid)) {
+        stillRunning++;
+      } else {
+        uncleanCount++;
+      }
+    }
+  }
+
+  return {
+    uncleanCount,
+    stillRunning,
+    cleanup() {
+      for (const entry of pids) {
+        rmSync(join(dir, entry), { force: true });
+      }
+    },
+  };
+}
+
+/**
+ * Register the current pi instance as a searxng user.
+ *
+ * Creates a PID-based lock file in the instances directory, cleans up stale
+ * locks, and starts SearXNG (if it's not already running). Safe to call
+ * multiple times — it is idempotent.
+ *
+ * @param scriptPath Optional path to a custom management script.
+ *   Must accept "up" and "down" commands. When set, used instead of the
+ *   built-in `bin/searxng` script.
+ */
+export async function registerInstance(scriptPath?: string): Promise<void> {
+  const dir = getInstancesDir();
+  mkdirSync(dir, { recursive: true });
+
+  // Remove locks belonging to dead processes
+  cleanStaleLocks(dir);
+
+  // Create / overwrite our lock file
+  const lockFile = join(dir, `${process.pid}.lock`);
+  writeFileSync(lockFile, String(process.pid));
+
+  // Start SearXNG (idempotent — the script checks if already running)
+  try {
+    await runScript("up", scriptPath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`pi-web: failed to start SearXNG: ${message}`);
+  }
+}
+
+/**
+ * Unregister the current pi instance.
+ *
+ * Removes our PID lock file. If no live instances remain, stops SearXNG.
+ *
+ * @param scriptPath Optional path to a custom management script.
+ *   Must match the path passed to registerInstance.
+ */
+export async function unregisterInstance(scriptPath?: string): Promise<void> {
+  const dir = getInstancesDir();
+
+  // Remove our lock file
+  const lockFile = join(dir, `${process.pid}.lock`);
+  try {
+    rmSync(lockFile, { force: true });
+  } catch {
+    // Ignore — best effort cleanup
+  }
+
+  // Check if any live instances remain
+  if (existsSync(dir)) {
+    for (const entry of readdirSync(dir)) {
+      const pid = parseInt(entry.replace(/\.lock$/, ""), 10);
+      if (!Number.isNaN(pid) && isProcessAlive(pid)) {
+        return; // Another instance is still running
+      }
+    }
+  }
+
+  // No more live instances — shut down SearXNG.
+  // Use detached mode with PID tracking so unclean shutdowns are detected
+  // on the next startup via inspectShutdownState().
+  runScript("down", scriptPath, { detached: true, shutdownPidDir: dir });
+}

package/src/lib/types.ts

@@ -0,0 +1,78 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { Static } from "typebox";
+import Type from "typebox";
+
+// ── webfetch types ──────────────────────────────────────────────────────
+
+export const FormatSchema = StringEnum(["text", "markdown", "html"] as const, {
+  description:
+    "The format to return the content in - text, markdown, or html (default: 'markdown')",
+});
+export type Format = Static<typeof FormatSchema>;
+
+export type Header = Record<
+  "User-Agent" | "Accept" | "Accept-Language",
+  string
+>;
+
+// ── websearch types ─────────────────────────────────────────────────────
+
+/**
+ * A search provider implementation.
+ *
+ * Each provider encapsulates the logic for calling a specific search backend
+ * (MCP server, REST API, etc.) and returns the search results as a text string.
+ */
+export interface SearchProvider {
+  /** Human-readable provider name (e.g. "exa-mcp", "brave", "tavily"). */
+  readonly name: string;
+
+  /** Usage notes shown in the tool description for the LLM. */
+  readonly usageNotes: string;
+
+  /**
+   * Execute a search and return the result text.
+   * Returns undefined if the search returned no results.
+   */
+  search(args: SearchArgs, signal?: AbortSignal): Promise<string | undefined>;
+}
+
+export const WebsearchParameters = Type.Object({
+  query: Type.String({ description: "Web search query" }),
+  numResults: Type.Optional(
+    Type.Number({
+      description: "Number of search results to return (default: 8)",
+    }),
+  ),
+  livecrawl: Type.Optional(
+    StringEnum(["fallback", "preferred"] as const, {
+      description:
+        "Live crawl mode - 'fallback': use live crawling as backup if cached content unavailable, 'preferred': prioritize live crawling (default: 'fallback')",
+    }),
+  ),
+  type: Type.Optional(
+    StringEnum(["auto", "fast", "deep"] as const, {
+      description:
+        "Search type - 'auto': balanced search, 'fast': quick results, 'deep': comprehensive search (default: 'auto')",
+    }),
+  ),
+  contextMaxCharacters: Type.Optional(
+    Type.Number({
+      description:
+        "Maximum characters for context string optimized for LLMs (default: 10000)",
+    }),
+  ),
+});
+
+export type SearchArgs = Static<typeof WebsearchParameters>;
+
+export const McpResultPayload = Type.Object({
+  result: Type.Object({
+    content: Type.Array(
+      Type.Object({
+        type: Type.String(),
+        text: Type.String(),
+      }),
+    ),
+  }),
+});