pi-sub2api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pacoyang
+
+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

@@ -0,0 +1,80 @@
+# pi-sub2api
+
+A [pi](https://pi.dev) extension for a [sub2api](https://github.com/Wei-Shaw/sub2api) gateway.
+
+- Fetches the model list from the gateway at startup and registers it as the `sub2api` provider.
+- Adds a `/usage` command showing balance and today/total cost.
+
+## Install
+
+```bash
+pi install npm:pi-sub2api
+```
+
+Or try it for a single run without installing:
+
+```bash
+pi -e npm:pi-sub2api
+```
+
+## Configure
+
+All configuration lives in `~/.pi/agent/auth.json` under the provider name `sub2api`. No shell
+environment variables are needed.
+
+```json
+{
+  "sub2api": {
+    "type": "api_key",
+    "key": "sk-...",
+    "env": { "SUB2API_BASE_URL": "https://your-sub2api-host" }
+  }
+}
+```
+
+```bash
+chmod 600 ~/.pi/agent/auth.json
+```
+
+- `key` — an API key generated in the sub2api dashboard.
+- `env.SUB2API_BASE_URL` — the gateway base URL, **without** a trailing `/v1`. Defaults to
+  `http://localhost:8080`.
+
+pi resolves the key from `auth.json["sub2api"]` for inference; the extension reads the same entry
+for its own `/v1/models` and `/v1/usage` calls. `SUB2API_KEY` / `SUB2API_BASE_URL` environment
+variables are used as a fallback if the `auth.json` entry is absent.
+
+## Use
+
+```bash
+pi --list-models                                  # models appear under the sub2api provider
+pi --provider sub2api --model gpt-5.5
+```
+
+In an interactive session, `/usage` prints balance and cost:
+
+```
+sub2api usage
+  balance  -67.01 USD
+  today    $0.27 · 9 req · 57,826 tok
+  total    $184.21 · 5,965 req · 105,534,943 tok
+  top models (by cost)
+    gpt-5.5  $0.27 · 52,300 tok · 4 req
+```
+
+## Notes
+
+- **API type**: the provider is registered with `openai-completions`. `openai-responses` and
+  `openai-codex-responses` did not work against this gateway.
+- **Cost**: pi's per-token `cost` is set to `0`, because sub2api's `/v1/models` returns no pricing.
+  Cost comes from the gateway's own accounting via `/usage`, not from pi's estimate.
+- **Model list**: embedding and image-generation models are filtered out; only chat-capable models
+  are registered.
+- **Thinking levels**: reasoning models expose `off/low/medium/high/xhigh`. `minimal` is marked
+  unsupported because the upstream rejects `reasoning_effort: "minimal"`.
+- **Model metadata**: `contextWindow` and `maxTokens` are set to 400000/128000 for every model,
+  since the gateway's model list does not report per-model limits.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "pi-sub2api",
+  "version": "0.1.0",
+  "description": "Pi extension for a sub2api gateway: dynamic model registration and a /usage command for balance and cost.",
+  "type": "module",
+  "license": "MIT",
+  "author": "pacoyang <yangbaigao@gmail.com>",
+  "homepage": "https://github.com/pacoyang/pi-sub2api#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pacoyang/pi-sub2api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pacoyang/pi-sub2api/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "sub2api"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,166 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * pi extension for a sub2api gateway.
+ *
+ * - Fetches the model list from GET {BASE}/v1/models and registers them as the
+ *   "sub2api" provider (openai-completions).
+ * - Registers a /usage command backed by GET {BASE}/v1/usage (balance and cost).
+ *
+ * Configuration lives entirely in ~/.pi/agent/auth.json under the provider name
+ * "sub2api" (no shell env exports needed):
+ *
+ *   {
+ *     "sub2api": {
+ *       "type": "api_key",
+ *       "key": "sk-...",
+ *       "env": { "SUB2API_BASE_URL": "https://your-sub2api-host" }
+ *     }
+ *   }
+ *
+ * pi resolves the key from auth.json["sub2api"] for inference; this extension reads
+ * the same entry for its own /v1/models and /v1/usage calls.
+ *
+ * Note: only openai-completions works against this gateway; openai-responses and
+ * openai-codex-responses did not.
+ */
+
+const DEFAULT_BASE = "http://localhost:8080";
+
+function agentDir(): string {
+  const override = process.env.PI_CODING_AGENT_DIR;
+  return override ? override.replace(/^~(?=$|\/)/, homedir()) : join(homedir(), ".pi", "agent");
+}
+
+/** Resolve a stored value: literal, or $ENV_VAR interpolation. */
+function resolveValue(raw: string | undefined, scopedEnv?: Record<string, string>): string {
+  if (!raw) return "";
+  const m = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/.exec(raw);
+  if (m) return scopedEnv?.[m[1]] ?? process.env[m[1]] ?? "";
+  return raw;
+}
+
+function readSub2apiCredential(): { key: string; base: string } {
+  try {
+    const authPath = join(agentDir(), "auth.json");
+    const data = JSON.parse(readFileSync(authPath, "utf-8")) as Record<
+      string,
+      { type?: string; key?: string; env?: Record<string, string> }
+    >;
+    const cred = data.sub2api;
+    if (cred?.type === "api_key") {
+      return {
+        key: resolveValue(cred.key, cred.env),
+        base: (resolveValue(cred.env?.SUB2API_BASE_URL, cred.env) || DEFAULT_BASE).replace(/\/+$/, ""),
+      };
+    }
+  } catch {
+    // auth.json missing or unparseable; fall through to env/default.
+  }
+  return {
+    key: process.env.SUB2API_KEY ?? "",
+    base: (process.env.SUB2API_BASE_URL ?? DEFAULT_BASE).replace(/\/+$/, ""),
+  };
+}
+
+async function fetchJson(url: string, key: string, timeoutMs = 8000): Promise<any> {
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${key}`, Accept: "application/json" },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+}
+
+// Render the GET /v1/usage response as a compact multi-line report.
+function formatUsage(data: any): string {
+  const lines = ["sub2api usage"];
+  const row = (label: string, rest: string) => lines.push(`  ${label.padEnd(7)}  ${rest}`);
+  const num = (v: unknown) => Number(v ?? 0);
+  if (data?.balance != null) {
+    row("balance", `${num(data.balance).toFixed(2)}${data.unit ? ` ${data.unit}` : ""}`);
+  }
+  const bucket = (label: string, b: any) => {
+    if (b) {
+      row(label, `$${num(b.cost).toFixed(2)} · ${num(b.requests).toLocaleString()} req · ${num(b.total_tokens).toLocaleString()} tok`);
+    }
+  };
+  bucket("today", data?.usage?.today);
+  bucket("total", data?.usage?.total);
+  const stats: any[] = Array.isArray(data?.model_stats) ? data.model_stats : [];
+  if (stats.length) {
+    lines.push("  top models (by cost)");
+    for (const s of [...stats].sort((a, b) => num(b.cost) - num(a.cost)).slice(0, 3)) {
+      lines.push(`    ${s.model}  $${num(s.cost).toFixed(2)} · ${num(s.total_tokens).toLocaleString()} tok · ${num(s.requests).toLocaleString()} req`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export default async function (pi: ExtensionAPI) {
+  const { key, base } = readSub2apiCredential();
+
+  // Codex / gpt-5 / o-series are reasoning models; infer the flag from the id.
+  const isReasoning = (id: string) => /gpt-5|codex|^o[1-9]|reason|think/i.test(id);
+
+  let models: Array<{ id: string }> = [];
+  try {
+    const json = await fetchJson(`${base}/v1/models`, key);
+    // Keep chat-capable models only; drop embeddings and image-generation models.
+    models = ((json?.data as Array<{ id: string }>) ?? []).filter((m) => !/embedding|image/i.test(m.id));
+  } catch (err) {
+    console.warn(`[sub2api] models fetch failed: ${(err as Error).message}`);
+  }
+
+  if (models.length === 0) {
+    // Nothing fetched: skip registration to avoid an empty provider.
+    // Check the "sub2api" entry in ~/.pi/agent/auth.json and that the service is running.
+    console.warn("[sub2api] no models returned, skipping registration.");
+    return;
+  }
+
+  // apiKey is required by registerProvider whenever models are defined (presence is
+  // validated; auth.json is not consulted here), so pass the key read from auth.json.
+  // At request time pi still resolves auth.json["sub2api"] first.
+  pi.registerProvider("sub2api", {
+    name: "Sub2API",
+    baseUrl: `${base}/v1`,
+    api: "openai-completions",
+    apiKey: key,
+    models: models.map((m) => ({
+      id: m.id,
+      name: m.id,
+      reasoning: isReasoning(m.id),
+      // Upstream rejects reasoning_effort "minimal" (supported: none/low/medium/high/xhigh),
+      // so mark that level unsupported; pi hides it and clamps a request up to "low".
+      thinkingLevelMap: isReasoning(m.id) ? { minimal: null } : undefined,
+      input: ["text", "image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 400000,
+      maxTokens: 128000,
+    })),
+  });
+
+  console.log(`[sub2api] registered ${models.length} model(s): ${models.map((m) => m.id).join(", ")}`);
+
+  // /usage: sub2api tracks authoritative cost/balance at GET /v1/usage (same key).
+  pi.registerCommand("usage", {
+    description: "Show sub2api balance and today/total cost",
+    handler: async (_args, ctx) => {
+      if (!key) {
+        ctx.ui.notify("sub2api: no API key in auth.json", "error");
+        return;
+      }
+      ctx.ui.notify("Fetching sub2api usage…", "info");
+      try {
+        const data = await fetchJson(`${base}/v1/usage`, key);
+        ctx.ui.notify(formatUsage(data), "info");
+      } catch (e) {
+        ctx.ui.notify(`sub2api: usage unavailable — ${(e as Error).message}`, "warning");
+      }
+    },
+  });
+}