@holysoles/pi-gatewayhelper 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 holysoles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# Pi Gateway Helper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Pi extension for routing virtual models through a private LLM gateway, with optional public-model failover and price synchronization.
+
+<!-- toc -->
+
+- [Install](#install)
+- [Configuration](#configuration)
+- [Verify](#verify)
+
+<!-- tocstop -->
+
+## Install
+
+Install the pinned npm release:
+
+```sh
+pi install npm:@holysoles/pi-gatewayhelper@0.1.0
+```
+
+Remove the same release with:
+
+```sh
+pi remove npm:@holysoles/pi-gatewayhelper@0.1.0
+```
+
+For a local checkout, run `pi install ./gatewayhelper` from the repository root; remove it with `pi remove ./gatewayhelper`.
+
+## Configuration
+
+Add a `privateLlmGateway` section to your global `settings.json` (normally `~/.pi/agent/settings.json`). The extension reads this file at startup; it does not read project settings or apply project overrides. Set `PI_CODING_AGENT_DIR` to use a different agent directory. Replace the example provider and model IDs with providers configured in Pi and IDs appropriate to your setup:
+
+```json
+{
+  "privateLlmGateway": {
+    "models": {
+      "gateway-chat": {
+        "private": { "provider": "my-private-gateway", "id": "internal-chat-v2" },
+        "public": { "provider": "public-provider", "id": "public-chat-latest" }
+      }
+    }
+  }
+}
+```
+
+Each key under `models` registers a selectable virtual model named `fallback/<key>`; in this example, select `/model fallback/gateway-chat`. The mapped private model must be defined in `~/.pi/agent/models.json`. For price synchronization, the mapped public chat model must have pricing in `~/.pi/agent/models-store.json`.
+
+`publicModelFailover` and `priceSync` both default to `true`. With failover enabled, the extension selects the mapped public model if the private model is unavailable or has no configured authentication, and can switch to the public model after a private-model retry failure. Set `publicModelFailover` to `false` to disable this; if the private model is unavailable, there is no fallback route. Set `priceSync` to `false` to disable synchronization. When enabled, at session startup the extension copies the mapped public chat model's prices into the matching private model entries in `models.json`.
+
+Foreground children launched by `pi-subagents` do not inherit the parent's virtual model registrations. Load this extension in those children with `subagents.defaultSubagentOnlyExtensions`, and configure each child model as a mapped `fallback/<key>`. For example, with a checkout at `/home/you/code/pi-packages`:
+
+```json
+{
+  "subagents": {
+    "defaultSubagentOnlyExtensions": [
+      "/home/you/code/pi-packages/gatewayhelper/index.ts"
+    ],
+    "agentOverrides": {
+      "worker": { "model": "fallback/gpt-6-luna" },
+      "reviewer": { "model": "fallback/gpt-6-sol" }
+    }
+  }
+}
+```
+
+Use the absolute entry-point path for your checkout. Both fallback IDs must also be keys in `privateLlmGateway.models`.
+
+Extensions that make direct model calls can import `parsePrivateLlmGatewaySettings` and `resolveFallbackModel` from the package's `./routing` export. Read the same global settings to use the identical mappings and failover policy:
+
+```ts
+import { getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import {
+  parsePrivateLlmGatewaySettings,
+  resolveFallbackModel,
+} from "@holysoles/pi-gatewayhelper/routing";
+
+const globalSettings = SettingsManager.create(ctx.cwd, getAgentDir()).getGlobalSettings();
+const gateway = parsePrivateLlmGatewaySettings(globalSettings);
+if (!gateway) throw new Error("privateLlmGateway settings are missing or invalid");
+const model = resolveFallbackModel(id, ctx, gateway.models, gateway.publicModelFailover);
+return ctx.modelRegistry.complete(model, context, options);
+```
+
+Pass the mapping key as `id`. A registered `fallback/<key>` is a routing alias, not a physical provider model for a direct `modelRegistry.complete()` call; resolve it first and pass `publicModelFailover` so a disabled policy is respected.
+
+## Verify
+
+After installation, select one of your mapped fallback models and confirm its provider/model IDs. Check the session notifications for routing or price-sync results. Run the package's isolated tests on Node 24+ with `npm test` from `gatewayhelper`; this does not start Pi or change your Pi configuration.

package/index.ts

@@ -0,0 +1,298 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+  mkdir,
+  open,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { chooseFallbackRoute, parsePrivateLlmGatewaySettings } from "./routing.mjs";
+
+function getAgentDir() {
+  const configured = process.env.PI_CODING_AGENT_DIR;
+  if (configured === "~") return homedir();
+  if (configured?.startsWith("~/")) return join(homedir(), configured.slice(2));
+  return configured || join(homedir(), ".pi", "agent");
+}
+
+type JsonRecord = Record<string, unknown>;
+type ModelMapping = {
+  private: { provider: string; id: string };
+  public: { provider: string; id: string };
+};
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function getPricedCost(value: unknown): JsonRecord | undefined {
+  if (!isRecord(value)) return undefined;
+  return Object.values(value).some((price) => typeof price === "number" && Number.isFinite(price))
+    ? value
+    : undefined;
+}
+
+function updateMappedCosts(
+  configuration: unknown,
+  catalog: unknown,
+  models: Record<string, ModelMapping>,
+) {
+  const warnings: string[] = [];
+  const changedModels = new Set<string>();
+  if (!isRecord(configuration) || !isRecord(configuration.providers)) {
+    return { changed: false, changedModels: [], warnings: ["models.json has no providers object; pricing was not synchronized."] };
+  }
+  if (!isRecord(catalog)) {
+    return { changed: false, changedModels: [], warnings: ["models-store.json is not a provider catalog; pricing was not synchronized."] };
+  }
+
+  for (const mapping of Object.values(models)) {
+    const privateProvider = configuration.providers[mapping.private.provider];
+    const privateModels = isRecord(privateProvider) && Array.isArray(privateProvider.models)
+      ? privateProvider.models.filter(
+          (model): model is JsonRecord => isRecord(model) && model.id === mapping.private.id,
+        )
+      : [];
+    if (privateModels.length === 0) {
+      warnings.push(`No configured private model found for ${mapping.private.provider}/${mapping.private.id}; its cost was left unchanged.`);
+    }
+
+    const publicProvider = catalog[mapping.public.provider];
+    const publicModels = isRecord(publicProvider) && Array.isArray(publicProvider.models)
+      ? publicProvider.models
+      : [];
+    const publicModel = publicModels.find((model): model is JsonRecord => {
+      return isRecord(model) && model.id === mapping.public.id &&
+        model.type === "chat" && getPricedCost(model.cost) !== undefined;
+    });
+    const publicCost = publicModel && getPricedCost(publicModel.cost);
+    if (!publicCost) {
+      warnings.push(`No priced public chat model found for ${mapping.public.provider}/${mapping.public.id}; ${mapping.private.provider}/${mapping.private.id} was left unchanged.`);
+      continue;
+    }
+
+    for (const privateModel of privateModels) {
+      if (isDeepStrictEqual(privateModel.cost, publicCost)) continue;
+      privateModel.cost = { ...publicCost };
+      changedModels.add(`${mapping.private.provider}/${mapping.private.id}`);
+    }
+  }
+
+  return { changed: changedModels.size > 0, changedModels: [...changedModels], warnings };
+}
+
+function notifyWarnings(ctx: any, warnings: string[]) {
+  for (const warning of warnings) ctx.ui.notify(`Private model price sync: ${warning}`, "warning");
+}
+
+async function acquireModelLock(lockPath: string) {
+  const token = `${process.pid}:${randomUUID()}`;
+  const ownerPath = join(lockPath, "owner");
+  const deadline = Date.now() + 90_000;
+  while (true) {
+    try {
+      await mkdir(lockPath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+
+      let stale = false;
+      try {
+        const [owner, lockStats] = await Promise.all([
+          readFile(ownerPath, "utf8").catch((readError: NodeJS.ErrnoException) => {
+            if (readError.code !== "ENOENT") throw readError;
+            return undefined;
+          }),
+          stat(lockPath),
+        ]);
+        if (owner !== undefined) {
+          const match = /^(\d+):/.exec(owner);
+          if (match) {
+            const pid = Number(match[1]);
+            let processAlive = true;
+            try {
+              process.kill(pid, 0);
+            } catch (processError) {
+              if ((processError as NodeJS.ErrnoException).code === "ESRCH") processAlive = false;
+            }
+            stale = !processAlive;
+          } else {
+            stale = Date.now() - lockStats.mtimeMs > 30_000;
+          }
+        } else {
+          stale = Date.now() - lockStats.mtimeMs > 30_000;
+        }
+      } catch (inspectError) {
+        if ((inspectError as NodeJS.ErrnoException).code !== "ENOENT") throw inspectError;
+      }
+      if (stale) {
+        const stalePath = `${lockPath}.${process.pid}.${randomUUID()}.stale`;
+        try {
+          await rename(lockPath, stalePath);
+          await rm(stalePath, { recursive: true, force: true });
+        } catch (removeError) {
+          if ((removeError as NodeJS.ErrnoException).code !== "ENOENT") throw removeError;
+        }
+        continue;
+      }
+      if (Date.now() >= deadline) throw new Error("Timed out waiting for the models.json price-sync lock");
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      continue;
+    }
+
+    try {
+      await writeFile(ownerPath, token, { flag: "wx" });
+    } catch (error) {
+      await rm(lockPath, { recursive: true, force: true });
+      throw error;
+    }
+
+    return async () => {
+      try {
+        if ((await readFile(ownerPath, "utf8")) === token) {
+          await rm(lockPath, { recursive: true, force: true });
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+    };
+  }
+}
+
+async function readJsonText(path: string) {
+  const text = await readFile(path, "utf8");
+  return { text, value: JSON.parse(text) as unknown };
+}
+
+async function replaceModelsFile(resolvedPath: string, configuration: unknown, expectedSource: string) {
+  // Replacing the resolved target preserves models.json symlinks and its file permissions.
+  const fileStats = await stat(resolvedPath);
+  const mode = fileStats.mode & 0o7777;
+  const temporaryPath = `${resolvedPath}.${process.pid}.${randomUUID()}.tmp`;
+  let renamed = false;
+  try {
+    const handle = await open(temporaryPath, "wx", mode);
+    try {
+      await handle.writeFile(`${JSON.stringify(configuration, null, 2)}\n`, "utf8");
+      await handle.chmod(mode);
+    } finally {
+      await handle.close();
+    }
+    if ((await readFile(resolvedPath, "utf8")) !== expectedSource) return false;
+    await rename(temporaryPath, resolvedPath);
+    renamed = true;
+    return true;
+  } finally {
+    if (!renamed) await rm(temporaryPath, { force: true });
+  }
+}
+
+async function synchronizeMappedPrices(models: Record<string, ModelMapping>, ctx: any) {
+  const agentDir = getAgentDir();
+  const modelsPath = join(agentDir, "models.json");
+  const catalogPath = join(agentDir, "models-store.json");
+  let releaseLock: (() => Promise<void>) | undefined;
+  try {
+    const resolvedModelsPath = await realpath(modelsPath);
+    let source = await readJsonText(resolvedModelsPath);
+    let catalog = await readJsonText(catalogPath);
+    let result = updateMappedCosts(source.value, catalog.value, models);
+    if (!result.changed) {
+      notifyWarnings(ctx, result.warnings);
+      return;
+    }
+
+    // Lock the physical target so all symlink aliases coordinate on the same file.
+    releaseLock = await acquireModelLock(`${resolvedModelsPath}.lock`);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      // Re-read under the lock and again immediately before rename to preserve external edits.
+      source = await readJsonText(resolvedModelsPath);
+      catalog = await readJsonText(catalogPath);
+      result = updateMappedCosts(source.value, catalog.value, models);
+      if (!result.changed) {
+        notifyWarnings(ctx, result.warnings);
+        return;
+      }
+      if (await replaceModelsFile(resolvedModelsPath, source.value, source.text)) {
+        notifyWarnings(ctx, result.warnings);
+        if (releaseLock) {
+          const release = releaseLock;
+          releaseLock = undefined;
+          try {
+            await release();
+          } catch (error) {
+            ctx.ui.notify(`Private model price sync could not release its lock: ${String(error)}`, "warning");
+          }
+        }
+        try {
+          await ctx.modelRegistry.refresh({ allowNetwork: false });
+        } catch (error) {
+          ctx.ui.notify(`Private model price sync: model registry refresh failed: ${String(error)}`, "warning");
+        }
+        ctx.ui.notify(`Synchronized private model pricing for ${result.changedModels.join(", ")}.`, "info");
+        return;
+      }
+    }
+    throw new Error("models.json changed repeatedly during price sync; pricing was not synchronized");
+  } catch (error) {
+    ctx.ui.notify(`Private model price sync failed: ${String(error)}`, "warning");
+  } finally {
+    if (releaseLock) {
+      try {
+        await releaseLock();
+      } catch (error) {
+        ctx.ui.notify(`Private model price sync could not release its lock: ${String(error)}`, "warning");
+      }
+    }
+  }
+}
+
+function readGlobalSettings() {
+  try {
+    return JSON.parse(readFileSync(join(getAgentDir(), "settings.json"), "utf8")) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  const settings = parsePrivateLlmGatewaySettings(readGlobalSettings());
+  if (!settings) return;
+
+  for (const id of Object.keys(settings.models)) {
+    pi.registerVirtualModel<boolean>({
+      provider: "fallback",
+      id,
+      name: id,
+      thinkingLevels: ["off", "minimal", "low", "medium", "high", "xhigh", "max"],
+      route(request, ctx) {
+        const mapping = settings.models[id];
+        const failedPrivate = request.reason === "retry" &&
+          request.failed?.model.provider === mapping.private.provider &&
+          request.failed?.model.id === mapping.private.id;
+        const preferPublic = request.state === true || failedPrivate;
+        const route = chooseFallbackRoute(
+          id,
+          ctx,
+          preferPublic,
+          settings.models,
+          settings.publicModelFailover,
+        );
+        return { ...route, thinkingLevel: request.thinkingLevel };
+      },
+    });
+  }
+
+  if (settings.priceSync && Object.keys(settings.models).length > 0) {
+    pi.on("session_start", async (_event, ctx) => {
+      await synchronizeMappedPrices(settings.models, ctx);
+    });
+  }
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@holysoles/pi-gatewayhelper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "repository": {
+    "url": "https://github.com/holysoles/pi-packages"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.ts",
+    "routing.mjs"
+  ],
+  "exports": {
+    "./routing": "./routing.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/private-llm-gateway.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/routing.mjs

@@ -0,0 +1,66 @@
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isEndpoint(value) {
+  return isRecord(value) &&
+    typeof value.provider === "string" && value.provider.trim().length > 0 &&
+    typeof value.id === "string" && value.id.trim().length > 0;
+}
+
+export function parsePrivateLlmGatewaySettings(settings) {
+  if (!isRecord(settings) || !Object.hasOwn(settings, "privateLlmGateway")) return undefined;
+
+  const section = settings.privateLlmGateway;
+  if (!isRecord(section) || !Object.hasOwn(section, "models")) return undefined;
+  if (!isRecord(section.models)) return undefined;
+  if (section.publicModelFailover !== undefined && typeof section.publicModelFailover !== "boolean") {
+    return undefined;
+  }
+  if (section.priceSync !== undefined && typeof section.priceSync !== "boolean") return undefined;
+
+  const modelEntries = [];
+  for (const [id, mapping] of Object.entries(section.models)) {
+    if (id.trim().length === 0 || !isRecord(mapping) ||
+      !isEndpoint(mapping.private) || !isEndpoint(mapping.public)) {
+      return undefined;
+    }
+    modelEntries.push([id, {
+      private: { provider: mapping.private.provider, id: mapping.private.id },
+      public: { provider: mapping.public.provider, id: mapping.public.id },
+    }]);
+  }
+
+  return {
+    models: Object.fromEntries(modelEntries),
+    publicModelFailover: section.publicModelFailover ?? true,
+    priceSync: section.priceSync ?? true,
+  };
+}
+
+export function chooseFallbackRoute(id, ctx, preferPublic, models, publicModelFailover = true) {
+  const mapping = models?.[id];
+  if (!mapping) throw new Error(`No mapping configured for ${id}`);
+  if (preferPublic && !publicModelFailover) {
+    throw new Error(`Public model failover is disabled for ${id}`);
+  }
+
+  const privateModel = ctx.modelRegistry.find(mapping.private.provider, mapping.private.id);
+  if (!publicModelFailover) {
+    if (!privateModel || !ctx.modelRegistry.hasConfiguredAuth(privateModel)) {
+      throw new Error(`No available model for ${id}`);
+    }
+    return { model: privateModel, state: undefined };
+  }
+
+  const usePublic = preferPublic || !privateModel || !ctx.modelRegistry.hasConfiguredAuth(privateModel);
+  const model = usePublic
+    ? ctx.modelRegistry.find(mapping.public.provider, mapping.public.id)
+    : privateModel;
+  if (!model) throw new Error(`No available model for ${id}`);
+  return { model, state: usePublic || undefined };
+}
+
+export function resolveFallbackModel(id, ctx, models, publicModelFailover = true) {
+  return chooseFallbackRoute(id, ctx, false, models, publicModelFailover).model;
+}