moonpi 0.4.3 → 0.4.5

package/README.md

@@ -54,7 +54,7 @@ npm install -g @mariozechner/pi-coding-agent
 Then, install the `moonpi` extension set directly via `pi`:
 
 ```bash
-pi install git:github.com/galatolofederico/moonpi@v0.4.1
+pi install npm:moonpi
 ```
 
 
@@ -182,7 +182,177 @@ Example output:
 
 At startup, a notification shows which files are currently selected for injection.
 
-### Configuration
+### `/context:clear`
+
+Deselects all currently active context files (both `/pick`-selected and auto-discovered). After clearing, no files are injected into the prompt until you run `/pick` again.
+
+Example output:
+
+```
+Cleared context file selection (3 file(s) deselected). Use /pick to select files.
+```
+
+## Custom Providers
+
+moonpi includes the support from some custom providers, and provides slash commands to manage custom providers in `~/.pi/agent/models.json`.
+
+
+### Synthetic Provider
+
+Moonpi registers Synthetic as the `synthetic` provider using the OpenAI-compatible endpoint.
+
+Configure credentials with either:
+
+```bash
+export SYNTHETIC_API_KEY=...
+```
+
+or run:
+
+```text
+/login
+```
+
+Use `/model` to select a `synthetic` model. Use `/synthetic:quotas` to show your weekly token and rolling 5h usage quotas:
+
+![Synthetic quotas output](assets/screenshots/moonpi-syn.png)
+
+#### Web Search
+
+When authenticated with Synthetic, moonpi makes a `web_search` tool available to the agent. This tool uses the [Synthetic search API](https://docs.synthetic.new) to perform zero-data-retention web searches and return results with title, URL, published date, and text excerpt.
+
+The tool is **only visible to the LLM when logged in with Synthetic** — it is not registered at all when no API key is configured, so the model never sees it or knows it exists.
+
+To disable the search tool even when logged in, set `synthetic.search.enabled` to `false` in your config:
+
+```json
+{
+  "synthetic": {
+    "search": {
+      "enabled": false
+    }
+  }
+}
+```
+
+### Managing Custom Providers
+
+moonpi provides five slash commands to manage custom providers in `~/.pi/agent/models.json`:
+
+#### `/custom-provider:add-provider`
+
+Interactive wizard that adds a new custom provider. Prompts for:
+
+1. **Provider name** — a unique identifier (e.g. `my-vllm`)
+2. **API type** — select from all supported APIs (`openai-completions`, `anthropic-messages`, `google-generative-ai`, etc.)
+3. **Base URL** — the API endpoint (sensible defaults per API type)
+4. **API key** — your API key or an environment variable name
+
+Example `models.json` result:
+
+```json
+{
+  "providers": {
+    "my-vllm": {
+      "baseUrl": "http://127.0.0.1:8000/v1",
+      "api": "openai-completions",
+      "apiKey": "none",
+      "models": []
+    }
+  }
+}
+```
+
+#### `/custom-provider:add-model`
+
+Adds a model to an existing custom provider. Prompts for:
+
+1. **Provider** — select from existing custom providers
+2. **Model ID** — the model identifier (e.g. `Qwen/Qwen3-27B`)
+3. **Display name** — optional human-readable name
+4. **Advanced options** — optional configuration for reasoning, context window, max tokens, image input, and API type override
+
+#### `/custom-provider:scan-models`
+
+Auto-detects models from an OpenAI-compatible provider endpoint. Works with providers using `openai-completions` or `openai-responses` API.
+
+1. **Select provider** — choose from OpenAI-compatible custom providers
+2. **Scan** — fetches `/v1/models` from the provider's base URL
+3. **Select models** — checkbox UI shows all discovered models; already-added models are greyed out
+   - `Space` to toggle individual models
+   - `a`/`A` to select/deselect all
+   - `Enter` to confirm (adds all new models if none selected)
+4. Auto-fills `contextWindow` from `max_model_len` when available
+
+#### `/custom-provider:remove-provider`
+
+Removes a custom provider and all its models from `models.json`. Asks for confirmation before deleting.
+
+#### `/custom-provider:remove-model`
+
+Removes a single model from a custom provider. Prompts for the provider, then the model to remove, with confirmation.
+
+After any change, run `/reload` to refresh pi's model registry and make new models available in `/model`.
+
+## Moonpi loop
+
+moonpi includes sprint-oriented loop for larger projects.
+
+### `/sprint:init`
+
+Creates a new sprint for a larger project.
+
+This command asks **one question**: the sprint objective.
+
+It then delegates SPRINT.md and TASKS.md creation to the agent, which writes:
+
+```txt
+./sprints/<sprint_number>/SPRINT.md
+./sprints/<sprint_number>/TASKS.md
+```
+
+The sprint is divided into phases.
+
+Each phase includes tasks and verification steps that define when the phase is complete.
+
+The goal is to turn a vague big project into a concrete, phased execution plan.
+
+### `/sprint:loop`
+
+Runs the latest sprint phase-by-phase. Automatically picks the most recent sprint.
+
+The loop works like this:
+
+1. complete one phase
+2. mark completed tasks in:
+
+```txt
+./sprints/<sprint_number>/TASKS.md
+```
+
+3. compact the conversation/context
+4. proceed to the next phase
+5. repeat until the sprint is complete
+
+The model signals the end of a phase by calling a special `end_phase` tool.
+
+This keeps long-running projects simple, resumable, and grounded in actual files.
+
+### Does it work?
+
+Watch a drastically sped-up video of `Qwen/Qwen3.6-27B` working unattended for over an hour on this sprint prompt:
+
+```text
+create WebOS a fully functional web-based operating system with apps, games and everything
+```
+
+https://github.com/user-attachments/assets/92670a55-a3c4-4c31-a4a2-0afc449f0137
+
+
+And judge the result yourself [here](https://qwen36-27b-moonpi-webos.netlify.app/).
+
+
+## Configuration
 
 Configure `.pi/moonpi.json` (project) or `~/.pi/agent/moonpi.json` (global):
 
@@ -191,6 +361,11 @@ Configure `.pi/moonpi.json` (project) or `~/.pi/agent/moonpi.json` (global):
   "defaultMode": "auto",
   "preserveExternalTools": false,
   "customEditor": true,
+  "synthetic": {
+    "search": {
+      "enabled": true
+    }
+  },
   "contextFiles": {
     "enabled": true,
     "fileNames": ["README.md", "SPECS.md", "SPRINT.md"],
@@ -230,6 +405,12 @@ Configure `.pi/moonpi.json` (project) or `~/.pi/agent/moonpi.json` (global):
 | `preserveExternalTools` | `false` | When `true`, tools registered by other extensions are kept alongside moonpi tools when applying mode tool restrictions |
 | `customEditor` | `true` | When `false`, moonpi skips installing its mode-colored editor, preserving editor customizations from other extensions |
 
+#### Synthetic
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `synthetic.search.enabled` | `true` | When `false`, the `web_search` tool is not registered even if logged in with Synthetic |
+
 #### Keybindings
 
 | Field | Default | Description |
@@ -316,89 +497,6 @@ If the model tries to write to a file without reading it first, the write tool r
 
 This prevents careless overwrites and forces the agent to inspect the current state of a file before modifying it.
 
-## Moonpi loop
-
-moonpi includes sprint-oriented loop for larger projects.
-
-### `/sprint:init`
-
-Creates a new sprint for a larger project.
-
-This command asks **one question**: the sprint objective.
-
-It then delegates SPRINT.md and TASKS.md creation to the agent, which writes:
-
-```txt
-./sprints/<sprint_number>/SPRINT.md
-./sprints/<sprint_number>/TASKS.md
-```
-
-The sprint is divided into phases.
-
-Each phase includes tasks and verification steps that define when the phase is complete.
-
-The goal is to turn a vague big project into a concrete, phased execution plan.
-
-### `/sprint:loop`
-
-Runs the latest sprint phase-by-phase. Automatically picks the most recent sprint.
-
-The loop works like this:
-
-1. complete one phase
-2. mark completed tasks in:
-
-```txt
-./sprints/<sprint_number>/TASKS.md
-```
-
-3. compact the conversation/context
-4. proceed to the next phase
-5. repeat until the sprint is complete
-
-The model signals the end of a phase by calling a special `end_phase` tool.
-
-This keeps long-running projects simple, resumable, and grounded in actual files.
-
-### Does it work?
-
-Watch a drastically sped-up video of `Qwen/Qwen3.6-27B` working unattended for over an hour on this sprint prompt:
-
-```text
-create WebOS a fully functional web-based operating system with apps, games and everything
-```
-
-https://github.com/user-attachments/assets/92670a55-a3c4-4c31-a4a2-0afc449f0137
-
-
-And judge the result yourself [here](https://qwen36-27b-moonpi-webos.netlify.app/).
-
-## Custom Providers
-
-moonpi includes the support from some custom providers.
-
-
-### Synthetic Provider
-
-Moonpi registers Synthetic as the `synthetic` provider using the OpenAI-compatible endpoint.
-
-Configure credentials with either:
-
-```bash
-export SYNTHETIC_API_KEY=...
-```
-
-or run:
-
-```text
-/login
-```
-
-Use `/model` to select a `synthetic` model. Use `/synthetic:quotas` to show your weekly token and rolling 5h usage quotas:
-
-![Synthetic quotas output](assets/screenshots/moonpi-syn.png)
-
-
 ## Why moonpi?
 
 moonpi is not trying to be a giant agent framework.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moonpi",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Opinionated set of extensions for pi",
   "type": "module",
   "main": "./src/index.ts",

package/src/config.ts

@@ -42,6 +42,11 @@ export const DEFAULT_CONFIG: MoonpiConfig = {
   defaultMode: "auto",
   preserveExternalTools: true,
   customEditor: true,
+  synthetic: {
+    search: {
+      enabled: true,
+    },
+  },
   contextFiles: {
     enabled: true,
     fileNames: ["README.md", "SPECS.md", "SPRINT.md"],
@@ -125,6 +130,7 @@ function mergeConfig(base: MoonpiConfig, raw: Record<string, unknown> | undefine
     defaultMode: base.defaultMode,
     preserveExternalTools: base.preserveExternalTools,
     customEditor: base.customEditor,
+    synthetic: { ...base.synthetic },
     contextFiles: { ...base.contextFiles },
     guards: { ...base.guards },
     keybindings: { ...base.keybindings },
@@ -134,6 +140,14 @@ function mergeConfig(base: MoonpiConfig, raw: Record<string, unknown> | undefine
   if (typeof raw.preserveExternalTools === "boolean") next.preserveExternalTools = raw.preserveExternalTools;
   if (typeof raw.customEditor === "boolean") next.customEditor = raw.customEditor;
 
+  if (isRecord(raw.synthetic)) {
+    if (isRecord(raw.synthetic.search)) {
+      if (typeof raw.synthetic.search.enabled === "boolean") {
+        next.synthetic.search.enabled = raw.synthetic.search.enabled;
+      }
+    }
+  }
+
   if (isRecord(raw.contextFiles)) {
     const context = raw.contextFiles;
     if (typeof context.enabled === "boolean") next.contextFiles.enabled = context.enabled;

package/src/context-files.ts

@@ -484,6 +484,21 @@ export function installContextFiles(pi: ExtensionAPI, controller: MoonpiControll
     },
   });
 
+  pi.registerCommand("context:clear", {
+    description: "Deselect all context files (clear /pick and auto-discovered files)",
+    handler: async (_args, ctx) => {
+      if (!controller.config.contextFiles.enabled) {
+        ctx.ui.notify("moonpi context file injection is disabled in /moonpi:settings.", "warning");
+        return;
+      }
+
+      const previousCount = getEffectiveSelectedContextFilePaths(ctx.cwd, controller).length;
+      controller.state.selectedContextFilePaths = [];
+      controller.persist();
+      ctx.ui.notify(`Cleared context file selection (${previousCount} file(s) deselected). Use /pick to select files.`, "info");
+    },
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     controller.restoreFromSession(ctx);
     const discovery = controller.state.selectedContextFilePaths === undefined ? findDefaultContextFilePaths(ctx.cwd, controller) : undefined;

package/src/custom-providers.ts

@@ -0,0 +1,673 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
+
+// =========================================================================
+// models.json helpers
+// =========================================================================
+
+/** The API types that custom providers can use. */
+const KNOWN_APIS = [
+  "openai-completions",
+  "openai-responses",
+  "anthropic-messages",
+  "google-generative-ai",
+  "google-vertex",
+  "mistral-conversations",
+  "bedrock-converse-stream",
+  "azure-openai-responses",
+  "openai-codex-responses",
+] as const;
+
+/** APIs that are OpenAI-compatible and support the /v1/models endpoint. */
+const OPENAI_COMPAT_APIS = new Set([
+  "openai-completions",
+  "openai-responses",
+]);
+
+interface ModelDefinition {
+  id: string;
+  name?: string;
+  api?: string;
+  baseUrl?: string;
+  reasoning?: boolean;
+  input?: string[];
+  cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  contextWindow?: number;
+  maxTokens?: number;
+  headers?: Record<string, string>;
+  compat?: Record<string, unknown>;
+}
+
+interface ProviderConfig {
+  name?: string;
+  baseUrl?: string;
+  apiKey?: string;
+  api?: string;
+  headers?: Record<string, string>;
+  compat?: Record<string, unknown>;
+  authHeader?: boolean;
+  models?: ModelDefinition[];
+  modelOverrides?: Record<string, unknown>;
+}
+
+interface ModelsConfig {
+  providers: Record<string, ProviderConfig>;
+}
+
+function getModelsJsonPath(): string {
+  return join(getAgentDir(), "models.json");
+}
+
+function readModelsJson(): ModelsConfig {
+  const filePath = getModelsJsonPath();
+  if (!existsSync(filePath)) {
+    return { providers: {} };
+  }
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    // Strip // line comments (same as pi's model-registry.ts)
+    const stripped = raw
+      .replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*/g, (m) => (m[0] === '"' ? m : ""))
+      .replace(/"(?:\\.|[^"\\])*"|,(\s*[}\]])/g, (m, tail) => tail ?? (m[0] === '"' ? m : ""));
+    return JSON.parse(stripped) as ModelsConfig;
+  } catch {
+    return { providers: {} };
+  }
+}
+
+function writeModelsJson(config: ModelsConfig): void {
+  const filePath = getModelsJsonPath();
+  const dir = join(filePath, "..");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+// =========================================================================
+// Command: /custom-provider:add-provider
+// =========================================================================
+
+async function addProviderCommand(_args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const config = readModelsJson();
+
+  // 1. Provider name
+  const providerName = await ctx.ui.input("Provider name (e.g. my-vllm)", "my-provider");
+  if (!providerName?.trim()) {
+    ctx.ui.notify("Cancelled: no provider name given.", "warning");
+    return;
+  }
+  const name = providerName.trim();
+
+  if (config.providers[name]) {
+    const overwrite = await ctx.ui.confirm(
+      `Provider "${name}" already exists. Overwrite?`,
+      `Existing provider has baseUrl: ${config.providers[name]!.baseUrl ?? "none"}, api: ${config.providers[name]!.api ?? "none"}`,
+    );
+    if (!overwrite) {
+      ctx.ui.notify("Cancelled.", "info");
+      return;
+    }
+  }
+
+  // 2. API type
+  const selectedApi = await ctx.ui.select("Select API type", [...KNOWN_APIS]);
+  if (!selectedApi) {
+    ctx.ui.notify("Cancelled: no API type selected.", "warning");
+    return;
+  }
+
+  // 3. Base URL
+  const defaultBaseUrl = selectedApi === "anthropic-messages"
+    ? "https://api.anthropic.com"
+    : selectedApi === "google-generative-ai"
+      ? "https://generativelanguage.googleapis.com"
+      : "";
+  const baseUrl = await ctx.ui.input("Base URL", defaultBaseUrl || "http://localhost:8000/v1");
+  if (!baseUrl?.trim()) {
+    ctx.ui.notify("Cancelled: no base URL given.", "warning");
+    return;
+  }
+
+  // 4. API key
+  const apiKey = await ctx.ui.input("API key (or env var name like MY_API_KEY)", "none");
+  if (!apiKey?.trim()) {
+    ctx.ui.notify("Cancelled: no API key given.", "warning");
+    return;
+  }
+
+  // Build the provider config
+  const providerConfig: ProviderConfig = {
+    baseUrl: baseUrl.trim(),
+    api: selectedApi,
+    apiKey: apiKey.trim(),
+    models: [],
+  };
+
+  config.providers[name] = providerConfig;
+  writeModelsJson(config);
+
+  ctx.ui.notify(
+    `Provider "${name}" added to models.json.\n` +
+    `  API: ${selectedApi}\n` +
+    `  Base URL: ${baseUrl.trim()}\n` +
+    `  API Key: ${apiKey.trim()}\n\n` +
+    `Use /custom-provider:add-model to add models, or /custom-provider:scan-models to auto-detect them.\n` +
+    `Run /reload to refresh pi's model registry.`,
+    "info",
+  );
+}
+
+// =========================================================================
+// Command: /custom-provider:add-model
+// =========================================================================
+
+async function addModelCommand(_args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const config = readModelsJson();
+  const providerNames = Object.keys(config.providers);
+
+  if (providerNames.length === 0) {
+    ctx.ui.notify(
+      "No custom providers found. Use /custom-provider:add-provider first.",
+      "warning",
+    );
+    return;
+  }
+
+  // 1. Select provider
+  const selectedProvider = await ctx.ui.select("Select provider to add model to", providerNames);
+  if (!selectedProvider) {
+    ctx.ui.notify("Cancelled: no provider selected.", "warning");
+    return;
+  }
+
+  const provider = config.providers[selectedProvider]!;
+
+  // 2. Model ID
+  const modelId = await ctx.ui.input("Model ID (e.g. Qwen/Qwen3-27B)", "");
+  if (!modelId?.trim()) {
+    ctx.ui.notify("Cancelled: no model ID given.", "warning");
+    return;
+  }
+
+  // Check for duplicates
+  const existingModels = provider.models ?? [];
+  if (existingModels.some((m) => m.id === modelId.trim())) {
+    ctx.ui.notify(`Model "${modelId.trim()}" already exists in provider "${selectedProvider}".`, "warning");
+    return;
+  }
+
+  // 3. Optional fields
+  const modelName = await ctx.ui.input("Model display name (optional, press Enter to skip)", modelId.trim());
+
+  const wantsAdvanced = await ctx.ui.confirm("Configure advanced options?", "Context window, max tokens, reasoning, input types");
+  const modelDef: ModelDefinition = {
+    id: modelId.trim(),
+    ...(modelName?.trim() && modelName.trim() !== modelId.trim() ? { name: modelName.trim() } : {}),
+  };
+
+  if (wantsAdvanced) {
+    // API override
+    const overrideApi = await ctx.ui.confirm("Override API type for this model?", `Provider default: ${provider.api ?? "unknown"}`);
+    if (overrideApi) {
+      const modelApi = await ctx.ui.select("Select model API type", [...KNOWN_APIS]);
+      if (modelApi) modelDef.api = modelApi;
+    }
+
+    // Reasoning
+    const reasoning = await ctx.ui.confirm("Does this model support reasoning/thinking?", "");
+    modelDef.reasoning = reasoning;
+
+    // Context window
+    const ctxWindow = await ctx.ui.input("Context window (tokens)", "128000");
+    if (ctxWindow?.trim()) {
+      const val = parseInt(ctxWindow.trim(), 10);
+      if (!Number.isNaN(val) && val > 0) modelDef.contextWindow = val;
+    }
+
+    // Max tokens
+    const maxTokens = await ctx.ui.input("Max output tokens", "16384");
+    if (maxTokens?.trim()) {
+      const val = parseInt(maxTokens.trim(), 10);
+      if (!Number.isNaN(val) && val > 0) modelDef.maxTokens = val;
+    }
+
+    // Input types
+    const hasImage = await ctx.ui.confirm("Supports image input?", "");
+    modelDef.input = hasImage ? ["text", "image"] : ["text"];
+  }
+
+  // Add model to provider
+  if (!provider.models) provider.models = [];
+  provider.models.push(modelDef);
+  writeModelsJson(config);
+
+  const summary = [
+    `Model "${modelDef.id}" added to provider "${selectedProvider}" in models.json.`,
+  ];
+  if (modelDef.name) summary.push(`  Display name: ${modelDef.name}`);
+  if (modelDef.reasoning !== undefined) summary.push(`  Reasoning: ${modelDef.reasoning}`);
+  if (modelDef.contextWindow) summary.push(`  Context window: ${modelDef.contextWindow}`);
+  if (modelDef.maxTokens) summary.push(`  Max tokens: ${modelDef.maxTokens}`);
+  summary.push("");
+  summary.push("Run /reload to refresh pi's model registry.");
+
+  ctx.ui.notify(summary.join("\n"), "info");
+}
+
+// =========================================================================
+// Command: /custom-provider:scan-models
+// =========================================================================
+
+interface RemoteModel {
+  id: string;
+  object?: string;
+  created?: number;
+  owned_by?: string;
+  max_model_len?: number;
+}
+
+interface ModelsListResponse {
+  object: string;
+  data: RemoteModel[];
+}
+
+async function scanModelsCommand(_args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const config = readModelsJson();
+  const providerNames = Object.keys(config.providers);
+
+  if (providerNames.length === 0) {
+    ctx.ui.notify(
+      "No custom providers found. Use /custom-provider:add-provider first.",
+      "warning",
+    );
+    return;
+  }
+
+  // Filter to providers that are OpenAI-compatible
+  const compatProviders = providerNames.filter((name) => {
+    const api = config.providers[name]!.api;
+    return !api || OPENAI_COMPAT_APIS.has(api);
+  });
+
+  if (compatProviders.length === 0) {
+    ctx.ui.notify(
+      "No OpenAI-compatible providers found. Scan requires providers using openai-completions or openai-responses API.",
+      "warning",
+    );
+    return;
+  }
+
+  // 1. Select provider
+  const selectedProvider = await ctx.ui.select(
+    "Select provider to scan for models",
+    compatProviders,
+  );
+  if (!selectedProvider) {
+    ctx.ui.notify("Cancelled: no provider selected.", "warning");
+    return;
+  }
+
+  const provider = config.providers[selectedProvider]!;
+  const baseUrl = provider.baseUrl?.replace(/\/+$/, "");
+
+  if (!baseUrl) {
+    ctx.ui.notify(`Provider "${selectedProvider}" has no base URL configured.`, "error");
+    return;
+  }
+
+  // 2. Fetch models from /v1/models or /models
+  const modelsEndpoint = baseUrl.endsWith("/v1") || baseUrl.endsWith("/v1/")
+    ? `${baseUrl}/models`
+    : `${baseUrl}/v1/models`;
+
+  ctx.ui.notify(`Scanning ${modelsEndpoint}...`, "info");
+
+  let response: ModelsListResponse;
+  try {
+    const headers: Record<string, string> = {
+      "Accept": "application/json",
+    };
+    if (provider.apiKey && provider.apiKey !== "none") {
+      headers["Authorization"] = `Bearer ${provider.apiKey}`;
+    }
+
+    const res = await fetch(modelsEndpoint, { headers, signal: AbortSignal.timeout(15_000) });
+    if (!res.ok) {
+      ctx.ui.notify(
+        `Failed to fetch models: HTTP ${res.status} ${res.statusText}\n` +
+        `Endpoint: ${modelsEndpoint}`,
+        "error",
+      );
+      return;
+    }
+    const body = await res.json() as ModelsListResponse;
+    if (!body.data || !Array.isArray(body.data)) {
+      ctx.ui.notify(
+        `Unexpected response format. Expected { "data": [...] }.\n` +
+        `Got: ${JSON.stringify(body).slice(0, 500)}`,
+        "error",
+      );
+      return;
+    }
+    response = body;
+  } catch (err) {
+    ctx.ui.notify(
+      `Failed to connect to ${modelsEndpoint}: ${err instanceof Error ? err.message : String(err)}`,
+      "error",
+    );
+    return;
+  }
+
+  if (response.data.length === 0) {
+    ctx.ui.notify("No models found at the endpoint.", "info");
+    return;
+  }
+
+  // 3. Show discovered models and let user select which to add
+  const existingIds = new Set((provider.models ?? []).map((m) => m.id));
+  const modelOptions = response.data.map((m) => {
+    const exists = existingIds.has(m.id) ? " [already added]" : "";
+    const maxLen = m.max_model_len ? ` (ctx: ${m.max_model_len})` : "";
+    const owner = m.owned_by ? ` - ${m.owned_by}` : "";
+    return `${m.id}${maxLen}${owner}${exists}`;
+  });
+
+  // Select which models to add
+  const selectedModels = await ctx.ui.custom<string[]>((tui, theme, _kb, done) => {
+    let cursorIndex = 0;
+    const selected = new Set<number>();
+    let cachedLines: string[] | undefined;
+    // Only allow selecting models that aren't already added
+    const addableIndices = response.data
+      .map((m, i) => ({ i, alreadyAdded: existingIds.has(m.id) }))
+      .filter((x) => !x.alreadyAdded)
+      .map((x) => x.i);
+
+    function refresh() {
+      cachedLines = undefined;
+      tui.requestRender();
+    }
+
+    function handleInput(data: string) {
+      if (matchesKey(data, Key.up)) {
+        cursorIndex = Math.max(0, cursorIndex - 1);
+        refresh();
+        return;
+      }
+      if (matchesKey(data, Key.down)) {
+        cursorIndex = Math.min(modelOptions.length - 1, cursorIndex + 1);
+        refresh();
+        return;
+      }
+      if (matchesKey(data, Key.space)) {
+        if (addableIndices.includes(cursorIndex)) {
+          if (selected.has(cursorIndex)) {
+            selected.delete(cursorIndex);
+          } else {
+            selected.add(cursorIndex);
+          }
+        }
+        refresh();
+        return;
+      }
+      if (matchesKey(data, Key.enter)) {
+        // If nothing selected, select all addable models
+        const toAdd = selected.size > 0
+          ? [...selected]
+          : addableIndices;
+        const ids = toAdd
+          .sort((a, b) => a - b)
+          .map((i) => response.data[i]!.id);
+        done(ids);
+        return;
+      }
+      if (matchesKey(data, Key.escape)) {
+        done([]);
+      }
+      // a/A to select/deselect all
+      if (data === "a") {
+        for (const i of addableIndices) selected.add(i);
+        refresh();
+        return;
+      }
+      if (data === "A") {
+        selected.clear();
+        refresh();
+        return;
+      }
+    }
+
+    function render(width: number): string[] {
+      if (cachedLines) return cachedLines;
+      const lines: string[] = [];
+      const add = (s: string) => lines.push(truncateToWidth(s, width));
+
+      add(theme.fg("accent", "─".repeat(width)));
+      add(theme.fg("text", ` Found ${response.data.length} models at ${selectedProvider}`));
+      lines.push("");
+
+      for (let i = 0; i < modelOptions.length; i++) {
+        const isCursor = i === cursorIndex;
+        const isAddable = addableIndices.includes(i);
+        const isChecked = selected.has(i);
+        const prefix = isCursor ? theme.fg("accent", "> ") : "  ";
+        const box = isAddable
+          ? (isChecked ? theme.fg("success", "☑") : theme.fg("dim", "☐"))
+          : theme.fg("dim", "■");
+        const label = isAddable
+          ? theme.fg("text", modelOptions[i]!)
+          : theme.fg("dim", modelOptions[i]!);
+        add(`${prefix}${box} ${label}`);
+      }
+
+      lines.push("");
+      const selectedCount = selected.size;
+      if (selectedCount > 0) {
+        add(theme.fg("dim", ` ${selectedCount} selected • Space toggle • Enter confirm • a/A select/deselect all • Esc cancel`));
+      } else {
+        add(theme.fg("dim", ` Enter to add all new models • Space toggle • a/A select/deselect all • Esc cancel`));
+      }
+
+      add(theme.fg("accent", "─".repeat(width)));
+      cachedLines = lines;
+      return lines;
+    }
+
+    return {
+      render,
+      invalidate: () => { cachedLines = undefined; },
+      handleInput,
+    };
+  });
+
+  if (selectedModels.length === 0) {
+    ctx.ui.notify("No models selected. Cancelled.", "info");
+    return;
+  }
+
+  // 4. Add selected models to provider
+  if (!provider.models) provider.models = [];
+
+  let addedCount = 0;
+  let skippedCount = 0;
+  for (const modelId of selectedModels) {
+    if (existingIds.has(modelId)) {
+      skippedCount++;
+      continue;
+    }
+    const remoteModel = response.data.find((m) => m.id === modelId);
+    const modelDef: ModelDefinition = {
+      id: modelId,
+      ...(remoteModel?.max_model_len ? { contextWindow: remoteModel.max_model_len } : {}),
+    };
+    provider.models.push(modelDef);
+    existingIds.add(modelId);
+    addedCount++;
+  }
+
+  writeModelsJson(config);
+
+  ctx.ui.notify(
+    `Scan complete for "${selectedProvider}".\n` +
+    `  Added: ${addedCount} model(s)\n` +
+    (skippedCount > 0 ? `  Skipped (already existing): ${skippedCount}\n` : "") +
+    `\nRun /reload to refresh pi's model registry.`,
+    "info",
+  );
+}
+
+// =========================================================================
+// Command: /custom-provider:remove-provider
+// =========================================================================
+
+async function removeProviderCommand(_args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const config = readModelsJson();
+  const providerNames = Object.keys(config.providers);
+
+  if (providerNames.length === 0) {
+    ctx.ui.notify(
+      "No custom providers found in models.json.",
+      "warning",
+    );
+    return;
+  }
+
+  // 1. Select provider to remove
+  const selectedProvider = await ctx.ui.select("Select provider to remove", providerNames);
+  if (!selectedProvider) {
+    ctx.ui.notify("Cancelled: no provider selected.", "warning");
+    return;
+  }
+
+  // 2. Confirm deletion
+  const provider = config.providers[selectedProvider]!;
+  const modelCount = provider.models?.length ?? 0;
+  const confirmMessage = modelCount > 0
+    ? `Remove provider "${selectedProvider}" and its ${modelCount} model(s)?`
+    : `Remove provider "${selectedProvider}"?`;
+
+  const confirmed = await ctx.ui.confirm(
+    confirmMessage,
+    `This will update models.json. Run /reload after to refresh pi's model registry.`,
+  );
+  if (!confirmed) {
+    ctx.ui.notify("Cancelled.", "info");
+    return;
+  }
+
+  // 3. Remove provider
+  delete config.providers[selectedProvider];
+  writeModelsJson(config);
+
+  ctx.ui.notify(
+    `Provider "${selectedProvider}" removed from models.json.\n` +
+    `Run /reload to refresh pi's model registry.`,
+    "info",
+  );
+}
+
+// =========================================================================
+// Command: /custom-provider:remove-model
+// =========================================================================
+
+async function removeModelCommand(_args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const config = readModelsJson();
+  const providerNames = Object.keys(config.providers);
+
+  if (providerNames.length === 0) {
+    ctx.ui.notify(
+      "No custom providers found in models.json.",
+      "warning",
+    );
+    return;
+  }
+
+  // 1. Select provider
+  const selectedProvider = await ctx.ui.select("Select provider to remove a model from", providerNames);
+  if (!selectedProvider) {
+    ctx.ui.notify("Cancelled: no provider selected.", "warning");
+    return;
+  }
+
+  const provider = config.providers[selectedProvider]!;
+  const models = provider.models ?? [];
+
+  if (models.length === 0) {
+    ctx.ui.notify(
+      `Provider "${selectedProvider}" has no models.`,
+      "warning",
+    );
+    return;
+  }
+
+  // 2. Select model to remove
+  const modelLabels = models.map((m) => m.name ? `${m.id} (${m.name})` : m.id);
+  const selectedModelLabel = await ctx.ui.select("Select model to remove", modelLabels);
+  if (!selectedModelLabel) {
+    ctx.ui.notify("Cancelled: no model selected.", "warning");
+    return;
+  }
+
+  const selectedIndex = modelLabels.indexOf(selectedModelLabel);
+  if (selectedIndex === -1) {
+    ctx.ui.notify("Cancelled: could not resolve model.", "warning");
+    return;
+  }
+
+  const modelToRemove = models[selectedIndex]!;
+
+  // 3. Confirm
+  const confirmed = await ctx.ui.confirm(
+    `Remove model "${modelToRemove.id}" from provider "${selectedProvider}"?`,
+    "This will update models.json. Run /reload after to refresh pi's model registry.",
+  );
+  if (!confirmed) {
+    ctx.ui.notify("Cancelled.", "info");
+    return;
+  }
+
+  // 4. Remove model
+  provider.models = models.filter((_, i) => i !== selectedIndex);
+  writeModelsJson(config);
+
+  ctx.ui.notify(
+    `Model "${modelToRemove.id}" removed from provider "${selectedProvider}" in models.json.\n` +
+    `Run /reload to refresh pi's model registry.`,
+    "info",
+  );
+}
+
+// =========================================================================
+// Install all custom-provider commands
+// =========================================================================
+
+export function installCustomProviderCommands(pi: ExtensionAPI): void {
+  pi.registerCommand("custom-provider:add-provider", {
+    description: "Add a custom provider to models.json (interactive wizard)",
+    handler: addProviderCommand,
+  });
+
+  pi.registerCommand("custom-provider:add-model", {
+    description: "Add a model to an existing custom provider in models.json",
+    handler: addModelCommand,
+  });
+
+  pi.registerCommand("custom-provider:scan-models", {
+    description: "Scan an OpenAI-compatible provider endpoint for available models and add them to models.json",
+    handler: scanModelsCommand,
+  });
+
+  pi.registerCommand("custom-provider:remove-provider", {
+    description: "Remove a custom provider and all its models from models.json",
+    handler: removeProviderCommand,
+  });
+
+  pi.registerCommand("custom-provider:remove-model", {
+    description: "Remove a model from an existing custom provider in models.json",
+    handler: removeModelCommand,
+  });
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { formatConfig } from "./config.js";
 import { installContextFiles } from "./context-files.js";
+import { installCustomProviderCommands } from "./custom-providers.js";
 import { installGuards } from "./guards.js";
 import { MoonpiController } from "./modes.js";
 import { formatTodoList } from "./state.js";
@@ -22,6 +23,7 @@ export default async function moonpi(pi: ExtensionAPI): Promise<void> {
   installGuards(pi, controller);
   installContextFiles(pi, controller);
   installSprintWorkflow(pi, controller);
+  installCustomProviderCommands(pi);
 
   pi.registerCommand("moonpi:mode", {
     description: "Switch moonpi mode: plan, act, auto, fast",
@@ -138,7 +140,7 @@ ${todoList}`);
 
   // Synthetic is optional; keep core Moonpi mode hooks installed even if provider setup fails.
   try {
-    await installSynthetic(pi);
+    await installSynthetic(pi, controller);
   } catch {
     // Ignore optional provider setup failures.
   }

package/src/modes.ts

@@ -40,6 +40,7 @@ function latestSnapshot(entries: SessionEntry[]): MoonpiSnapshot | undefined {
 export class MoonpiController {
   readonly state = new MoonpiState();
   config: MoonpiConfig = loadMoonpiConfig(process.cwd());
+  syntheticAuthenticated = false;
   private terminalInputUnsubscribe: (() => void) | undefined;
 
   constructor(private readonly pi: ExtensionAPI) {}
@@ -144,9 +145,14 @@ export class MoonpiController {
   }
 
   getToolsForCurrentMode(): string[] {
-    if (!this.config.preserveExternalTools) return STABLE_MOONPI_TOOLS;
-    const externalTools = this.pi.getActiveTools().filter((toolName) => !MOONPI_TOOL_NAMES.has(toolName));
-    return [...new Set([...STABLE_MOONPI_TOOLS, ...externalTools])];
+    let tools = this.config.preserveExternalTools
+      ? [...new Set([...STABLE_MOONPI_TOOLS, ...this.pi.getActiveTools().filter((toolName) => !MOONPI_TOOL_NAMES.has(toolName))])]
+      : [...STABLE_MOONPI_TOOLS];
+
+    if (this.syntheticAuthenticated && this.config.synthetic.search.enabled) {
+      tools.push("web_search");
+    }
+    return tools;
   }
 
   buildModePrompt(): string {

package/src/synthetic.ts

@@ -1,4 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ProviderModelConfig } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type, type Static } from "typebox";
+import type { MoonpiController } from "./modes.js";
 import { SYNTHETIC_MODELS_FALLBACK, mergeWithFallback, parseSyntheticModels, readCachedModels, writeCachedModels } from "./synthetic-models.js";
 
 const SYNTHETIC_PROVIDER = "synthetic";
@@ -6,6 +9,7 @@ const SYNTHETIC_API_KEY_ENV = "SYNTHETIC_API_KEY";
 const SYNTHETIC_OPENAI_BASE_URL = "https://api.synthetic.new/openai/v1";
 const SYNTHETIC_MODELS_URL = "https://api.synthetic.new/openai/v1/models";
 const SYNTHETIC_QUOTAS_URL = "https://api.synthetic.new/v2/quotas";
+const SYNTHETIC_SEARCH_URL = "https://api.synthetic.new/v2/search";
 const FETCH_TIMEOUT_MS = 15_000;
 
 type QuotasErrorKind = "cancelled" | "timeout" | "config" | "http" | "network";
@@ -238,6 +242,155 @@ async function getSyntheticApiKey(ctx: ExtensionCommandContext | ExtensionContex
   return storedKey ?? process.env[SYNTHETIC_API_KEY_ENV] ?? "";
 }
 
+// =========================================================================
+// Search API
+// =========================================================================
+
+interface SearchResult {
+  url: string;
+  title: string;
+  text: string;
+  published?: string;
+}
+
+interface SearchResponse {
+  results: SearchResult[];
+}
+
+const SearchParamsSchema = Type.Object({
+  query: Type.String({ description: "Search query" }),
+});
+
+type SearchParams = Static<typeof SearchParamsSchema>;
+
+interface SearchDetails {
+  query: string;
+  resultCount: number;
+}
+
+function formatSearchResults(query: string, results: SearchResult[]): string {
+  if (results.length === 0) {
+    return `No results found for "${query}".`;
+  }
+
+  const lines: string[] = [`Found ${results.length} result${results.length === 1 ? "" : "s"} for "${query}":\n`];
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i]!;
+    const num = i + 1;
+    lines.push(`${num}. **${result.title}**`);
+    lines.push(`   ${result.url}`);
+    if (result.published) {
+      try {
+        const date = new Date(result.published);
+        if (!Number.isNaN(date.getTime())) {
+          lines.push(`   Published: ${date.toISOString().split("T")[0]}`);
+        }
+      } catch {
+        // Skip unparseable dates
+      }
+    }
+    lines.push(`   ${result.text}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function registerSearchTool(pi: ExtensionAPI): void {
+  pi.registerTool<typeof SearchParamsSchema, SearchDetails>({
+    name: "web_search",
+    label: "web search",
+    description:
+      "Search the web using the Synthetic search API. Returns a list of results with title, URL, and text excerpt.",
+    promptSnippet: "Search the web for information",
+    promptGuidelines: [
+      "Use web_search when you need to find information on the web that you don't already know.",
+      "Prefer web_search over guessing URLs or making assumptions about external documentation.",
+    ],
+    parameters: SearchParamsSchema,
+    async execute(_toolCallId, params: SearchParams, signal, _onUpdate, ctx) {
+      const apiKey = await getSyntheticApiKey(ctx);
+      if (!apiKey) {
+        return {
+          content: [{ type: "text", text: "Error: Synthetic API key not available. Please re-authenticate with /login synthetic." }],
+          details: { query: params.query, resultCount: 0 } satisfies SearchDetails,
+        };
+      }
+
+      const signals = [AbortSignal.timeout(FETCH_TIMEOUT_MS)];
+      if (signal) signals.push(signal);
+      const combinedSignal = AbortSignal.any(signals);
+
+      try {
+        const response = await fetch(SYNTHETIC_SEARCH_URL, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            "X-Title": "moonpi",
+          },
+          body: JSON.stringify({ query: params.query }),
+          signal: combinedSignal,
+        });
+
+        if (!response.ok) {
+          let message = response.statusText;
+          const body = await response.text();
+          if (body.length > 0) {
+            try {
+              const parsed = JSON.parse(body) as { error?: unknown; message?: unknown };
+              if (typeof parsed.error === "string") message = parsed.error;
+              else if (typeof parsed.message === "string") message = parsed.message;
+              else message = body;
+            } catch {
+              message = body;
+            }
+          }
+          return {
+            content: [{ type: "text", text: `Error: Synthetic search API returned ${response.status}: ${message}` }],
+            details: { query: params.query, resultCount: 0 } satisfies SearchDetails,
+          };
+        }
+
+        const data = (await response.json()) as SearchResponse;
+        const results = data.results ?? [];
+        return {
+          content: [{ type: "text", text: formatSearchResults(params.query, results) }],
+          details: { query: params.query, resultCount: results.length } satisfies SearchDetails,
+        };
+      } catch (error: unknown) {
+        const aborted = combinedSignal.aborted || (error instanceof DOMException && error.name === "AbortError");
+        if (aborted) {
+          if (isTimeoutReason(combinedSignal.reason)) {
+            return {
+              content: [{ type: "text", text: "Error: Synthetic search request timed out." }],
+              details: { query: params.query, resultCount: 0 } satisfies SearchDetails,
+            };
+          }
+          return {
+            content: [{ type: "text", text: "Error: Synthetic search request was cancelled." }],
+            details: { query: params.query, resultCount: 0 } satisfies SearchDetails,
+          };
+        }
+
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: Synthetic search failed: ${message}` }],
+          details: { query: params.query, resultCount: 0 } satisfies SearchDetails,
+        };
+      }
+    },
+    renderResult(result, _options, theme) {
+      const text = result.content
+        .filter((item) => item.type === "text")
+        .map((item) => item.text)
+        .join("\n");
+      return new Text(theme.fg("toolOutput", text), 0, 0);
+    },
+  });
+}
+
 async function fetchSyntheticModels(apiKey: string, signal?: AbortSignal): Promise<ProviderModelConfig[] | null> {
   if (!apiKey) return null;
 
@@ -309,7 +462,16 @@ async function refreshLiveModels(pi: ExtensionAPI, apiKey: string, signal?: Abor
   return fetchedModels;
 }
 
-export async function installSynthetic(pi: ExtensionAPI): Promise<void> {
+export async function installSynthetic(pi: ExtensionAPI, controller: MoonpiController): Promise<void> {
+  let searchToolRegistered = false;
+  const searchEnabled = () => controller.config.synthetic.search.enabled;
+
+  function ensureSearchToolRegistered(): void {
+    if (searchToolRegistered || !searchEnabled()) return;
+    searchToolRegistered = true;
+    registerSearchTool(pi);
+  }
+
   // Fast path: read cached models from disk (synchronous, no network).
   // This ensures models are available immediately at init time, which is
   // critical for model restoration on session resume. Without this, models
@@ -327,6 +489,8 @@ export async function installSynthetic(pi: ExtensionAPI): Promise<void> {
   // resolved later in the session_start handler.
   const apiKey = process.env[SYNTHETIC_API_KEY_ENV] ?? "";
   if (apiKey) {
+    controller.syntheticAuthenticated = true;
+    ensureSearchToolRegistered();
     // Fire and forget – we already registered with cached/fallback models,
     // so startup isn't blocked on the network request.
     refreshLiveModels(pi, apiKey).catch(() => {
@@ -338,6 +502,14 @@ export async function installSynthetic(pi: ExtensionAPI): Promise<void> {
   // and refresh the model list from the live API.
   pi.on("session_start", async (_event, ctx) => {
     const apiKey = await getSyntheticApiKey(ctx);
+    const wasAuthenticated = controller.syntheticAuthenticated;
+    controller.syntheticAuthenticated = !!apiKey;
+    if (controller.syntheticAuthenticated && !searchToolRegistered) {
+      ensureSearchToolRegistered();
+    }
+    if (controller.syntheticAuthenticated !== wasAuthenticated) {
+      controller.applyMode(ctx);
+    }
     // Fire-and-forget: don't block session startup on the network request.
     // Cached/fallback models are already registered, so the provider is usable immediately.
     refreshLiveModels(pi, apiKey, ctx.signal).catch(() => {});

package/src/types.ts

@@ -35,6 +35,12 @@ export interface MoonpiConfig {
   /** Whether moonpi installs its custom mode-colored editor. Set to false to preserve
    *  editor customizations from other extensions (e.g. pi-wierd-statusline). */
   customEditor: boolean;
+  synthetic: {
+    search: {
+      /** Whether the web_search tool is available when logged in with Synthetic. */
+      enabled: boolean;
+    };
+  };
   contextFiles: {
     enabled: boolean;
     fileNames: string[];