@aliou/pi-ts-aperture 0.5.0 → 0.6.0

package/README.md

@@ -1,50 +1,148 @@
-![banner](https://assets.aliou.me/pi-extensions/banners/pi-ts-aperture.png)
+![banner](https://assets.aliou.me/github/aliou/pi-ts-aperture/banner.png)
 
 # pi-ts-aperture
 
 Route Pi LLM providers through [Tailscale Aperture](https://tailscale.com/docs/features/aperture), a managed AI gateway on your tailnet.
 
-Aperture handles API key injection and request routing server-side. This extension overrides selected providers so requests go through your Aperture gateway instead of directly to upstream provider APIs.
+Aperture handles API key injection and request routing server-side. This extension integrates Pi with Aperture using two independent capabilities: **dedicated** (a standalone `aperture` provider) and **proxy** (reroute existing Pi providers). Dedicated is enabled by default, and you can enable proxy at the same time.
 
-## Setup
+## Install
 
 ```bash
 pi install npm:@aliou/pi-ts-aperture
 ```
 
-Then run the setup wizard:
+## First run
+
+After installing, run the onboarding wizard:
 
 ```
-/aperture:setup
+/aperture:onboarding
 ```
 
-This prompts for:
-1. Aperture base URL (for example `ai.your-tailnet.ts.net`)
-2. Providers to route through Aperture (fuzzy searchable, multi-select)
+[![Onboarding walkthrough](https://assets.aliou.me/pi-extensions/demos/aperture/v0.6.0/onboarding.gif)](https://assets.aliou.me/pi-extensions/demos/aperture/v0.6.0/onboarding.mp4)
 
-Configuration is saved globally to `~/.pi/agent/extensions/aperture.json`.
+The wizard walks you through:
+
+1. Aperture base URL, with a `/v1/models` health check (e.g. `ai.your-tailnet.ts.net`).
+2. Capability selection: dedicated, proxy, or both.
+3. Provider selection:
+   - Dedicated: choose which Aperture gateway providers to include.
+   - Proxy: choose matching local Pi providers to route through Aperture, with optional gateway model verification.
+4. Recap, save, and reload Pi so the selected capabilities are registered cleanly.
+
+You can change everything later with:
+
+```
+/aperture:settings
+```
+
+## Capabilities
+
+### Dedicated provider (default)
+
+Registers a standalone `aperture` provider whose model list comes from the Aperture gateway. You can include all gateway providers or filter to specific gateway providers during onboarding or in settings.
+
+Dedicated model IDs are the model IDs reported by Aperture. They are not prefixed with the upstream provider ID. The extension keeps an internal route map so each model uses the Pi API that matches its Aperture provider compatibility.
+
+Because Aperture does not expose every Pi model capability yet, models use safe defaults on first load: 128k context, 8k max output, text input, and no reasoning. Gateway pricing is mapped to Pi costs when Aperture returns pricing data.
+
+#### Sync model capabilities
+
+In dedicated mode, the onboarding extension can stay enabled until model metadata is synced and validated. It exposes:
+
+- `sync-aperture-models` skill: looks up real capabilities such as context window, max tokens, reasoning, and input modalities, then updates `~/.pi/agent/models.json`.
+- `aperture_validate_models_json` tool: validates Pi's `models.json` schema and checks that Aperture models include capability fields.
+- `aperture_complete_onboarding` tool: marks onboarding complete and disables the temporary onboarding tools and skill after validation passes.
+
+User-defined model entries in `models.json` take precedence over gateway defaults and persist across restarts. The extension still owns routing details and cost data from Aperture gateway pricing.
+
+### Proxy existing providers
+
+Reroutes existing Pi providers (anthropic, openai, openai-codex, etc.) through Aperture. Each provider keeps its own model definitions and settings. Only the base URL, API key, and headers are overridden.
+
+Proxy provider selection maps Aperture providers to local Pi registry providers by base URL. It supports child path matching, so an Aperture provider under `https://chatgpt.com/backend-api/codex` can match Pi's local `https://chatgpt.com/backend-api` provider. If base URLs are unavailable, matching also falls back to provider IDs.
+
+Proxy mode is useful when you want Pi's native per-provider model configuration but want requests to go through Aperture for server-side credentials and routing.
 
 ## Commands
 
 | Command | Description |
 |---|---|
-| `/aperture:setup` | Interactive wizard to configure Aperture URL and routed providers |
-| `/aperture:settings` | Settings UI to update URL and routed provider list |
+| `/aperture:onboarding` | Onboarding wizard. Only available while onboarding is enabled. |
+| `/aperture:settings` | Settings UI to update connection, capabilities, proxy providers, dedicated provider filters, onboarding status, and the onboarding extension toggle. |
 
 ## How it works
 
-For each configured provider, the extension calls `registerProvider` with:
+### Aperture API usage
+
+The extension reads provider data from Aperture using:
+
+- `GET /api/providers` for gateway providers and models.
+- `GET /aperture/config` for provider compatibility, names, and base URLs.
+
+### Request routing
+
+Requests sent through Aperture include provenance headers:
+
+- `Referer: https://pi.dev`
+- `X-Title: npm:@aliou/pi-ts-aperture`
+- `x-session-id` for grouping requests in the Aperture dashboard
+
+### Proxy routing
+
+For each configured upstream provider, the extension calls `registerProvider` with:
+
+- `baseUrl` set to your Aperture URL + `/v1` for most Pi APIs.
+- `baseUrl` set to the Aperture root for APIs where Pi appends its own path, such as `openai-codex-responses`.
+- `apiKey` set to `"-"` because Aperture injects upstream credentials server-side. OAuth credentials still take precedence when Pi has them.
+
+Optional gateway model verification can warn when configured Pi models are missing from the Aperture gateway.
+
+### Dedicated routing
+
+Dedicated mode fetches models from Aperture, maps provider compatibility to Pi APIs, merges gateway defaults with user-defined `providers.aperture.models` from `~/.pi/agent/models.json`, and registers an `aperture` provider.
+
+Compatibility controls the Pi API and base URL used for each upstream provider at runtime. For example, OpenAI-compatible providers use `/v1`, Anthropic-compatible providers use the gateway root, Gemini-compatible providers use `/v1beta`, and Vertex-compatible providers use `/v1`.
+
+User-defined models from `models.json` take precedence over gateway defaults, so custom capabilities such as reasoning, context window, max output, and input modalities are preserved across restarts. If a user model does not define cost, the extension keeps the cost derived from Aperture gateway pricing.
+
+## Configuration
+
+Configuration is saved globally to `~/.pi/agent/extensions/aperture.json`.
+
+```json
+{
+  "baseUrl": "http://ai.your-tailnet.ts.net",
+  "onboardingDone": true,
+  "onboarding": {
+    "enabled": false
+  },
+  "proxy": {
+    "enabled": true,
+    "upstreamProviders": [
+      { "id": "anthropic", "shouldCheckGatewayModels": true }
+    ]
+  },
+  "dedicated": {
+    "enabled": true,
+    "providers": [
+      { "id": "anthropic", "name": "Anthropic", "enabled": true },
+      { "id": "openai", "name": "OpenAI", "enabled": true },
+      { "id": "google", "name": "Google", "enabled": false }
+    ]
+  }
+}
+```
 
-- `baseUrl` set to your Aperture URL + `/v1` (OpenAI-compatible surface used by Pi provider configs)
-- `apiKey` set to `"-"` (Aperture injects upstream credentials server-side)
-- provenance headers:
-  - `Referer: https://pi.dev`
-  - `X-Title: npm:@aliou/pi-ts-aperture`
+Notes:
 
-Additionally, the extension can bootstrap model IDs discovered from Aperture (`/api/providers`) for providers like OpenRouter so CLI model selection can resolve Aperture-exposed model IDs before the first prompt.
+- There is no `mode` setting. Use `proxy.enabled` and `dedicated.enabled` independently.
+- An empty `dedicated.providers` list means all Aperture gateway providers are included.
+- Model metadata belongs in `~/.pi/agent/models.json`, not in the extension config.
 
 ## Requirements
 
-- 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://`)
+- 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://`).

package/extensions/aperture/dedicated/api-routing.ts

@@ -0,0 +1,66 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { getApiProvider } from "@earendil-works/pi-ai";
+import type { ProviderCompatibility } from "../../../src/api/types";
+import type {
+  AssistantMessageEventStream,
+  Context,
+  SimpleStreamOptions,
+} from "../shared/types";
+
+interface ModelRoute {
+  api: Api;
+}
+
+export function getApiForCompatibility(
+  compatibility: ProviderCompatibility | undefined,
+): Api {
+  // Prefer chat completions when available: it is Aperture's default and the
+  // broadest compatibility mode for Pi's tool-calling path.
+  if (!compatibility || compatibility.openai_chat) return "openai-completions";
+  if (compatibility.anthropic_messages) return "anthropic-messages";
+  if (compatibility.openai_responses) return "openai-responses";
+  if (compatibility.gemini_generate_content) return "google-generative-ai";
+  if (compatibility.google_generate_content) return "google-vertex";
+  if (compatibility.bedrock_converse) return "bedrock-converse-stream";
+  return "openai-completions";
+}
+
+export function getBaseUrlForApi(
+  api: Api,
+  gatewayUrl: string,
+  baseUrl: string,
+): string {
+  switch (api) {
+    case "anthropic-messages":
+      return gatewayUrl;
+    case "google-generative-ai":
+      return `${gatewayUrl}/v1beta`;
+    case "google-vertex":
+      return `${gatewayUrl}/v1`;
+    default:
+      return baseUrl;
+  }
+}
+
+export function buildStreamSimple(routeByModelId: Map<string, ModelRoute>) {
+  return (
+    model: Model<Api>,
+    context: Context,
+    options?: SimpleStreamOptions,
+  ): AssistantMessageEventStream => {
+    const route = routeByModelId.get(model.id);
+    const api = route?.api ?? "openai-completions";
+    const provider = getApiProvider(api);
+    if (!provider) {
+      throw new Error(`Unsupported Aperture provider API: ${api}`);
+    }
+
+    return provider.streamSimple({ ...model, api }, context, {
+      ...options,
+      headers: {
+        ...options?.headers,
+        "x-session-id": options?.sessionId ?? "",
+      },
+    });
+  };
+}

package/extensions/aperture/dedicated/model-defaults.ts

@@ -0,0 +1,48 @@
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+
+export interface ApertureModelDefaultsInput {
+  id: string;
+  providerId: string;
+  provider?: {
+    id: string;
+    name?: string;
+  };
+  pricing?: {
+    input?: string;
+    input_cache_read?: string;
+    input_cache_write?: string;
+    output?: string;
+  };
+}
+
+const TOKENS_PER_MILLION = 1_000_000;
+
+function parsePrice(value: string | undefined): number {
+  if (!value) return 0;
+  const n = Number(value);
+  return Number.isFinite(n) ? n * TOKENS_PER_MILLION : 0;
+}
+
+export function buildDefaultModelConfig(
+  model: ApertureModelDefaultsInput,
+): ProviderModelConfig {
+  const id = model.id;
+  const cost = model.pricing
+    ? {
+        input: parsePrice(model.pricing.input),
+        output: parsePrice(model.pricing.output),
+        cacheRead: parsePrice(model.pricing.input_cache_read),
+        cacheWrite: parsePrice(model.pricing.input_cache_write),
+      }
+    : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+  return {
+    id,
+    name: id,
+    reasoning: false,
+    input: ["text"],
+    cost,
+    contextWindow: 128_000,
+    maxTokens: 8_192,
+  };
+}

package/extensions/aperture/dedicated/runtime.ts

@@ -0,0 +1,87 @@
+import type { Api } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ProviderModelConfig,
+} from "@earendil-works/pi-coding-agent";
+import { ApertureClient } from "../../../src/api/client";
+import type { ApertureProvider } from "../../../src/api/types";
+import { resolveGatewayUrl, resolveProviderBaseUrl } from "../../../src/url";
+import { configLoader, type ResolvedConfig } from "../shared/config/loader";
+import {
+  buildStreamSimple,
+  getApiForCompatibility,
+  getBaseUrlForApi,
+} from "./api-routing";
+import { buildDefaultModelConfig } from "./model-defaults";
+
+const PROVIDER_NAME = "aperture";
+const APERTURE_API = "aperture";
+
+const HEADERS = {
+  Referer: "https://pi.dev",
+  "X-Title": "npm:@aliou/pi-ts-aperture",
+};
+
+function filterProviders(
+  providers: ApertureProvider[],
+  config: ResolvedConfig,
+): ApertureProvider[] {
+  const selected = new Set(
+    config.dedicated.providers.filter((p) => p.enabled).map((p) => p.id),
+  );
+  return config.dedicated.providers.length > 0
+    ? providers.filter((provider) => selected.has(provider.id))
+    : providers;
+}
+
+export class DedicatedRuntime {
+  async sync(pi: Pick<ExtensionAPI, "registerProvider">): Promise<void> {
+    const config = configLoader.getConfig();
+    await this.syncConfig(pi, config);
+  }
+
+  async syncConfig(
+    pi: Pick<ExtensionAPI, "registerProvider">,
+    config: ResolvedConfig,
+  ): Promise<void> {
+    if (!config.dedicated.enabled) return;
+
+    const gatewayUrl = resolveGatewayUrl(config);
+    const baseUrl = resolveProviderBaseUrl(config);
+    if (!gatewayUrl || !baseUrl) return;
+
+    const providers = filterProviders(
+      await new ApertureClient(gatewayUrl).providers(),
+      config,
+    );
+    const routeByModelId = new Map<string, { api: Api }>();
+    const models: ProviderModelConfig[] = [];
+
+    for (const provider of providers) {
+      const api = getApiForCompatibility(provider.compatibility);
+      for (const modelId of provider.models) {
+        routeByModelId.set(modelId, { api });
+        models.push({
+          ...buildDefaultModelConfig({
+            id: modelId,
+            providerId: provider.id,
+            provider: { id: provider.id, name: provider.name },
+          }),
+          api: APERTURE_API,
+          baseUrl: getBaseUrlForApi(api, gatewayUrl, baseUrl),
+        });
+      }
+    }
+
+    if (models.length === 0) return;
+
+    pi.registerProvider(PROVIDER_NAME, {
+      baseUrl,
+      apiKey: "-",
+      api: APERTURE_API,
+      headers: HEADERS,
+      models,
+      streamSimple: buildStreamSimple(routeByModelId),
+    });
+  }
+}

package/extensions/aperture/index.ts

@@ -0,0 +1,78 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { DedicatedRuntime } from "./dedicated/runtime";
+import { registerOnboarding } from "./onboarding";
+import { ApertureRuntime } from "./proxy/runtime";
+import { registerApertureSettings } from "./settings-command";
+import { configLoader } from "./shared/config/loader";
+import { emitConfigSync } from "./shared/sync-bus";
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+  await configLoader.load();
+
+  const proxyRuntime = new ApertureRuntime();
+  const dedicatedRuntime = new DedicatedRuntime();
+  let lastProxyProviders = configLoader
+    .getConfig()
+    .proxy.upstreamProviders.map((p) => p.id);
+  let knownModels = [] as ReturnType<
+    ExtensionContext["modelRegistry"]["getAll"]
+  >;
+
+  const updateKnownModels = (ctx: ExtensionContext): void => {
+    knownModels = ctx.modelRegistry.getAll();
+  };
+
+  const onSync = (ctx: ExtensionContext): void => {
+    updateKnownModels(ctx);
+    emitConfigSync();
+    const config = configLoader.getConfig();
+
+    const nextProxyProviders = config.proxy.enabled
+      ? config.proxy.upstreamProviders.map((p) => p.id)
+      : [];
+    for (const provider of proxyRuntime.getProvidersToUnregister(
+      lastProxyProviders,
+      nextProxyProviders,
+    )) {
+      pi.unregisterProvider(provider);
+      ctx.ui.notify(`[aperture] unregistered ${provider}.`, "info");
+    }
+    lastProxyProviders = nextProxyProviders;
+
+    void proxyRuntime
+      .sync({
+        registerProvider: pi.registerProvider.bind(pi),
+        getModels: () => ctx.modelRegistry.getAll(),
+      })
+      .then(() => {
+        const active = ctx.model;
+        if (!active) return;
+        const updated = ctx.modelRegistry.find(active.provider, active.id);
+        if (updated && nextProxyProviders.includes(active.provider)) {
+          void pi.setModel(updated);
+        }
+      });
+
+    void proxyRuntime.checkMissingModels({
+      getModels: () => ctx.modelRegistry.getAll(),
+      notify: (msg, type) => ctx.ui.notify(msg, type),
+    });
+
+    void dedicatedRuntime.sync(pi).catch((error: unknown) => {
+      ctx.ui.notify(
+        `[aperture] dedicated sync failed: ${error instanceof Error ? error.message : String(error)}`,
+        "warning",
+      );
+    });
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    onSync(ctx);
+  });
+
+  registerApertureSettings(pi, onSync, () => knownModels);
+  registerOnboarding(pi);
+}

package/extensions/aperture/onboarding/index.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { configLoader } from "../shared/config/loader";
+import {
+  isOnboardingExtensionEnabled,
+  isOnboardingPending,
+} from "./onboarding";
+import { registerOnboardingCommand } from "./setup-command";
+
+export function registerOnboarding(pi: ExtensionAPI): void {
+  const globalConfig = configLoader.getRawConfig("global");
+  if (!isOnboardingExtensionEnabled(globalConfig)) return;
+
+  pi.on("session_start", (_event, ctx) => {
+    if (isOnboardingPending(configLoader.getRawConfig("global"))) {
+      ctx.ui.notify(
+        "[aperture] extension installed. Run /aperture:onboarding to configure.",
+        "info",
+      );
+    }
+  });
+
+  if (isOnboardingPending(globalConfig)) {
+    registerOnboardingCommand(pi);
+  }
+}