@rahularya01/pi-essentials 0.1.0

package/src/config.ts

@@ -0,0 +1,351 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DEFAULT_MCP_IDLE_TIMEOUT_MS,
+  DEFAULT_MCP_REQUEST_TIMEOUT_MS,
+  DEFAULT_SEARCH_RESULTS,
+  DEFAULT_SUBAGENT_CONCURRENCY,
+  DEFAULT_SUBAGENT_OUTPUT_BYTES,
+  DEFAULT_SUBAGENT_SPAWN_BUDGET,
+  DEFAULT_WEB_MAX_BYTES,
+  DEFAULT_WEB_MAX_CHARS,
+  DEFAULT_WEB_TIMEOUT_MS,
+  MAX_PARALLEL_SUBAGENTS,
+} from "./security/limits.ts";
+import { getProjectConfigPath, getUserConfigPath } from "./paths.ts";
+import { normalizeAllowedHost } from "./security/ssrf.ts";
+
+export type FeatureToggle = boolean | { enabled?: boolean };
+
+export type SearchProviderName = "auto" | "duckduckgo" | "brave" | "tavily" | "exa" | "jina" | "searxng";
+
+export interface McpFeatureConfig {
+  enabled?: boolean;
+  requestTimeoutMs?: number;
+  idleTimeoutMs?: number;
+}
+
+export interface WebSearchConfig {
+  provider?: SearchProviderName;
+  braveApiKey?: string;
+  tavilyApiKey?: string;
+  exaApiKey?: string;
+  jinaApiKey?: string;
+  searxngUrl?: string;
+  timeoutMs?: number;
+  maxResults?: number;
+}
+
+export interface WebFetchConfig {
+  timeoutMs?: number;
+  maxBytes?: number;
+  maxChars?: number;
+  jinaFallback?: boolean;
+}
+
+export interface WebFeatureConfig {
+  enabled?: boolean;
+  search?: WebSearchConfig;
+  fetch?: WebFetchConfig;
+  /**
+   * Private hosts the user deliberately trusts, as `host` or `host:port`.
+   * Needed for self-hosted services such as a local SearXNG instance, which the
+   * private-address guard would otherwise block.
+   */
+  allowedHosts?: string[];
+}
+
+export interface SubagentsFeatureConfig {
+  enabled?: boolean;
+  maxConcurrency?: number;
+  maxParallel?: number;
+  maxOutputBytes?: number;
+  spawnBudget?: number;
+  allowNested?: boolean;
+  /** Let the fleet/inspector open a running child in an external Herdr pane, if `herdr` is on PATH. */
+  herdr?: boolean;
+}
+
+export interface PiEssentialsFile {
+  mcp?: boolean | McpFeatureConfig;
+  web?: boolean | WebFeatureConfig;
+  subagents?: boolean | SubagentsFeatureConfig;
+  todos?: boolean | { enabled?: boolean };
+  questions?: boolean | { enabled?: boolean };
+}
+
+export interface ResolvedMcpConfig {
+  enabled: boolean;
+  requestTimeoutMs: number;
+  idleTimeoutMs: number;
+}
+
+export interface ResolvedWebConfig {
+  enabled: boolean;
+  allowedHosts: ReadonlySet<string>;
+  search: {
+    provider: SearchProviderName;
+    braveApiKey?: string;
+    tavilyApiKey?: string;
+    exaApiKey?: string;
+    jinaApiKey?: string;
+    searxngUrl?: string;
+    timeoutMs: number;
+    maxResults: number;
+  };
+  fetch: {
+    timeoutMs: number;
+    maxBytes: number;
+    maxChars: number;
+    jinaFallback: boolean;
+  };
+}
+
+export interface ResolvedSubagentsConfig {
+  enabled: boolean;
+  maxConcurrency: number;
+  maxParallel: number;
+  maxOutputBytes: number;
+  spawnBudget: number;
+  allowNested: boolean;
+  herdr: boolean;
+}
+
+export interface ResolvedConfig {
+  mcp: ResolvedMcpConfig;
+  web: ResolvedWebConfig;
+  subagents: ResolvedSubagentsConfig;
+  todos: { enabled: boolean };
+  questions: { enabled: boolean };
+  warnings: string[];
+}
+
+const DEFAULTS: PiEssentialsFile = {
+  mcp: true,
+  web: true,
+  subagents: true,
+  todos: true,
+  questions: true,
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function enabledFrom(flag: unknown, fallback: boolean): boolean {
+  if (typeof flag === "boolean") return flag;
+  if (isObject(flag) && typeof flag.enabled === "boolean") return flag.enabled;
+  return fallback;
+}
+
+function positiveInt(value: unknown, fallback: number, min = 1, max = Number.MAX_SAFE_INTEGER): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  const n = Math.floor(value);
+  if (n < min) return min;
+  if (n > max) return max;
+  return n;
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function readJsonFile(filePath: string, warnings: string[]): unknown {
+  if (!fs.existsSync(filePath)) return undefined;
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw) as unknown;
+  } catch {
+    warnings.push(`Ignoring malformed config at ${filePath}; using defaults for that file.`);
+    return undefined;
+  }
+}
+
+function asFile(value: unknown, filePath: string, warnings: string[]): PiEssentialsFile {
+  if (value === undefined) return {};
+  if (!isObject(value)) {
+    warnings.push(`Ignoring ${filePath}: expected a JSON object at the top level.`);
+    return {};
+  }
+  const known = new Set<string>(FEATURE_KEYS);
+  for (const key of Object.keys(value)) {
+    if (!known.has(key)) {
+      warnings.push(`Unknown option "${key}" in ${filePath}; expected one of ${[...known].join(", ")}.`);
+    }
+  }
+  return value as PiEssentialsFile;
+}
+
+const FEATURE_KEYS = ["mcp", "web", "subagents", "todos", "questions"] as const;
+
+/** Layer one config file over another; later files win, objects merge key by key. */
+export function mergeFiles(base: PiEssentialsFile, overlay: PiEssentialsFile): PiEssentialsFile {
+  const merged: PiEssentialsFile = { ...base };
+  for (const key of FEATURE_KEYS) {
+    const next = overlay[key];
+    if (next === undefined) continue;
+    (merged as Record<string, unknown>)[key] = mergeMaybeObject(base[key], next);
+  }
+  return merged;
+}
+
+function mergeMaybeObject<T>(base: boolean | T | undefined, overlay: boolean | T): boolean | T {
+  if (typeof overlay === "boolean" || typeof base === "boolean" || base === undefined) return overlay;
+  if (isObject(base) && isObject(overlay)) return deepMerge(base, overlay) as T;
+  return overlay;
+}
+
+function deepMerge(base: Record<string, unknown>, overlay: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    const existing = out[key];
+    out[key] = isObject(existing) && isObject(value) ? deepMerge(existing, value) : value;
+  }
+  return out;
+}
+
+function envOr(configValue: string | undefined, envName: string): string | undefined {
+  return configValue || optionalString(process.env[envName]);
+}
+
+/**
+ * Build the private-host allowlist. A configured SearXNG instance is trusted
+ * implicitly: pointing `searxngUrl` at localhost is the normal way to run one,
+ * and silently blocking it would make the setting useless.
+ */
+function resolveAllowedHosts(
+  configured: unknown,
+  searxngUrl: string | undefined,
+  warnings: string[],
+): ReadonlySet<string> {
+  const hosts = new Set<string>();
+  const add = (entry: string, source: string) => {
+    const normalized = normalizeAllowedHost(entry);
+    if (normalized) hosts.add(normalized);
+    else warnings.push(`Ignoring unparseable ${source} entry "${entry}".`);
+  };
+
+  if (configured !== undefined) {
+    if (Array.isArray(configured)) {
+      for (const entry of configured) {
+        if (typeof entry === "string") add(entry, "web.allowedHosts");
+        else warnings.push("web.allowedHosts entries must be strings.");
+      }
+    } else {
+      warnings.push("web.allowedHosts must be an array of host or host:port strings.");
+    }
+  }
+  if (searxngUrl) add(searxngUrl, "web.search.searxngUrl");
+  return hosts;
+}
+
+export function resolveConfig(file: PiEssentialsFile, warnings: string[] = []): ResolvedConfig {
+  const mcpIn = file.mcp ?? true;
+  const webIn = file.web ?? true;
+  const subIn = file.subagents ?? true;
+  const mcpObj = isObject(mcpIn) ? mcpIn : {};
+  const webObj = isObject(webIn) ? webIn : {};
+  const subObj = isObject(subIn) ? subIn : {};
+  const search = isObject(webObj.search) ? webObj.search : {};
+  const fetch = isObject(webObj.fetch) ? webObj.fetch : {};
+
+  const searxngUrl = optionalString(search.searxngUrl) ?? optionalString(process.env.SEARXNG_URL);
+  const providerRaw = optionalString(search.provider) ?? "auto";
+  const providers: SearchProviderName[] = ["auto", "duckduckgo", "brave", "tavily", "exa", "jina", "searxng"];
+  const provider = (providers.includes(providerRaw as SearchProviderName) ? providerRaw : "auto") as SearchProviderName;
+  if (providerRaw !== provider) {
+    warnings.push(`Unknown search provider "${providerRaw}"; using auto.`);
+  }
+
+  return {
+    mcp: {
+      enabled: enabledFrom(mcpIn, true),
+      requestTimeoutMs: positiveInt(mcpObj.requestTimeoutMs, DEFAULT_MCP_REQUEST_TIMEOUT_MS, 1000, 300_000),
+      idleTimeoutMs: positiveInt(mcpObj.idleTimeoutMs, DEFAULT_MCP_IDLE_TIMEOUT_MS, 1000, 24 * 60 * 60_000),
+    },
+    web: {
+      enabled: enabledFrom(webIn, true),
+      allowedHosts: resolveAllowedHosts(webObj.allowedHosts, searxngUrl, warnings),
+      search: {
+        provider,
+        braveApiKey: envOr(optionalString(search.braveApiKey), "BRAVE_API_KEY"),
+        tavilyApiKey: envOr(optionalString(search.tavilyApiKey), "TAVILY_API_KEY"),
+        exaApiKey: envOr(optionalString(search.exaApiKey), "EXA_API_KEY"),
+        jinaApiKey: envOr(optionalString(search.jinaApiKey), "JINA_API_KEY"),
+        searxngUrl,
+        timeoutMs: positiveInt(search.timeoutMs, DEFAULT_WEB_TIMEOUT_MS, 1000, 60_000),
+        maxResults: positiveInt(search.maxResults, DEFAULT_SEARCH_RESULTS, 1, 20),
+      },
+      fetch: {
+        timeoutMs: positiveInt(fetch.timeoutMs, DEFAULT_WEB_TIMEOUT_MS, 1000, 60_000),
+        maxBytes: positiveInt(fetch.maxBytes, DEFAULT_WEB_MAX_BYTES, 16_384, 8 * 1024 * 1024),
+        maxChars: positiveInt(fetch.maxChars, DEFAULT_WEB_MAX_CHARS, 1000, 200_000),
+        jinaFallback: fetch.jinaFallback !== false,
+      },
+    },
+    subagents: {
+      enabled: enabledFrom(subIn, true),
+      maxConcurrency: positiveInt(subObj.maxConcurrency, DEFAULT_SUBAGENT_CONCURRENCY, 1, MAX_PARALLEL_SUBAGENTS),
+      maxParallel: positiveInt(subObj.maxParallel, MAX_PARALLEL_SUBAGENTS, 1, MAX_PARALLEL_SUBAGENTS),
+      maxOutputBytes: positiveInt(subObj.maxOutputBytes, DEFAULT_SUBAGENT_OUTPUT_BYTES, 1024, 1024 * 1024),
+      spawnBudget: positiveInt(subObj.spawnBudget, DEFAULT_SUBAGENT_SPAWN_BUDGET, 1, 64),
+      allowNested: subObj.allowNested === true,
+      herdr: subObj.herdr !== false,
+    },
+    todos: { enabled: enabledFrom(file.todos ?? true, true) },
+    questions: { enabled: enabledFrom(file.questions ?? true, true) },
+    warnings,
+  };
+}
+
+export function loadConfig(cwd: string = process.cwd()): ResolvedConfig {
+  const warnings: string[] = [];
+  const userRaw = readJsonFile(getUserConfigPath(), warnings);
+  const projectRaw = readJsonFile(getProjectConfigPath(cwd), warnings);
+  const merged = mergeFiles(
+    mergeFiles(DEFAULTS, asFile(userRaw, getUserConfigPath(), warnings)),
+    asFile(projectRaw, getProjectConfigPath(cwd), warnings),
+  );
+  return resolveConfig(merged, warnings);
+}
+
+export function warnConfig(warnings: string[], notify?: (message: string) => void): void {
+  for (const warning of warnings) {
+    if (notify) notify(warning);
+    else console.warn(`[pi-essentials] ${warning}`);
+  }
+}
+
+export function ensureDir(dir: string, mode = 0o700): void {
+  fs.mkdirSync(dir, { recursive: true, mode });
+  try {
+    fs.chmodSync(dir, mode);
+  } catch {
+    // Best-effort on platforms that ignore chmod.
+  }
+}
+
+let tmpCounter = 0;
+
+export function writePrivateFile(filePath: string, contents: string): void {
+  ensureDir(path.dirname(filePath));
+  const tmp = `${filePath}.${process.pid}.${tmpCounter++}.tmp`;
+  try {
+    fs.writeFileSync(tmp, contents, { encoding: "utf8", mode: 0o600 });
+    fs.renameSync(tmp, filePath);
+  } catch (error) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      // Best-effort cleanup of the partial temp file.
+    }
+    throw error;
+  }
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch {
+    // Best-effort.
+  }
+}

