@aliou/pi-ts-aperture 0.6.1 → 0.6.2

package/extensions/aperture/dedicated/models-cache.ts

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { Api } from "@earendil-works/pi-ai";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Stale-while-revalidate disk cache for dedicated Aperture models.
+ *
+ * Dedicated Aperture models are only discoverable by hitting the authenticated
+ * Aperture `/api/providers` endpoint, which we can only do inside
+ * `session_start` / `onSync` (Pi does not expose the gateway to the extension
+ * factory). However, Pi validates scoped models (e.g.
+ * `aperture/<model-id>`) during startup, *before* `session_start` fires. To
+ * avoid "No models match pattern" warnings on saved scoped models, we persist
+ * the last fetch to disk so the provider can be registered with cached models
+ * instantly on the next launch. The first run with no cache still warns once;
+ * subsequent runs resolve cleanly.
+ *
+ * Unlike a plain `ProviderModelConfig[]` cache, dedicated mode uses a custom
+ * `"aperture"` API with a `streamSimple` that routes each request to the
+ * upstream Aperture API (openai-completions, anthropic-messages, ...). That
+ * upstream `api` and per-model `baseUrl` are derived from compatibility at
+ * fetch time and are *not* stored on the model config (model.api is the
+ * `"aperture"` string), so the cache also persists the modelId -> upstream Api
+ * route map. The gateway URL is stored so a stale cache for a different
+ * gateway is ignored until revalidation rewrites it.
+ *
+ * File shape: `{ version: 1, gatewayUrl: string, models: ProviderModelConfig[], routes: Record<string, Api> }`.
+ */
+
+const CACHE_VERSION = 1;
+const CACHE_FILENAME = "aperture-dedicated-models.json";
+
+function cachePath(): string {
+  return join(getAgentDir(), "cache", CACHE_FILENAME);
+}
+
+export interface DedicatedModelsCacheFile {
+  version?: unknown;
+  gatewayUrl?: unknown;
+  models?: unknown;
+  routes?: unknown;
+}
+
+export interface DedicatedModelsCache {
+  gatewayUrl: string;
+  models: ProviderModelConfig[];
+  routes: Record<string, Api>;
+}
+
+/**
+ * Read cached dedicated models synchronously.
+ *
+ * Designed to be called from the provider extension factory body, where Pi
+ * has not entered the event loop yet. Returns `null` if the cache is missing,
+ * unreadable, malformed, or for a different gateway URL.
+ */
+export function loadCachedDedicatedModels(
+  expectedGatewayUrl: string,
+): DedicatedModelsCache | null {
+  try {
+    const path = cachePath();
+    if (!existsSync(path)) return null;
+
+    const parsed: DedicatedModelsCacheFile = JSON.parse(
+      readFileSync(path, "utf8"),
+    );
+    if (parsed.version !== CACHE_VERSION) return null;
+    if (typeof parsed.gatewayUrl !== "string") return null;
+    if (parsed.gatewayUrl !== expectedGatewayUrl) return null;
+    if (!Array.isArray(parsed?.models)) return null;
+    if (
+      parsed.routes === null ||
+      typeof parsed.routes !== "object" ||
+      Array.isArray(parsed.routes)
+    ) {
+      return null;
+    }
+
+    return {
+      gatewayUrl: parsed.gatewayUrl,
+      models: parsed.models as ProviderModelConfig[],
+      routes: parsed.routes as Record<string, Api>,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist dedicated models to disk for the next startup.
+ *
+ * Called after a successful `/api/providers` fetch. Failures are swallowed
+ * since a missing cache only degrades to first-run behavior.
+ */
+export async function writeCachedDedicatedModels(
+  gatewayUrl: string,
+  models: ProviderModelConfig[],
+  routes: Map<string, Api>,
+): Promise<void> {
+  try {
+    const path = cachePath();
+    await mkdir(dirname(path), { recursive: true });
+    const routesRecord: Record<string, Api> = {};
+    for (const [modelId, api] of routes) routesRecord[modelId] = api;
+    await writeFile(
+      path,
+      `${JSON.stringify(
+        { version: CACHE_VERSION, gatewayUrl, models, routes: routesRecord },
+        null,
+        2,
+      )}\n`,
+      "utf8",
+    );
+  } catch {
+    // Cache writes are best-effort. A missing cache only falls back to the
+    // first-run path (next session revalidates and writes again).
+  }
+}

package/extensions/aperture/dedicated/runtime.ts

@@ -13,6 +13,11 @@ import {
   getBaseUrlForApi,
 } from "./api-routing";
 import { buildDefaultModelConfig } from "./model-defaults";
+import {
+  type DedicatedModelsCache,
+  loadCachedDedicatedModels,
+  writeCachedDedicatedModels,
+} from "./models-cache";
 
 const PROVIDER_NAME = "aperture";
 const APERTURE_API = "aperture";
@@ -22,6 +27,11 @@ const HEADERS = {
   "X-Title": "npm:@aliou/pi-ts-aperture",
 };
 
+interface BuiltModels {
+  models: ProviderModelConfig[];
+  routeByModelId: Map<string, { api: Api }>;
+}
+
 function filterProviders(
   providers: ApertureProvider[],
   config: ResolvedConfig,
@@ -34,7 +44,81 @@ function filterProviders(
     : providers;
 }
 
+function buildModels(
+  providers: ApertureProvider[],
+  gatewayUrl: string,
+  baseUrl: string,
+): BuiltModels {
+  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),
+      });
+    }
+  }
+
+  return { models, routeByModelId };
+}
+
+function registerFromBuilt(
+  pi: Pick<ExtensionAPI, "registerProvider">,
+  baseUrl: string,
+  built: BuiltModels,
+): void {
+  if (built.models.length === 0) return;
+  pi.registerProvider(PROVIDER_NAME, {
+    baseUrl,
+    apiKey: "-",
+    api: APERTURE_API,
+    headers: HEADERS,
+    models: built.models,
+    streamSimple: buildStreamSimple(built.routeByModelId),
+  });
+}
+
 export class DedicatedRuntime {
+  /**
+   * Register the aperture provider synchronously from the on-disk cache so Pi
+   * can validate scoped models during startup, before `session_start`
+   * revalidates from the live gateway.
+   *
+   * No-ops when dedicated is disabled, the gateway URL is unset, or there is
+   * no usable cache (first run, or cache for a different gateway URL). The
+   * subsequent revalidation in {@link syncConfig} writes a fresh cache.
+   */
+  registerCached(pi: Pick<ExtensionAPI, "registerProvider">): void {
+    const config = configLoader.getConfig();
+    if (!config.dedicated.enabled) return;
+
+    const gatewayUrl = resolveGatewayUrl(config);
+    const baseUrl = resolveProviderBaseUrl(config);
+    if (!gatewayUrl || !baseUrl) return;
+
+    const cache = loadCachedDedicatedModels(gatewayUrl);
+    if (!cache) return;
+
+    const routeByModelId = new Map<string, { api: Api }>();
+    for (const [modelId, api] of Object.entries(cache.routes)) {
+      routeByModelId.set(modelId, { api });
+    }
+
+    registerFromBuilt(pi, baseUrl, {
+      models: cache.models,
+      routeByModelId,
+    });
+  }
+
   async sync(pi: Pick<ExtensionAPI, "registerProvider">): Promise<void> {
     const config = configLoader.getConfig();
     await this.syncConfig(pi, config);
@@ -54,34 +138,18 @@ export class DedicatedRuntime {
       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),
-        });
-      }
-    }
+    const built = buildModels(providers, gatewayUrl, baseUrl);
 
