@aliou/pi-ts-aperture 0.3.2 → 0.5.0

package/README.md

@@ -1,3 +1,5 @@
+![banner](https://assets.aliou.me/pi-extensions/banners/pi-ts-aperture.png)
+
 # pi-ts-aperture
 
 Route Pi LLM providers through [Tailscale Aperture](https://tailscale.com/docs/features/aperture), a managed AI gateway on your tailnet.
@@ -45,4 +47,4 @@ Additionally, the extension can bootstrap model IDs discovered from Aperture (`/
 
 - A Tailscale tailnet with Aperture configured
 - The device running Pi must be on the tailnet (or otherwise able to reach your Aperture endpoint)
-- Use the URL/scheme that matches your deployment (`http://` or `https://`)
+- Use the URL/scheme that matches your deployment (`http://` or `https://`)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aliou/pi-ts-aperture",
   "description": "Route Pi LLM providers through Tailscale Aperture",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "type": "module",
   "license": "MIT",
   "private": false,
@@ -29,12 +29,12 @@
     "video": "https://assets.aliou.me/pi-extensions/demos/pi-ts-aperture.mp4"
   },
   "dependencies": {
-    "@aliou/pi-utils-settings": "^0.10.0"
+    "@aliou/pi-utils-settings": "^0.12.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "0.61.0",
-    "@mariozechner/pi-coding-agent": "0.61.0",
-    "@mariozechner/pi-tui": "0.61.0"
+    "@mariozechner/pi-ai": "0.64.0",
+    "@mariozechner/pi-coding-agent": "0.64.0",
+    "@mariozechner/pi-tui": "0.64.0"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-coding-agent": {
@@ -51,7 +51,7 @@
     "@aliou/biome-plugins": "^0.3.2",
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-coding-agent": "0.61.0",
+    "@mariozechner/pi-coding-agent": "0.64.0",
     "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.18",
@@ -67,7 +67,8 @@
     "changeset": "changeset",
     "version": "changeset version",
     "release": "pnpm changeset publish",
-    "test": "vitest run tests/e2e.test.ts",
-    "test:watch": "vitest watch tests/"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run tests/e2e.test.ts"
   }
 }

package/src/commands/settings.ts

@@ -17,12 +17,12 @@ import type {
   ExtensionContext,
 } from "@mariozechner/pi-coding-agent";
 import { getSettingsListTheme } from "@mariozechner/pi-coding-agent";
-import type { ApertureConfig, ResolvedConfig } from "../config";
-import { configLoader } from "../config";
+import type { ApertureConfig, ResolvedConfig } from "../lib/config";
+import { configLoader } from "../lib/config";
 
 export function registerApertureSettings(
   pi: ExtensionAPI,
-  onConfigChange: (ctx: ExtensionContext) => void,
+  onSync: (ctx: ExtensionContext) => void,
 ): void {
   registerSettingsCommand<ApertureConfig, ResolvedConfig>(pi, {
     commandName: "aperture:settings",
@@ -37,6 +37,9 @@ export function registerApertureSettings(
 
       const providers = tabConfig?.providers ?? resolved.providers;
 
+      const checkGatewayModels: string[] =
+        tabConfig?.checkGatewayModels ?? resolved.checkGatewayModels;
+
       return [
         {
           label: "Connection",
@@ -51,6 +54,39 @@ export function registerApertureSettings(
               values: undefined,
               submenu: undefined,
             },
+            {
+              id: "checkGatewayModels",
+              label: "Gateway model checking",
+              description:
+                "Providers for which gateway model availability is checked",
+              currentValue:
+                checkGatewayModels.length > 0
+                  ? `${checkGatewayModels.length} provider(s)`
+                  : "disabled",
+              values: undefined,
+              submenu: (_val, submenuDone) => {
+                let latest = [...checkGatewayModels];
+                return new ArrayEditor({
+                  label: "Gateway-checked providers",
+                  items: [...checkGatewayModels],
+                  theme: settingsTheme,
+                  onSave: (items) => {
+                    latest = items;
+                    const updated = structuredClone(
+                      tabConfig ?? {},
+                    ) as ApertureConfig;
+                    setNestedValue(updated, "checkGatewayModels", items);
+                    setDraft(updated);
+                  },
+                  onDone: () =>
+                    submenuDone(
+                      latest.length > 0
+                        ? `${latest.length} provider(s)`
+                        : "disabled",
+                    ),
+                });
+              },
+            },
           ],
         },
         {
@@ -93,7 +129,7 @@ export function registerApertureSettings(
       return updated;
     },
     onSave: (ctx) => {
-      onConfigChange(ctx);
+      onSync(ctx);
     },
   });
 }

package/src/commands/setup.ts

@@ -2,256 +2,138 @@
  * aperture:setup -- interactive wizard for configuring Aperture.
  *
  * Steps:
- * 1. Ask for Aperture base URL (Input)
- * 2. Select providers to route through Aperture (FuzzySelector, multi-select loop)
- * 3. Save config and register providers
+ * 1. URL input (health check runs inline on Enter, auto-advances on success)
+ * 2. Provider selection with per-provider "verify models" sub-option
  */
 
-import { FuzzySelector } from "@aliou/pi-utils-settings";
+import {
+  FuzzyMultiSelector,
+  type FuzzyMultiSelectorItem,
+  getSettingsTheme,
+  type SettingsTheme,
+  Wizard,
+  type WizardStepContext,
+} from "@aliou/pi-utils-settings";
 import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@mariozechner/pi-coding-agent";
-import { getSettingsListTheme } from "@mariozechner/pi-coding-agent";
 import type { Component, TUI } from "@mariozechner/pi-tui";
-import { Input, Key, matchesKey } from "@mariozechner/pi-tui";
-import { configLoader } from "../config";
-import { checkApertureHealth } from "../lib/health";
-
-function normalizeUrl(url: string): string {
-  let result = url.trim();
-  if (!result) return result;
-  if (!result.startsWith("http://") && !result.startsWith("https://")) {
-    result = `http://${result}`;
-  }
-  return result.replace(/\/v1\/?$/, "").replace(/\/+$/, "");
-}
+import { Input } from "@mariozechner/pi-tui";
+import { configLoader } from "../lib/config";
+import { checkApertureHealth } from "../lib/gateway";
+import { normalizeInputUrl } from "../lib/url";
 
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
-/**
- * Shows a spinner while verifying the Aperture URL is reachable.
- * Kicks off the health check on construction and resolves done(boolean)
- * when the check completes.
- */
-class HealthCheckSpinner implements Component {
-  private theme: ReturnType<typeof getSettingsListTheme>;
-  private url: string;
+// ---------------------------------------------------------------------------
+// Step 1: URL input with inline health check
+// ---------------------------------------------------------------------------
+
+class UrlStep implements Component {
+  private input: Input;
+  private theme: SettingsTheme;
   private tui: TUI;
-  // true = healthy, false = failed (retry), undefined = cancelled
-  private done: (result: boolean | undefined) => void;
+  private wizCtx: WizardStepContext;
+  private onUrl: (url: string) => void;
+  private readonly placeholder = "ai.pango-lin.ts.net";
+
+  private state: "idle" | "checking" | "ok" | "error" = "idle";
+  private errorMessage = "";
   private frame = 0;
-  private timer: ReturnType<typeof setInterval>;
-  private result: { ok: boolean; error?: string } | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
 
   constructor(
-    theme: ReturnType<typeof getSettingsListTheme>,
-    url: string,
+    theme: SettingsTheme,
     tui: TUI,
-    done: (result: boolean | undefined) => void,
+    currentValue: string,
+    wizCtx: WizardStepContext,
+    onUrl: (url: string) => void,
   ) {
     this.theme = theme;
-    this.url = url;
     this.tui = tui;
-    this.done = done;
+    this.wizCtx = wizCtx;
+    this.onUrl = onUrl;
+    this.input = new Input();
+    if (currentValue) {
+      this.input.setValue(currentValue);
+    }
+    this.input.onSubmit = () => this.submit();
+  }
+
+  private submit(): void {
+    const value = this.input.getValue().trim();
+    if (!value || this.state === "checking") return;
+
+    const url = normalizeInputUrl(value);
+    this.state = "checking";
+    this.frame = 0;
 
-    // Animate spinner at ~80ms per frame.
     this.timer = setInterval(() => {
       this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
       this.tui.requestRender();
     }, 80);
 
-    // Fire the check.
     checkApertureHealth(url).then((res) => {
-      clearInterval(this.timer);
-      this.result = res;
-      this.tui.requestRender();
+      if (this.timer) clearInterval(this.timer);
+      this.timer = null;
 
-      // On success, auto-advance after a brief pause.
-      // On failure, wait for user input (see handleInput).
       if (res.ok) {
-        setTimeout(() => this.done(true), 600);
+        this.state = "ok";
+        this.onUrl(url);
+        this.wizCtx.markComplete();
+        this.tui.requestRender();
+        setTimeout(() => this.wizCtx.goNext(), 400);
+      } else {
+        this.state = "error";
+        this.errorMessage = res.error ?? "unknown error";
+        this.tui.requestRender();
       }
     });
   }
 
-  render(_width: number): string[] {
-    const lines: string[] = [];
-    lines.push(this.theme.label(" Aperture Setup", true));
-    lines.push("");
-
-    if (!this.result) {
-      const spinner = SPINNER_FRAMES[this.frame];
-      lines.push(
-        this.theme.hint(`  ${spinner} Checking connection to ${this.url}...`),
-      );
-    } else if (this.result.ok) {
-      lines.push(this.theme.hint(`  Connected to ${this.url}`));
-    } else {
-      lines.push(
-        this.theme.hint(`  Could not reach ${this.url}: ${this.result.error}`),
-      );
-      lines.push("");
-      lines.push(
-        this.theme.hint(
-          "  Make sure the URL is correct and you are connected to the tailnet.",
-        ),
-      );
-      lines.push("");
-      lines.push(this.theme.hint("  Enter: try another URL · Esc: cancel"));
-    }
-
-    lines.push("");
-    return lines;
-  }
-
-  invalidate() {}
-
-  handleInput(data: string) {
-    // Only handle input after a failed check.
-    if (!this.result || this.result.ok) return;
-
-    if (matchesKey(data, Key.enter)) {
-      this.done(false); // retry
-    } else if (matchesKey(data, Key.escape)) {
-      this.done(undefined); // cancel wizard
-    }
-  }
-
-  dispose() {
-    clearInterval(this.timer);
-  }
-}
-
-/**
- * Simple input prompt component for the base URL step.
- */
-class UrlPrompt implements Component {
-  private input: Input;
-  private done: (value: string | undefined) => void;
-  private theme: ReturnType<typeof getSettingsListTheme>;
-  private placeholder = "ai.pango-lin.ts.net";
-
-  constructor(
-    theme: ReturnType<typeof getSettingsListTheme>,
-    currentValue: string,
-    done: (value: string | undefined) => void,
-  ) {
-    this.theme = theme;
-    this.done = done;
-    this.input = new Input();
-    if (currentValue) {
-      this.input.setValue(currentValue);
-    }
-
-    this.input.onSubmit = () => {
-      const value = this.input.getValue().trim();
-      if (!value) return;
-      this.done(normalizeUrl(value));
-    };
-    this.input.onEscape = () => {
-      this.done(undefined);
-    };
-  }
-
   render(width: number): string[] {
     const lines: string[] = [];
-    lines.push(this.theme.label(" Aperture Setup", true));
-    lines.push("");
+
     lines.push(
       this.theme.hint(`  Aperture base URL (e.g. ${this.placeholder}):`),
     );
     lines.push(`  ${this.input.render(width - 4).join("")}`);
     lines.push("");
-    lines.push(this.theme.hint("  Enter: confirm · Esc: cancel"));
-    return lines;
-  }
-
-  invalidate() {}
-
-  handleInput(data: string) {
-    this.input.handleInput(data);
-  }
-}
-
-/**
- * Provider multi-select component. Uses FuzzySelector for search,
- * tracks selected providers, and lets the user confirm with Ctrl+S.
- */
-class ProviderMultiSelect implements Component {
-  private allProviders: string[];
-  private selected: Set<string>;
-  private theme: ReturnType<typeof getSettingsListTheme>;
-  private done: (value: string[] | undefined) => void;
-  private fuzzy: FuzzySelector;
 
-  constructor(
-    theme: ReturnType<typeof getSettingsListTheme>,
-    providers: string[],
-    preselected: string[],
-    done: (value: string[] | undefined) => void,
-  ) {
-    this.allProviders = providers;
-    this.selected = new Set(preselected);
-    this.theme = theme;
-    this.done = done;
-
-    this.fuzzy = new FuzzySelector({
-      label: "Select providers (Enter to toggle, Ctrl+S to confirm)",
-      items: this.allProviders,
-      theme,
-      onSelect: (value) => {
-        if (this.selected.has(value)) {
-          this.selected.delete(value);
-        } else {
-          this.selected.add(value);
-        }
-      },
-      onDone: () => {
-        this.done(undefined);
-      },
-    });
-  }
-
-  render(width: number): string[] {
-    const lines = this.fuzzy.render(width);
-
-    // Append selected providers summary
-    if (this.selected.size > 0) {
-      lines.push("");
-      lines.push(this.theme.hint(`  Selected (${this.selected.size}):`));
-      for (const p of this.selected) {
-        lines.push(`    ${this.theme.value(p, false)}`);
-      }
-    }
-
-    // Replace the hint line from FuzzySelector
-    const hintIndex = lines.findIndex((l) => l.includes("Type to search"));
-    if (hintIndex !== -1) {
-      lines[hintIndex] = this.theme.hint(
-        "  Type to search · Enter: toggle · Ctrl+S: confirm · Esc: cancel",
-      );
+    if (this.state === "checking") {
+      const spinner = SPINNER_FRAMES[this.frame];
+      lines.push(this.theme.hint(`  ${spinner} Checking connection...`));
+    } else if (this.state === "ok") {
+      lines.push(this.theme.hint("  Connected."));
+    } else if (this.state === "error") {
+      lines.push(this.theme.hint(`  Could not connect: ${this.errorMessage}`));
+      lines.push(this.theme.hint("  Fix the URL and press Enter to retry."));
     }
 
     return lines;
   }
 
-  invalidate() {
-    this.fuzzy.invalidate();
+  invalidate(): void {}
+
+  handleInput(data: string): void {
+    if (this.state === "checking") return;
+    this.state = "idle";
+    this.input.handleInput(data);
   }
 
-  handleInput(data: string) {
-    if (matchesKey(data, Key.ctrl("s"))) {
-      this.done([...this.selected]);
-      return;
-    }
-    this.fuzzy.handleInput(data);
+  dispose(): void {
+    if (this.timer) clearInterval(this.timer);
   }
 }
 
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
 export function registerSetupCommand(
   pi: ExtensionAPI,
-  onConfigChange: (ctx: ExtensionContext) => void,
+  onSync: (ctx: ExtensionContext) => void,
 ): void {
   pi.registerCommand("aperture:setup", {
     description: "Configure Tailscale Aperture integration",
@@ -265,57 +147,82 @@ export function registerSetupCommand(
       }
 
       const config = configLoader.getConfig();
-      const settingsTheme = getSettingsListTheme();
+      const checkGatewayProviders = config.checkGatewayModels ?? [];
 
-      // Step 1: base URL + health check loop.
-      // On failure, loop back to the URL prompt so the user can retry.
-      let baseUrl: string | undefined;
-      while (true) {
-        baseUrl = await ctx.ui.custom<string | undefined>(
-          (_tui, _theme, _kb, done) => {
-            return new UrlPrompt(
-              settingsTheme,
-              baseUrl ?? config.baseUrl,
-              done,
-            );
-          },
-        );
-
-        if (!baseUrl) return;
-        const urlToCheck = baseUrl;
-
-        const result = await ctx.ui.custom<boolean | undefined>(
-          (tui, _theme, _kb, done) => {
-            return new HealthCheckSpinner(settingsTheme, urlToCheck, tui, done);
-          },
-        );
-
-        if (result === true) break; // healthy, proceed
-        if (result === undefined) return; // cancelled
-      }
-
-      // Step 2: select providers
-      // Use model registry so custom/extension providers are included.
       const knownProviders = Array.from(
         new Set(ctx.modelRegistry.getAll().map((model) => model.provider)),
       ).sort((a, b) => a.localeCompare(b));
 
-      const providers = await ctx.ui.custom<string[] | undefined>(
-        (_tui, _theme, _kb, done) => {
-          return new ProviderMultiSelect(
-            settingsTheme,
-            knownProviders,
-            config.providers,
-            done,
-          );
+      let baseUrl = config.baseUrl;
+
+      const providerItems: FuzzyMultiSelectorItem[] = knownProviders.map(
+        (p) => ({
+          label: p,
+          checked: config.providers.includes(p),
+          subOptions: [
+            {
+              label: "verify models on gateway",
+              description:
+                "Warn at startup if this provider's models are missing from the Aperture gateway",
+              checked: checkGatewayProviders.includes(p),
+            },
+          ],
+        }),
+      );
+
+      const confirmed = await ctx.ui.custom<boolean | undefined>(
+        (tui, theme, _kb, done) => {
+          const settingsTheme = getSettingsTheme(theme);
+
+          return new Wizard({
+            title: "Aperture Setup",
+            theme: settingsTheme,
+            minContentHeight: 16,
+            steps: [
+              {
+                label: "URL",
+                build: (wCtx: WizardStepContext) =>
+                  new UrlStep(settingsTheme, tui, baseUrl, wCtx, (url) => {
+                    baseUrl = url;
+                  }),
+              },
+              {
+                label: "Providers",
+                build: (wCtx: WizardStepContext) => {
+                  wCtx.markComplete();
+                  return new FuzzyMultiSelector({
+                    label: "Providers to route through Aperture",
+                    items: providerItems,
+                    theme: settingsTheme,
+                    showHints: false,
+                    showCount: false,
+                    maxVisible: 7,
+                  });
+                },
+              },
+            ],
+            onComplete: () => done(true),
+            onCancel: () => done(undefined),
+          });
         },
       );
 
-      if (!providers) return;
+      if (!confirmed) return;
+
+      const providers = providerItems
+        .filter((i) => i.checked)
+        .map((i) => i.label);
+
+      const checkGatewayModels = providerItems
+        .filter((i) => i.checked && i.subOptions?.[0]?.checked)
+        .map((i) => i.label);
 
-      // Step 3: save and register
-      await configLoader.save("global", { baseUrl, providers });
-      onConfigChange(ctx);
+      await configLoader.save("global", {
+        baseUrl,
+        providers,
+        checkGatewayModels,
+      });
+      onSync(ctx);
       ctx.ui.notify(
         `Aperture configured: ${providers.length} provider(s) via ${baseUrl}`,
         "info",

package/src/extension/runtime.ts

@@ -0,0 +1,122 @@
+/**
+ * ApertureRuntime -- core extension runtime logic.
+ *
+ * Handles provider registration, unregistration, and gateway model checking.
+ */
+
+import { getApiProvider } from "@mariozechner/pi-ai";
+import { configLoader } from "../lib/config";
+import { fetchGatewayModelIds } from "../lib/gateway";
+import type {
+  Api,
+  AssistantMessageEventStream,
+  CheckDeps,
+  Context,
+  Model,
+  SimpleStreamOptions,
+  SyncDeps,
+} from "../lib/types";
+import { resolveProviderBaseUrl } from "../lib/url";
+
+/**
+ * Preserve provenance similarly to pi-synthetic so downstream providers can
+ * attribute traffic to Pi / this extension.
+ */
+const APERTURE_PROVENANCE_HEADERS = {
+  Referer: "https://pi.dev",
+  "X-Title": "npm:@aliou/pi-ts-aperture",
+};
+
+function resolveProviderHeaders(models: Model<Api>[]): Record<string, string> {
+  const modelHeaders = models.find((m) => m.headers)?.headers ?? {};
+  return {
+    ...APERTURE_PROVENANCE_HEADERS,
+    ...modelHeaders,
+  };
+}
+
+export class ApertureRuntime {
+  private registeredProviders = new Set<string>();
+
+  async sync(deps: SyncDeps): Promise<void> {
+    const config = configLoader.getConfig();
+    if (!config.baseUrl || config.providers.length === 0) {
+      return;
+    }
+
+    const baseUrl = resolveProviderBaseUrl(config);
+    if (!baseUrl) return;
+
+    const allModels = deps.getModels();
+
+    for (const providerName of config.providers) {
+      const providerModels = allModels.filter(
+        (m) => m.provider === providerName,
+      );
+      if (providerModels.length === 0) continue;
+
+      const api = providerModels[0].api ?? "openai-completions";
+      const builtIn = getApiProvider(api);
+
+      deps.registerProvider(providerName, {
+        baseUrl,
+        apiKey: "-",
+        headers: resolveProviderHeaders(providerModels),
+        api,
+        streamSimple: builtIn
+          ? (
+              model: Model<Api>,
+              context: Context,
+              options?: SimpleStreamOptions,
+            ): AssistantMessageEventStream =>
+              builtIn.streamSimple(model, context, {
+                ...options,
+                headers: {
+                  ...options?.headers,
+                  "x-session-id": options?.sessionId ?? "",
+                },
+              })
+          : undefined,
+      });
+
+      this.registeredProviders.add(providerName);
+    }
+  }
+
+  async checkMissingModels(deps: CheckDeps, gatewayUrl: string): Promise<void> {
+    const config = configLoader.getConfig();
+    if (config.checkGatewayModels.length === 0) return;
+
+    const gatewayModelIds = await fetchGatewayModelIds(gatewayUrl);
+    if (gatewayModelIds.length === 0) return;
+
+    const allModels = deps.getModels();
+    const checkedProviders = new Set(config.checkGatewayModels);
+
+    const routedModels = allModels.filter((m) =>
+      checkedProviders.has(m.provider),
+    );
+    const missingModels = routedModels.filter(
+      (m) => !gatewayModelIds.includes(m.id),
+    );
+
+    if (missingModels.length > 0) {
+      const ids = missingModels.map((m) => m.id).join(", ");
+      deps.notify(
+        `[aperture] models not available on gateway: ${ids}. Add them to the gateway configuration.`,
+        "warning",
+      );
+    }
+  }
+
+  /**
+   * Returns providers that should be unregistered based on config changes.
+   * Compares previous providers with new ones.
+   */
+  getProvidersToUnregister(
+    prevProviders: string[],
+    nextProviders: string[],
+  ): string[] {
+    return prevProviders.filter((p) => !nextProviders.includes(p));
+  }
+}

package/src/index.ts

@@ -1,10 +1,10 @@
 /**
  * Pi extension for Tailscale Aperture integration.
  *
- * Keeps the entry point focused on orchestration:
- * - load config
- * - register lifecycle hooks
- * - register user commands
+ * Entry point orchestration:
+ * - Load config
+ * - Register session_start hook for provider registration
+ * - Register user commands
  */
 
 import type {
@@ -13,76 +13,85 @@ import type {
 } from "@mariozechner/pi-coding-agent";
 import { registerApertureSettings } from "./commands/settings";
 import { registerSetupCommand } from "./commands/setup";
-import { configLoader } from "./config";
-import { applyAperture, refreshActiveModel } from "./providers/aperture";
+import { ApertureRuntime } from "./extension/runtime";
+import { configLoader } from "./lib/config";
+import { resolveGatewayUrl } from "./lib/url";
 
-function registerApertureLifecycleHook(pi: ExtensionAPI): void {
-  const warnedModels = new Set<string>();
+export default async function (pi: ExtensionAPI): Promise<void> {
+  await configLoader.load();
 
-  pi.on("before_agent_start", async (_event, ctx) => {
-    if (!ctx?.modelRegistry) return;
+  const runtime = new ApertureRuntime();
+  let lastRegisteredProviders: string[] = [
+    ...configLoader.getConfig().providers,
+  ];
 
-    const { providers: overriddenProviders, missingModels } =
-      await applyAperture(pi, ctx.modelRegistry);
+  // Sync function used by commands after config changes
+  const onSync = (ctx: ExtensionContext): void => {
+    const config = configLoader.getConfig();
 
-    const newMissing = missingModels.filter((id) => !warnedModels.has(id));
-    if (newMissing.length > 0) {
-      for (const id of newMissing) warnedModels.add(id);
+    // Unregister providers that were removed from config
+    const prevProviders = lastRegisteredProviders;
+    const nextProviders = config.providers;
+    const toRemove = runtime.getProvidersToUnregister(
+      prevProviders,
+      nextProviders,
+    );
+    for (const provider of toRemove) {
+      pi.unregisterProvider(provider);
       ctx.ui.notify(
-        `[aperture] models not available on gateway: ${newMissing.join(", ")}. Add them to the gateway configuration.`,
-        "warning",
+        `[aperture] unregistered ${provider}. Run /reload to use the native provider.`,
+        "info",
       );
     }
 
-    if (!ctx.model || !overriddenProviders.includes(ctx.model.provider)) return;
-
-    await refreshActiveModel(pi, ctx);
-  });
-}
-
-function createConfigChangeHandler(
-  pi: ExtensionAPI,
-): (ctx: ExtensionContext) => void {
-  let lastRegisteredProviders = [...configLoader.getConfig().providers];
-
-  return (ctx: ExtensionContext) => {
-    const { providers } = configLoader.getConfig();
-    const removedProviders = lastRegisteredProviders.filter(
-      (provider) => !providers.includes(provider),
-    );
+    // Re-register providers
+    void runtime
+      .sync({
+        registerProvider: pi.registerProvider.bind(pi),
+        getModels: () => ctx.modelRegistry.getAll(),
+      })
+      .then(() => {
+        // Refresh active model if it's from a registered provider
+        if (
+          ctx.model &&
+          ctx.modelRegistry.find(ctx.model.provider, ctx.model.id)
+        ) {
+          const updated = ctx.modelRegistry.find(
+            ctx.model.provider,
+            ctx.model.id,
+          );
+          if (updated && config.providers.includes(ctx.model.provider)) {
+            void pi.setModel(updated);
+          }
+        }
+      });
 
-    void applyAperture(pi, ctx.modelRegistry).then(({ missingModels }) => {
-      if (missingModels.length > 0) {
-        ctx.ui.notify(
-          `[aperture] models not available on gateway: ${missingModels.join(", ")}. Add them to the gateway configuration.`,
-          "warning",
+    // Check for missing models on gateway if configured
+    if (config.checkGatewayModels.length > 0) {
+      const gatewayUrl = resolveGatewayUrl(config);
+      if (gatewayUrl) {
+        void runtime.checkMissingModels(
+          {
+            getModels: () => ctx.modelRegistry.getAll(),
+            notify: (msg, type) => ctx.ui.notify(msg, type),
+          },
+          gatewayUrl,
         );
       }
-    });
-    lastRegisteredProviders = [...providers];
-
-    if (ctx.model && providers.includes(ctx.model.provider)) {
-      void refreshActiveModel(pi, ctx).then((updated) => {
-        if (!updated) return;
-        ctx.ui.notify(
-          `[aperture] re-routing ${ctx.model?.id ?? "model"} through ${ctx.model?.baseUrl ?? "aperture"}`,
-          "info",
-        );
-      });
     }
 
-    for (const provider of removedProviders) {
-      pi.unregisterProvider(provider);
-    }
+    lastRegisteredProviders = [...nextProviders];
   };
-}
 
-export default async function (pi: ExtensionAPI): Promise<void> {
-  await configLoader.load();
-
-  registerApertureLifecycleHook(pi);
+  // Register providers at session start (for new sessions)
+  pi.on("session_start", (_event, ctx) => {
+    lastRegisteredProviders = [...configLoader.getConfig().providers];
+    void runtime.sync({
+      registerProvider: pi.registerProvider.bind(pi),
+      getModels: () => ctx.modelRegistry.getAll(),
+    });
+  });
 
-  const onConfigChange = createConfigChangeHandler(pi);
-  registerSetupCommand(pi, onConfigChange);
-  registerApertureSettings(pi, onConfigChange);
+  registerSetupCommand(pi, onSync);
+  registerApertureSettings(pi, onSync);
 }

package/src/{config.ts → lib/config.ts}

@@ -10,16 +10,19 @@ import { ConfigLoader } from "@aliou/pi-utils-settings";
 export interface ApertureConfig {
   baseUrl?: string;
   providers?: string[];
+  checkGatewayModels?: string[];
 }
 
 export interface ResolvedConfig {
   baseUrl: string;
   providers: string[];
+  checkGatewayModels: string[];
 }
 
 const DEFAULT_CONFIG: ResolvedConfig = {
   baseUrl: "",
   providers: [],
+  checkGatewayModels: [],
 };
 
 export const configLoader = new ConfigLoader<ApertureConfig, ResolvedConfig>(

package/src/lib/{health.ts → gateway.ts}

@@ -1,8 +1,5 @@
 /**
- * Health check for the Aperture gateway.
- *
- * Hits GET <baseUrl>/v1/models to verify the gateway is reachable.
- * Uses native fetch (no extra dependencies).
+ * Gateway health and model checking.
  */
 
 export interface HealthCheckResult {

package/src/lib/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Internal types for Aperture extension.
+ */
+
+import type {
+  Api,
+  AssistantMessageEventStream,
+  Context,
+  Model,
+  SimpleStreamOptions,
+} from "@mariozechner/pi-ai";
+
+export type {
+  Api,
+  AssistantMessageEventStream,
+  Context,
+  Model,
+  SimpleStreamOptions,
+};
+
+/**
+ * Dependencies for ApertureRuntime.sync()
+ */
+export interface SyncDeps {
+  registerProvider: (
+    name: string,
+    config: {
+      baseUrl: string;
+      apiKey: string;
+      headers: Record<string, string>;
+      api: string;
+      streamSimple?: (
+        model: Model<Api>,
+        context: Context,
+        options?: SimpleStreamOptions,
+      ) => AssistantMessageEventStream;
+    },
+  ) => void;
+  getModels: () => Model<Api>[];
+}
+
+/**
+ * Dependencies for ApertureRuntime.checkMissingModels()
+ */
+export interface CheckDeps {
+  getModels: () => Model<Api>[];
+  notify: (msg: string, type: "warning" | "info") => void;
+}
+
+/**
+ * Headers for provider registration.
+ */
+export interface ProviderHeaders {
+  Referer: string;
+  "X-Title": string;
+}

package/src/lib/url.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure URL helpers.
+ */
+
+import type { ApertureConfig } from "./config";
+
+/**
+ * Normalizes a user-input URL:
+ * - Trims whitespace
+ * - Adds http:// scheme if missing
+ * - Strips trailing /v1 or /v1/
+ * - Strips trailing slashes
+ */
+export function normalizeInputUrl(raw: string): string {
+  let result = raw.trim();
+  if (!result) return result;
+  if (!result.startsWith("http://") && !result.startsWith("https://")) {
+    result = `http://${result}`;
+  }
+  return result.replace(/\/v1\/?$/, "").replace(/\/+$/, "");
+}
+
+/**
+ * Returns configured gateway URL without trailing slash.
+ * Returns null when baseUrl is empty or providers list is empty.
+ */
+export function resolveGatewayUrl(config: ApertureConfig): string | null {
+  const { baseUrl, providers } = config;
+  if (!baseUrl || providers?.length === 0) return null;
+  return baseUrl.replace(/\/+$/, "");
+}
+
+/**
+ * Returns the Aperture provider base URL used for provider registration.
+ * Appends /v1 to the gateway URL.
+ * Returns null when gateway URL cannot be resolved.
+ */
+export function resolveProviderBaseUrl(config: ApertureConfig): string | null {
+  const gateway = resolveGatewayUrl(config);
+  if (!gateway) return null;
+  return `${gateway}/v1`;
+}

package/src/providers/aperture.ts

@@ -1,112 +0,0 @@
-import type {
-  ExtensionAPI,
-  ExtensionContext,
-  ProviderModelConfig,
-} from "@mariozechner/pi-coding-agent";
-import { configLoader } from "../config";
-import { fetchGatewayModelIds } from "../lib/health";
-
-/**
- * Preserve provenance similarly to pi-synthetic so downstream providers can
- * attribute traffic to Pi / this extension.
- */
-const APERTURE_PROVENANCE_HEADERS = {
-  Referer: "https://pi.dev",
-  "X-Title": "npm:@aliou/pi-ts-aperture",
-};
-
-/** Returns configured gateway URL without trailing slash. */
-export function resolveGatewayUrl(): string | null {
-  const { baseUrl, providers } = configLoader.getConfig();
-  if (!baseUrl || providers.length === 0) return null;
-  return baseUrl.replace(/\/+$/, "");
-}
-
-/**
- * Returns the Aperture provider base URL used for provider registration.
- *
- * Aperture exposes multiple protocol paths (OpenAI, Anthropic, Gemini, ...).
- * For this extension we route through the OpenAI-compatible `/v1` surface that
- * Pi providers use (`openai-completions` API).
- */
-export function resolveApertureProviderBaseUrl(): string | null {
-  const gateway = resolveGatewayUrl();
-  if (!gateway) return null;
-  return `${gateway}/v1`;
-}
-
-function resolveProviderHeaders(
-  models: ProviderModelConfig[],
-): Record<string, string> {
-  const modelHeaders = models.find((m) => m.headers)?.headers ?? {};
-  return {
-    ...APERTURE_PROVENANCE_HEADERS,
-    ...modelHeaders,
-  };
-}
-
-/**
- * Apply Aperture override to configured providers.
- *
- * Only patches baseUrl, apiKey, and headers. Models are left exactly as
- * registered by Pi built-ins or other extensions -- Aperture never touches
- * model definitions.
- *
- * Providers with no models in the registry are skipped (nothing to reroute).
- */
-export async function applyAperture(
-  pi: ExtensionAPI,
-  registry: ExtensionContext["modelRegistry"],
-): Promise<{ providers: string[]; missingModels: string[] }> {
-  const baseUrl = resolveApertureProviderBaseUrl();
-  if (!baseUrl) return { providers: [], missingModels: [] };
-
-  const { providers } = configLoader.getConfig();
-
-  for (const provider of providers) {
-    const existingModels = registry
-      .getAll()
-      .filter((m) => m.provider === provider) as ProviderModelConfig[];
-
-    if (existingModels.length === 0) continue;
-
-    pi.registerProvider(provider, {
-      baseUrl,
-      apiKey: "-",
-      headers: resolveProviderHeaders(existingModels),
-      api: existingModels[0].api,
-      models: existingModels,
-    });
-  }
-
-  const gatewayUrl = resolveGatewayUrl();
-  const gatewayModelIds = gatewayUrl
-    ? await fetchGatewayModelIds(gatewayUrl)
-    : [];
-
-  let missingModels: string[] = [];
-  if (gatewayModelIds.length > 0) {
-    const routedModelIds = registry
-      .getAll()
-      .filter((m) => providers.includes(m.provider))
-      .map((m) => m.id);
-    missingModels = routedModelIds.filter(
-      (id) => !gatewayModelIds.includes(id),
-    );
-  }
-
-  return { providers, missingModels };
-}
-
-/** Re-resolve and set current model after provider registry updates. */
-export async function refreshActiveModel(
-  pi: ExtensionAPI,
-  ctx: ExtensionContext,
-): Promise<boolean> {
-  if (!ctx.model) return false;
-
-  const updated = ctx.modelRegistry.find(ctx.model.provider, ctx.model.id);
-  if (!updated) return false;
-
-  return pi.setModel(updated);
-}