package/src/errors.ts

@@ -0,0 +1,96 @@
+import type { Usage } from "@earendil-works/pi-ai";
+
+export class PiEssentialsError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+
+  constructor(message: string, code = "PI_ESSENTIALS_ERROR", retryable = false) {
+    super(message);
+    this.name = "PiEssentialsError";
+    this.code = code;
+    this.retryable = retryable;
+  }
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * Abort/timeout detection. Deliberately narrow: a remote "504 Gateway Timeout"
+ * body must not look like a local cancellation, or callers skip their fallbacks.
+ */
+export function isAbortError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const name = "name" in error ? String((error as { name?: unknown }).name) : "";
+  if (name === "AbortError" || name === "TimeoutError") return true;
+  if ((error as { code?: unknown }).code === "ABORT_ERR") return true;
+  const message = errorMessage(error).toLowerCase();
+  if (/^http \d{3}\b/.test(message)) return false;
+  return (
+    message.includes("the operation was aborted") ||
+    message.includes("was cancelled or timed out") ||
+    message.includes("this operation was aborted") ||
+    message.includes("request aborted")
+  );
+}
+
+export function toolText(text: string, details: object = {}, usage?: Usage) {
+  return {
+    content: [{ type: "text" as const, text }],
+    details,
+    ...(usage ? { usage } : {}),
+  };
+}
+
+/**
+ * Fail a tool call.
+ *
+ * Pi only marks a tool result `isError: true` when `execute` throws, so every
+ * genuine failure — bad arguments included — must raise rather than return
+ * prose that merely starts with "Error:".
+ */
+export function toolFailure(message: string, code = "PI_ESSENTIALS_ERROR"): never {
+  throw new PiEssentialsError(message, code);
+}
+
+/** Truncate to a UTF-8 byte budget without splitting a multi-byte character. */
+export function capBytes(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  const limit = Math.max(16, Math.floor(maxBytes));
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.byteLength <= limit) return { text, truncated: false };
+
+  // Reserve room for the marker itself, then walk back off any continuation
+  // byte (0b10xxxxxx) so the cut lands on a character boundary.
+  let end = limit;
+  let marker = "";
+  for (let attempt = 0; attempt < 10; attempt++) {
+    marker = `\n\n[Truncated: ${buffer.byteLength - end} of ${buffer.byteLength} bytes omitted.]`;
+    let next = Math.max(0, limit - Buffer.byteLength(marker, "utf8"));
+    while (next > 0 && (buffer[next] & 0xc0) === 0x80) next -= 1;
+    if (next === end) break;
+    end = next;
+  }
+  marker = `\n\n[Truncated: ${buffer.byteLength - end} of ${buffer.byteLength} bytes omitted.]`;
+  if (Buffer.byteLength(marker, "utf8") > limit) {
+    marker = "\n\n[Truncated]".slice(0, limit);
+    end = 0;
+  }
+  return { text: `${buffer.subarray(0, end).toString("utf8")}${marker}`, truncated: true };
+}
+
+export function capText(text: string, maxChars: number): { text: string; truncated: boolean } {
+  const limit = Math.max(1, Math.floor(maxChars));
+  if (text.length <= limit) return { text, truncated: false };
+  const omitted = text.length - limit;
+  return {
+    text: `${text.slice(0, limit)}\n\n[Truncated: ${omitted} characters omitted. Request another slice if you need more.]`,
+    truncated: true,
+  };
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig, warnConfig } from "./config.ts";
+import { registerMcp } from "./mcp/index.ts";
+import { registerQuestions } from "./questions/index.ts";
+import { registerSubagents } from "./subagents/index.ts";
+import { registerTodos } from "./todos/index.ts";
+import { registerWeb } from "./web/index.ts";
+
+export type { PiEssentialsFile, ResolvedConfig } from "./config.ts";
+export { loadConfig, resolveConfig } from "./config.ts";
+
+/** Depth beyond which a subagent may no longer spawn further subagents. */
+export const MAX_NEST_DEPTH = 2;
+
+export function readNestDepth(env: NodeJS.ProcessEnv = process.env): number {
+  const parsed = Number.parseInt(env.PI_ESSENTIALS_NEST_DEPTH ?? "0", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export default function piEssentials(pi: ExtensionAPI): void {
+  const config = loadConfig(process.cwd());
+
+  const nested = process.env.PI_ESSENTIALS_SUBAGENT === "1";
+  const nestDepth = readNestDepth();
+
+  // Surface config problems through the UI once a session exists; writing to the
+  // console during extension load corrupts TUI rendering.
+  let warned = false;
+  pi.on("session_start", async (_event, ctx) => {
+    if (warned || config.warnings.length === 0) return;
+    warned = true;
+    if (ctx.hasUI) warnConfig(config.warnings, (message) => ctx.ui.notify(`pi-essentials: ${message}`, "warning"));
+    else warnConfig(config.warnings);
+  });
+
+  if (config.mcp.enabled && !nested) registerMcp(pi, config);
+  if (config.web.enabled) registerWeb(pi, config);
+  if (config.subagents.enabled && (!nested || (config.subagents.allowNested && nestDepth < MAX_NEST_DEPTH))) {
+    registerSubagents(pi, config);
+  }
+  if (config.todos.enabled && !nested) registerTodos(pi);
+  if (config.questions.enabled && !nested) registerQuestions(pi);
+}