-    if (models.length === 0) return;
+    registerFromBuilt(pi, baseUrl, built);
 
-    pi.registerProvider(PROVIDER_NAME, {
-      baseUrl,
-      apiKey: "-",
-      api: APERTURE_API,
-      headers: HEADERS,
-      models,
-      streamSimple: buildStreamSimple(routeByModelId),
-    });
+    if (built.models.length > 0) {
+      const routes = new Map<string, Api>();
+      for (const [modelId, route] of built.routeByModelId) {
+        routes.set(modelId, route.api);
+      }
+      await writeCachedDedicatedModels(gatewayUrl, built.models, routes);
+    }
   }
 }
+
+export type { DedicatedModelsCache };

package/extensions/aperture/index.ts

@@ -14,6 +14,18 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 
   const proxyRuntime = new ApertureRuntime();
   const dedicatedRuntime = new DedicatedRuntime();
+
+  // Stale-while-revalidate seed for dedicated Aperture models.
+  //
+  // Dedicated models are only discoverable by hitting the Aperture
+  // `/api/providers` endpoint, which we can do inside `session_start`. Pi
+  // validates scoped models during startup, *before* `session_start` fires,
+  // so we synchronously restore the previous session's fetch from the on-disk
+  // cache so the provider is registered with cached models at load time.
+  // `session_start` then revalidates from the live gateway, writes the cache
+  // back, and re-registers with fresh models. First run with no cache still
+  // warns once until the first revalidation persists a cache.
+  dedicatedRuntime.registerCached(pi);
   let lastProxyProviders = configLoader
     .getConfig()
     .proxy.upstreamProviders.map((p) => p.id);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aliou/pi-ts-aperture",
   "description": "Route Pi LLM providers through Tailscale Aperture",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "license": "MIT",
   "private": false,