@zeldrisho/pi-opencode-free 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-23
+
+### Added
+
+- Add the OpenCode Free provider for using OpenCode's free-tier models in Pi without an OpenCode installation or API key.
+
+### Changed
+
+- Discover free models through Pi's native OpenCode catalog from pi.dev instead of models.dev, preserving Pi's capabilities and compatibility metadata.
+
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-opencode-free-v0.1.0...HEAD
+[0.1.0]: https://github.com/zeldrisho/pi-packages/releases/tag/pi-opencode-free-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zeldrisho
+
+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,73 @@
-# Temporary Holding Version
+# @zeldrisho/pi-opencode-free
 
-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.
+Use OpenCode's free-tier models in Pi. OpenCode does not need to be installed, and no account or API key is required.
+
+The extension adds an **OpenCode Free** provider that talks directly to OpenCode's OpenAI-compatible inference endpoint. It uses Pi's normal system prompt and tools; it does not launch OpenCode or import OpenCode's prompt.
+
+## Install
+
+```bash
+pi install npm:@zeldrisho/pi-opencode-free
+
+# Project:
+pi install -l npm:@zeldrisho/pi-opencode-free
+```
+
+Restart Pi after installing. Use `pi config` to enable or disable the extension, and `pi list` to see configured packages and their install paths.
+
+## Usage
+
+1. Run `/model`.
+2. Type `opencode-free` to filter the list.
+3. Select a model tagged `[opencode-free]`.
+
+The picker may say "Only showing models from configured providers. Use /login to add providers." You do not need to run `/login`; OpenCode Free is already configured.
+
+The model list is synced from OpenCode and matched against Pi's native OpenCode catalog from [pi.dev](https://pi.dev/models), the same catalog Pi uses for model capabilities and compatibility. Models appear and disappear as OpenCode's free catalog changes. After a successful sync, the catalog is cached for later sessions. If Pi starts without network access or the sync fails, it uses the last synced catalog, or the free models in Pi's bundled OpenCode catalog on a first offline run. If the list looks stale, restart Pi to trigger another sync.
+
+## Troubleshooting
+
+If **OpenCode Free** does not appear in `/model`:
+
+- Confirm the package is installed with `pi list`.
+- Confirm it is enabled with `pi config`.
+- Restart Pi after installing or enabling it.
+
+If the provider appears but no models are listed, check that this machine can reach `https://opencode.ai` and `https://pi.dev`. Discovery needs both; when it cannot run, the extension falls back to the cached catalog or Pi's bundled OpenCode catalog.
+
+## Configuration
+
+| Variable                    | Default                            | Description                                                            |
+| --------------------------- | ---------------------------------- | ---------------------------------------------------------------------- |
+| `OPENCODE_FREE_API_KEY`     | `public`                           | Bearer token sent to the inference endpoint.                           |
+| `OPENCODE_FREE_BASE_URL`    | `https://opencode.ai/inference/v1` | OpenAI-compatible base URL. Point this at a compatible proxy.          |
+| `OPENCODE_API_KEY`          | unset                              | Fallback bearer token when `OPENCODE_FREE_API_KEY` is unset.           |
+| `OPENCODE_FREE_CLI_VERSION` | compatibility version              | Optional client version reported to the endpoint, for example `2.1.3`. |
+
+For example, to route through a local proxy:
+
+```bash
+export OPENCODE_FREE_BASE_URL=http://127.0.0.1:8080/v1
+pi
+```
+
+The proxy must expose an OpenAI-compatible `/chat/completions` endpoint and should return the current free models from `/models`.
+
+## Notes
+
+- Free-tier availability, rate limits, and model names can change at any time.
+- This package is unofficial and is not affiliated with OpenCode.
+- Inference and `/models` requests use the configured base URL. Model catalog discovery always contacts `pi.dev` at a fixed URL, so `OPENCODE_FREE_BASE_URL` does not redirect it. Set `OPENCODE_FREE_BASE_URL` only to a proxy you trust, because that proxy receives your prompts and the bearer token.
+
+## Uninstall
+
+```bash
+pi remove npm:@zeldrisho/pi-opencode-free
+
+# Project:
+pi remove -l npm:@zeldrisho/pi-opencode-free
+```
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@zeldrisho/pi-opencode-free",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Pi provider extension for OpenCode's free-tier models",
+  "keywords": [
+    "opencode",
+    "opencode-free",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/zeldrisho/pi-packages/tree/main/packages/pi-opencode-free#readme",
+  "bugs": {
+    "url": "https://github.com/zeldrisho/pi-packages/issues"
+  },
+  "license": "MIT",
+  "author": "zeldrisho",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zeldrisho/pi-packages.git",
+    "directory": "packages/pi-opencode-free"
+  },
+  "files": [
+    "src",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "vp check",
+    "test": "vp test",
+    "test:watch": "vp test --watch",
+    "lint": "vp lint",
+    "lint:fix": "vp lint --fix",
+    "format": "vp fmt --write",
+    "typecheck": "vp check --no-fmt --no-lint"
+  }
 }

package/src/fingerprint.ts

@@ -0,0 +1,249 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { ProviderHeaders } from "@earendil-works/pi-ai";
+
+/**
+ * Synthetic major-2 client version used when no override is configured.
+ *
+ * The free-tier gate checks the major version, not a specific release, so a
+ * high compatibility version avoids pinning the extension to one OpenCode
+ * release.
+ */
+export const DEFAULT_CLI_VERSION = "2.999.0";
+
+/** Marks requests assembled for the extension's own provider. */
+export const FINGERPRINT_MARKER_HEADER = "x-pi-opencode-free";
+
+const CLI_VERSION_PATTERN = /^\d+\.\d+(?:\.\d+)?$/u;
+
+/** Canonical OpenCode session headers mirrored by the v2 CLI. */
+export const SESSION_HEADER_NAMES = [
+  "x-opencode-session",
+  "x-opencode-session-id",
+  "x-session-affinity",
+  "x-session-id",
+] as const;
+
+const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+const SESSION_PREFIX = "ses_";
+
+const SESSION_MASK_48 = 0xffffffffffffn;
+
+const SESSION_TS_MASK_36 = 0xfffffffffn;
+
+const SESSION_COUNTER = 1n;
+
+const SESSION_HEX_LENGTH = 12;
+
+const SESSION_SUFFIX_LENGTH = 14;
+
+const SESSION_SEED_LENGTH = 20;
+
+/** Largest multiple of the base62 alphabet size that fits in a byte. */
+const BASE62_UNBIASED_LIMIT = BASE62.length * 4;
+
+/**
+ * Renders the base62 suffix without modulo bias.
+ *
+ * Bytes at or above the largest full multiple of the alphabet are rejected so
+ * every digit keeps the same probability. Deterministic hash output supplies
+ * more bytes if the seed runs out after rejections.
+ *
+ * @param seed - At least twenty bytes; the suffix starts at byte six
+ * @returns Exactly fourteen base62 characters
+ */
+function createSessionSuffix(seed: Uint8Array): string {
+  const digits: string[] = [];
+  let bytes: Uint8Array = seed.subarray(6, SESSION_SEED_LENGTH);
+  let counter = 0;
+
+  while (digits.length < SESSION_SUFFIX_LENGTH) {
+    for (const byte of bytes) {
+      if (digits.length === SESSION_SUFFIX_LENGTH) break;
+
+      if (byte >= BASE62_UNBIASED_LIMIT) continue;
+
+      let index = byte;
+
+      while (index >= BASE62.length) index -= BASE62.length;
+      digits.push(BASE62[index] ?? "0");
+    }
+
+    if (digits.length === SESSION_SUFFIX_LENGTH) break;
+
+    counter += 1;
+    bytes = createHash("sha256").update(seed).update(String(counter)).digest();
+  }
+
+  return digits.join("");
+}
+
+/**
+ * Resolves the client version carried by the request fingerprint.
+ *
+ * @param environment - Environment variables visible to the extension
+ * @returns `OPENCODE_FREE_CLI_VERSION` when valid, else the compatibility version
+ */
+export function resolveCliVersion(environment: Record<string, string | undefined>): string {
+  const configured = environment.OPENCODE_FREE_CLI_VERSION?.trim();
+
+  if (configured && CLI_VERSION_PATTERN.test(configured)) return configured;
+
+  return DEFAULT_CLI_VERSION;
+}
+
+/**
+ * Builds the OpenCode v2 CLI user agent for a client version.
+ *
+ * @param cliVersion - Version placed between the `latest` channel and `cli` client
+ * @returns The user agent expected by the free-tier gate
+ */
+export function buildUserAgent(cliVersion: string): string {
+  return `opencode/latest/${cliVersion}/cli`;
+}
+
+/**
+ * Tool declaration required by the free-tier gate. The schema matches the
+ * OpenCode v2 CLI's own `read` tool declaration.
+ */
+export const READ_TOOL = {
+  type: "function",
+  function: {
+    name: "read",
+    description:
+      "Read the contents of a file or directory. Supports text files, images, and PDFs. Images and PDFs are presented directly to the model. Each text line is prefixed by its 1-based line number as <line>: <content>. The prefix is for reference and is not part of the file content. Directory entries are returned one per line. Use offset and limit to read large files or directories in sections. Prefer one larger read over many small slices, and use grep to find specific content in large files.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File or directory to read" },
+        offset: {
+          type: "integer",
+          minimum: 0,
+          description: "The line or directory entry to start reading from (1-based)",
+        },
+        limit: {
+          type: "integer",
+          minimum: 0,
+          description:
+            "The maximum number of lines or directory entries to read (defaults to and capped at 2000)",
+        },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+    strict: false,
+  },
+} as const;
+
+/**
+ * Creates the random seed backing a canonical session id.
+ *
+ * @returns Twenty cryptographically random bytes for a canonical session identifier
+ * @throws If cryptographic random byte generation fails
+ */
+export function createSessionSeed(): Uint8Array {
+  return randomBytes(SESSION_SEED_LENGTH);
+}
+
+/**
+ * Renders OpenCode CLI's canonical session identifier shape.
+ *
+ * The 48-bit hex half reproduces `Identifier.descending()` with the counter
+ * pinned to one, so the low twelve bits always read `ffe`. The high 36 bits are
+ * derived from the seed, matching the reference implementation, while the
+ * fourteen-character suffix is derived from the seed.
+ *
+ * @param seed - At least twenty bytes; defaults to fresh cryptographic randomness
+ * @returns A `ses_` identifier accepted by the free-tier gate
+ * @throws If the seed contains fewer than twenty bytes or default seed generation fails
+ */
+export function createCanonicalSessionId(seed: Uint8Array = createSessionSeed()): string {
+  if (seed.length < SESSION_SEED_LENGTH) {
+    throw new Error(`Session seed must contain at least ${SESSION_SEED_LENGTH} bytes`);
+  }
+
+  const timestampBits =
+    ((BigInt(seed[0] ?? 0) << 28n) |
+      (BigInt(seed[1] ?? 0) << 20n) |
+      (BigInt(seed[2] ?? 0) << 12n) |
+      (BigInt(seed[3] ?? 0) << 4n) |
+      (BigInt(seed[4] ?? 0) >> 4n)) &
+    SESSION_TS_MASK_36;
+
+  const encoded = ~((timestampBits << 12n) | SESSION_COUNTER) & SESSION_MASK_48;
+
+  return `${SESSION_PREFIX}${encoded.toString(16).padStart(SESSION_HEX_LENGTH, "0")}${createSessionSuffix(seed)}`;
+}
+
+/**
+ * Builds the static headers sent with every provider request.
+ *
+ * @param sessionId - Canonical session identifier for the active Pi session
+ * @param cliVersion - Client version carried by the user agent
+ * @returns Provider headers carrying the v2 CLI fingerprint
+ */
+export function buildFingerprintHeaders(sessionId: string, cliVersion: string) {
+  return {
+    "User-Agent": buildUserAgent(cliVersion),
+    "x-opencode-client": "cli",
+    "x-opencode-project": "global",
+    [FINGERPRINT_MARKER_HEADER]: "1",
+    "x-opencode-session": sessionId,
+    "x-opencode-session-id": sessionId,
+    "x-session-affinity": sessionId,
+    "x-session-id": sessionId,
+  } satisfies Record<string, string>;
+}
+
+/**
+ * Updates the active session id on requests assembled for this provider.
+ *
+ * The marker header keeps the mutation from leaking into built-in providers
+ * that share the OpenCode endpoint but do not use the free-tier fingerprint.
+ * Matching header names are replaced case-insensitively, and the legacy
+ * `x-opencode-request` header is removed. Unmarked requests are left unchanged.
+ *
+ * @param headers - Mutable request headers supplied by Pi
+ * @param sessionId - Canonical session identifier for the active Pi session
+ * @param cliVersion - Client version carried by the user agent
+ * @returns Whether the request belonged to this extension
+ */
+export function applyFingerprintHeaders(
+  headers: ProviderHeaders,
+  sessionId: string,
+  cliVersion: string,
+): boolean {
+  if (!hasFingerprintMarker(headers)) return false;
+
+  setHeader(headers, "User-Agent", buildUserAgent(cliVersion));
+  setHeader(headers, "x-opencode-client", "cli");
+  setHeader(headers, "x-opencode-project", "global");
+
+  for (const name of SESSION_HEADER_NAMES) {
+    setHeader(headers, name, sessionId);
+  }
+
+  for (const name of Object.keys(headers)) {
+    if (name.toLowerCase() === "x-opencode-request") delete headers[name];
+  }
+
+  return true;
+}
+
+/** Checks for a case-insensitive marker header whose value is exactly `"1"`. */
+function hasFingerprintMarker(headers: ProviderHeaders): boolean {
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() === FINGERPRINT_MARKER_HEADER && value === "1") return true;
+  }
+
+  return false;
+}
+
+/** Replaces all case variants of a header in place with the supplied spelling and value. */
+function setHeader(headers: ProviderHeaders, name: string, value: string): void {
+  for (const existing of Object.keys(headers)) {
+    if (existing.toLowerCase() === name.toLowerCase()) delete headers[existing];
+  }
+
+  headers[name] = value;
+}

package/src/index.ts

@@ -0,0 +1,148 @@
+import type { RefreshModelsContext } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
+
+import {
+  applyFingerprintHeaders,
+  buildFingerprintHeaders,
+  createCanonicalSessionId,
+  createSessionSeed,
+  resolveCliVersion,
+} from "./fingerprint.ts";
+import {
+  configsFromStoredModels,
+  discoverFreeModels,
+  initialFreeModels,
+  resolveApiKey,
+  resolveBaseUrl,
+  storedModelsFromConfigs,
+  stripTrailingSlashes,
+  type FreeChatModelConfig,
+} from "./models.ts";
+import { isProviderRequestPayload, normalizeFreeRequestPayload } from "./request.ts";
+
+/** Provider id used by `/model` and provider-scoped request handlers. */
+export const PROVIDER_ID = "opencode-free";
+
+const DISCOVERY_TIMEOUT_MS = 8_000;
+
+/** Injectable runtime dependencies used by tests and the default extension export. */
+export interface OpencodeFreeDependencies {
+  randomSeed: () => Uint8Array;
+  fetcher: typeof fetch;
+  environment: Record<string, string | undefined>;
+}
+
+/**
+ * Registers the OpenCode free provider and its request hooks.
+ *
+ * Seeds the catalog from bundled models, rotates session identity on session
+ * start, and normalizes requests for this provider. Discovery runs when Pi
+ * invokes the registered model refresh hook.
+ *
+ * @param pi - Extension API supplied by Pi
+ * @param dependencies - Runtime dependencies for discovery and session generation
+ * @throws If seed generation fails or returns fewer than twenty bytes; Pi API errors propagate
+ */
+export function registerOpencodeFree(
+  pi: ExtensionAPI,
+  dependencies: OpencodeFreeDependencies,
+): void {
+  let sessionId = createCanonicalSessionId(dependencies.randomSeed());
+
+  const baseUrl = resolveBaseUrl(dependencies.environment);
+  const apiKey = resolveApiKey(dependencies.environment);
+  const cliVersion = resolveCliVersion(dependencies.environment);
+
+  pi.on("session_start", () => {
+    sessionId = createCanonicalSessionId(dependencies.randomSeed());
+  });
+
+  pi.on("before_provider_headers", (event) => {
+    applyFingerprintHeaders(event.headers, sessionId, cliVersion);
+  });
+
+  pi.on("before_provider_request", (event, ctx) => {
+    if (ctx.model?.provider !== PROVIDER_ID) return undefined;
+
+    if (!isProviderRequestPayload(event.payload)) return undefined;
+
+    return normalizeFreeRequestPayload(event.payload);
+  });
+
+  const config: ProviderConfig = {
+    name: "OpenCode Free",
+    baseUrl,
+    apiKey,
+    api: "openai-completions",
+    authHeader: true,
+    headers: buildFingerprintHeaders(sessionId, cliVersion),
+    models: initialFreeModels(),
+    refreshModels: async (context) =>
+      refreshModels(context, dependencies, baseUrl, sessionId, cliVersion),
+  };
+
+  pi.registerProvider(PROVIDER_ID, config);
+}
+
+/**
+ * Refreshes the catalog, falling back to stored models or bundled models when
+ * offline, canceled, or discovery returns no usable models. Discovery has an
+ * eight-second abort deadline. Successful results are published for persistence;
+ * publication failures are ignored and the discovered models are still returned.
+ *
+ * @param fallbackBaseUrl - Endpoint used when the refresh context has no override
+ * @throws Propagates model metadata conversion errors from discovery
+ */
+async function refreshModels(
+  context: RefreshModelsContext,
+  dependencies: OpencodeFreeDependencies,
+  fallbackBaseUrl: string,
+  sessionId: string,
+  cliVersion: string,
+): Promise<FreeChatModelConfig[]> {
+  const baseUrl = stripTrailingSlashes(context.baseUrl ?? fallbackBaseUrl);
+  const cachedModels = configsFromStoredModels(context.stored?.models ?? [], PROVIDER_ID);
+  const fallbackModels = cachedModels.length > 0 ? cachedModels : initialFreeModels();
+
+  if (!context.allowNetwork || context.signal.aborted) return fallbackModels;
+
+  const signal = AbortSignal.any([context.signal, AbortSignal.timeout(DISCOVERY_TIMEOUT_MS)]);
+
+  const models = await discoverFreeModels({
+    baseUrl,
+    headers: buildFingerprintHeaders(sessionId, cliVersion),
+    signal,
+    fetcher: dependencies.fetcher,
+    allowNetwork: context.allowNetwork,
+  });
+
+  if (!models || context.signal.aborted) return fallbackModels;
+
+  try {
+    await context.publish({
+      persist: {
+        models: storedModelsFromConfigs(models, PROVIDER_ID, baseUrl),
+        checkedAt: Date.now(),
+      },
+    });
+  } catch {
+    // Keep a valid in-memory catalog even when persistent storage is unavailable.
+  }
+
+  return models;
+}
+
+const defaultDependencies: OpencodeFreeDependencies = {
+  randomSeed: createSessionSeed,
+  fetcher: globalThis.fetch,
+  environment: process.env,
+};
+
+/**
+ * Pi extension entry point. Registers the `opencode-free` provider.
+ *
+ * @param pi - Extension API supplied by Pi
+ */
+export default function piOpencodeFree(pi: ExtensionAPI): void {
+  registerOpencodeFree(pi, defaultDependencies);
+}

package/src/models.ts

@@ -0,0 +1,462 @@
+import { isModelType, type AnyModel, type Api, type Model } from "@earendil-works/pi-ai";
+import {
+  getBuiltinModelDataGeneratedAt,
+  getBuiltinModels,
+} from "@earendil-works/pi-ai/providers/all";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+
+/** Default OpenAI-compatible OpenCode inference endpoint. */
+export const DEFAULT_BASE_URL = "https://opencode.ai/inference/v1";
+
+/** Pi's native OpenCode catalog overlay, as served by pi.dev. */
+export const MODEL_CATALOG_URL = "https://pi.dev/api/models/providers/opencode?types=chat";
+
+const DEFAULT_PUBLIC_API_KEY = "public";
+
+/** Chat model configuration accepted by `ProviderConfig.models`. */
+export type FreeChatModelConfig = Extract<ProviderModelConfig, { reasoning: boolean }>;
+
+interface RemoteCost {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+interface RemoteCatalogEntry {
+  id: string;
+  type?: string;
+  name?: string;
+  api?: string;
+  input?: readonly string[];
+  cost?: RemoteCost;
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning?: boolean;
+  thinkingLevelMap?: FreeChatModelConfig["thinkingLevelMap"];
+  compat?: FreeChatModelConfig["compat"];
+  inputLimits?: FreeChatModelConfig["inputLimits"];
+  promptCache?: FreeChatModelConfig["promptCache"];
+}
+
+interface LiveModel {
+  id?: string;
+}
+
+interface LiveModelsResponse {
+  data?: readonly LiveModel[];
+}
+
+/** Inputs for live free-model discovery. */
+export interface DiscoverFreeModelsOptions {
+  baseUrl: string;
+  headers: Record<string, string>;
+  signal: AbortSignal;
+  fetcher: typeof fetch;
+  allowNetwork: boolean;
+}
+
+/**
+ * Removes trailing slash characters without a backtracking regular expression.
+ *
+ * @param value - URL text to normalize
+ * @returns The value without trailing slashes
+ */
+export function stripTrailingSlashes(value: string): string {
+  let end = value.length;
+
+  while (end > 0 && value.charCodeAt(end - 1) === 0x2f) end -= 1;
+
+  return value.slice(0, end);
+}
+
+/**
+ * Resolves the provider base URL, allowing a local proxy or alternate gateway.
+ *
+ * @param environment - Environment variables visible to the extension
+ * @returns The configured URL without trailing slashes, or the OpenCode default
+ */
+export function resolveBaseUrl(environment: Record<string, string | undefined>): string {
+  const configured = environment.OPENCODE_FREE_BASE_URL?.trim();
+
+  if (!configured) return DEFAULT_BASE_URL;
+
+  return stripTrailingSlashes(configured);
+}
+
+/**
+ * Resolves the bearer token used for inference requests.
+ *
+ * @param environment - Environment variables visible to the extension
+ * @returns `OPENCODE_FREE_API_KEY`, then `OPENCODE_API_KEY`, then `public`
+ */
+export function resolveApiKey(environment: Record<string, string | undefined>): string {
+  const freeKey = environment.OPENCODE_FREE_API_KEY?.trim();
+
+  if (freeKey) return freeKey;
+
+  const openCodeKey = environment.OPENCODE_API_KEY?.trim();
+
+  return openCodeKey || DEFAULT_PUBLIC_API_KEY;
+}
+
+/**
+ * Returns the free chat models in Pi's built-in OpenCode catalog.
+ *
+ * This seeds the provider before the first network refresh. The live catalog
+ * replaces it as soon as discovery succeeds.
+ *
+ * @returns Free chat model configurations from Pi's bundled catalog
+ */
+export function initialFreeModels(): FreeChatModelConfig[] {
+  return [...freeBuiltinModels().values()];
+}
+
+/**
+ * Restores this provider's cached OpenAI-completions chat models from Pi's persisted store.
+ * Model costs are preserved without checking whether they are zero.
+ *
+ * @param models - Models from `RefreshModelsContext.stored`
+ * @param providerId - Provider id that owns the cached catalog
+ * @returns Chat model configurations owned by this provider
+ */
+export function configsFromStoredModels(
+  models: readonly AnyModel[],
+  providerId: string,
+): FreeChatModelConfig[] {
+  const configs: FreeChatModelConfig[] = [];
+
+  for (const model of models) {
+    if (!isModelType(model, "chat")) continue;
+
+    if (model.provider !== providerId) continue;
+
+    if (model.api !== "openai-completions") continue;
+
+    configs.push(fromModel(model));
+  }
+
+  return configs;
+}
+
+/**
+ * Converts provider configurations into the catalog shape Pi persists.
+ *
+ * @param models - Discovered free chat models
+ * @param providerId - Provider id that owns the catalog
+ * @param baseUrl - Current provider base URL
+ * @returns Full chat models suitable for `ModelsStoreEntry.models`
+ */
+export function storedModelsFromConfigs(
+  models: readonly FreeChatModelConfig[],
+  providerId: string,
+  baseUrl: string,
+): Model<"openai-completions">[] {
+  return models.map((config) => {
+    const model: Model<"openai-completions"> = {
+      id: config.id,
+      name: config.name,
+      provider: providerId,
+      api: "openai-completions",
+      baseUrl,
+      input: config.input,
+      cost: config.cost,
+      contextWindow: config.contextWindow,
+      maxTokens: config.maxTokens,
+      reasoning: config.reasoning,
+    };
+
+    if (config.thinkingLevelMap) model.thinkingLevelMap = config.thinkingLevelMap;
+
+    if (config.compat) model.compat = config.compat;
+
+    if (config.inputLimits) model.inputLimits = config.inputLimits;
+
+    if (config.promptCache) model.promptCache = config.promptCache;
+
+    return model;
+  });
+}
+
+/**
+ * Discovers free chat models from the live endpoint and Pi's native catalog.
+ *
+ * The live endpoint decides which models currently exist. Pi's OpenCode
+ * catalog supplies their capabilities and compatibility flags, so this
+ * extension does not maintain a second metadata translation.
+ * A newer remote catalog overlays bundled metadata; otherwise bundled metadata
+ * is used. Both endpoints must respond successfully. Fetch, HTTP, JSON parsing,
+ * and response-shape failures return `undefined`, as do disabled networking,
+ * an already-aborted signal, and an empty intersection.
+ *
+ * @param options - Endpoint, headers, abort signal, and fetcher
+ * @returns Free chat model configurations, or `undefined` when discovery cannot verify them
+ * @throws If model metadata conversion fails, such as for a non-string catalog name
+ */
+export async function discoverFreeModels(
+  options: DiscoverFreeModelsOptions,
+): Promise<FreeChatModelConfig[] | undefined> {
+  if (!options.allowNetwork || options.signal.aborted) return undefined;
+
+  const [liveIds, catalog] = await Promise.all([
+    fetchLiveModelIds(options),
+    fetchModelCatalog(options),
+  ]);
+
+  if (!liveIds || liveIds.length === 0 || !catalog) return undefined;
+
+  const models = selectFreeModels(liveIds, freeCatalogModels(catalog));
+
+  return models.length > 0 ? models : undefined;
+}
+
+/** Indexes bundled OpenAI-completions models with zero input and output costs by model id. */
+function freeBuiltinModels(): Map<string, FreeChatModelConfig> {
+  const models = new Map<string, FreeChatModelConfig>();
+
+  for (const model of getBuiltinModels("opencode")) {
+    if (model.api !== "openai-completions") continue;
+
+    if (model.cost.input !== 0 || model.cost.output !== 0) continue;
+
+    models.set(model.id, fromModel(model));
+  }
+
+  return models;
+}
+
+/** Overlays qualifying remote entries on bundled models; rejected or absent entries leave them intact. */
+function freeCatalogModels(
+  catalog: readonly RemoteCatalogEntry[],
+): Map<string, FreeChatModelConfig> {
+  const models = freeBuiltinModels();
+
+  for (const entry of catalog) {
+    const config = configFromRemote(entry);
+
+    if (config) models.set(config.id, config);
+  }
+
+  return models;
+}
+
+/** Copies model capabilities into a provider configuration, omitting provider and endpoint identity. */
+function fromModel(model: Model<Api>): FreeChatModelConfig {
+  const config: FreeChatModelConfig = {
+    id: model.id,
+    name: model.name,
+    input: model.input,
+    cost: model.cost,
+    contextWindow: model.contextWindow,
+    maxTokens: model.maxTokens,
+    reasoning: model.reasoning,
+  };
+
+  if (model.thinkingLevelMap) config.thinkingLevelMap = model.thinkingLevelMap;
+
+  if (model.compat) config.compat = model.compat;
+
+  if (model.inputLimits) config.inputLimits = model.inputLimits;
+
+  if (model.promptCache) config.promptCache = model.promptCache;
+
+  return config;
+}
+
+/**
+ * Converts a zero-input/output-cost OpenAI-completions chat entry with positive
+ * finite limits, reasoning, and input metadata, or returns `undefined` when those checks fail.
+ * Positive fractional token limits are rounded down; cache costs are preserved.
+ *
+ * @throws If an otherwise qualifying entry has a non-null name that is not a string
+ */
+function configFromRemote(entry: RemoteCatalogEntry): FreeChatModelConfig | undefined {
+  if (entry.type !== undefined && entry.type !== "chat") return undefined;
+
+  if (entry.api !== "openai-completions") return undefined;
+
+  if (entry.cost?.input !== 0 || entry.cost.output !== 0) return undefined;
+
+  if (!isPositiveInteger(entry.contextWindow)) return undefined;
+
+  if (!isPositiveInteger(entry.maxTokens)) return undefined;
+
+  if (entry.reasoning !== true && entry.reasoning !== false) return undefined;
+
+  if (!entry.input || !isStringArray(entry.input)) return undefined;
+
+  const config: FreeChatModelConfig = {
+    id: entry.id,
+    name: entry.name?.trim() || entry.id,
+    input: entry.input.includes("image") ? ["text", "image"] : ["text"],
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: entry.cost.cacheRead ?? 0,
+      cacheWrite: entry.cost.cacheWrite ?? 0,
+    },
+    contextWindow: Math.floor(entry.contextWindow),
+    maxTokens: Math.floor(entry.maxTokens),
+    reasoning: entry.reasoning,
+  };
+
+  if (entry.thinkingLevelMap) config.thinkingLevelMap = entry.thinkingLevelMap;
+
+  if (entry.compat) config.compat = entry.compat;
+
+  if (entry.inputLimits) config.inputLimits = entry.inputLimits;
+
+  if (entry.promptCache) config.promptCache = entry.promptCache;
+
+  return config;
+}
+
+/** Selects live ids with known free metadata, preserving live order and duplicate ids. */
+function selectFreeModels(
+  liveIds: readonly string[],
+  metadata: ReadonlyMap<string, FreeChatModelConfig>,
+): FreeChatModelConfig[] {
+  const models: FreeChatModelConfig[] = [];
+
+  for (const id of liveIds) {
+    const config = metadata.get(id);
+
+    if (!config) continue;
+
+    models.push(config);
+  }
+
+  return models;
+}
+
+/**
+ * Fetches `/models` with the supplied headers and signal, omitting empty ids.
+ * Returns `undefined` on HTTP, fetch, JSON parsing, or response-shape failure,
+ * including an aborted fetch; a valid empty list returns an empty array.
+ */
+async function fetchLiveModelIds(
+  options: DiscoverFreeModelsOptions,
+): Promise<readonly string[] | undefined> {
+  try {
+    const response = await options.fetcher(`${options.baseUrl}/models`, {
+      headers: { ...options.headers, Accept: "application/json" },
+      signal: options.signal,
+    });
+
+    if (!response.ok) return undefined;
+
+    const body: unknown = await response.json();
+
+    if (!isLiveModelsResponse(body)) return undefined;
+
+    const ids: string[] = [];
+
+    for (const model of body.data ?? []) {
+      if (model.id) ids.push(model.id);
+    }
+
+    return ids;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Fetches Pi's OpenCode catalog with the supplied signal and without provider headers.
+ * Returns an empty array when the bundled catalog is at least as recent, or
+ * `undefined` on HTTP, fetch, JSON parsing, or response-shape failure, including abort.
+ */
+async function fetchModelCatalog(
+  options: DiscoverFreeModelsOptions,
+): Promise<readonly RemoteCatalogEntry[] | undefined> {
+  try {
+    const response = await options.fetcher(MODEL_CATALOG_URL, {
+      headers: { Accept: "application/json" },
+      signal: options.signal,
+    });
+
+    if (!response.ok) return undefined;
+
+    const body: unknown = await response.json();
+
+    if (!isRemoteCatalog(body)) return undefined;
+
+    return isCatalogNewer(response.headers.get("last-modified")) ? body : [];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Compares the remote Last-Modified date with the bundled catalog timestamp.
+ * A missing or invalid remote date qualifies only when no bundled timestamp exists.
+ */
+function isCatalogNewer(lastModified: string | null): boolean {
+  const remoteGeneratedAt = Date.parse(lastModified ?? "");
+  const localGeneratedAt = getBuiltinModelDataGeneratedAt();
+
+  if (Number.isNaN(remoteGeneratedAt)) return localGeneratedAt === undefined;
+
+  return localGeneratedAt === undefined || remoteGeneratedAt > localGeneratedAt;
+}
+
+/** Requires a `data` array whose entries all have string ids; an empty array is valid. */
+function isLiveModelsResponse(value: unknown): value is LiveModelsResponse {
+  if (value === null || typeof value !== "object" || !("data" in value)) return false;
+
+  const data = value.data;
+
+  if (!Array.isArray(data)) return false;
+
+  for (const model of data) {
+    if (!isLiveModel(model)) return false;
+  }
+
+  return true;
+}
+
+/** Checks only for a string id, allowing empty ids and leaving other fields unchecked. */
+function isLiveModel(value: unknown): value is LiveModel {
+  if (value === null || typeof value !== "object" || !("id" in value)) return false;
+
+  return typeof value.id === "string";
+}
+
+/** Accepts an empty catalog or entries with string ids; capability fields are not validated here. */
+function isRemoteCatalog(value: unknown): value is readonly RemoteCatalogEntry[] {
+  if (!Array.isArray(value)) return false;
+
+  for (const model of value) {
+    if (!isRemoteCatalogEntry(model)) return false;
+  }
+
+  return true;
+}
+
+/** Checks only for a string id, leaving optional catalog metadata unchecked. */
+function isRemoteCatalogEntry(value: unknown): value is RemoteCatalogEntry {
+  return (
+    value !== null && typeof value === "object" && "id" in value && typeof value.id === "string"
+  );
+}
+
+/** Accepts arrays containing only strings, including empty arrays. */
+function isStringArray(value: unknown): value is readonly string[] {
+  if (!Array.isArray(value)) return false;
+
+  for (const item of value) {
+    if (typeof item !== "string") return false;
+  }
+
+  return true;
+}
+
+/** Excludes NaN and infinities when validating numeric model limits. */
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/** Accepts finite values greater than zero, including fractions that callers round down. */
+function isPositiveInteger(value: unknown): value is number {
+  return isFiniteNumber(value) && value > 0;
+}

package/src/request.ts

@@ -0,0 +1,121 @@
+import { READ_TOOL } from "./fingerprint.ts";
+
+interface ToolFunctionReference {
+  name?: string;
+  description?: string;
+}
+
+interface ToolDeclaration {
+  type?: string;
+  function?: ToolFunctionReference;
+}
+
+interface ToolChoiceObject {
+  type?: string;
+}
+
+/** The subset of an OpenAI chat-completions payload the extension needs to inspect. */
+export interface ProviderRequestPayload {
+  model?: string;
+  stream?: boolean;
+  tools?: readonly ToolDeclaration[];
+  tool_choice?: string | ToolChoiceObject;
+  temperature?: number;
+  max_tokens?: number;
+}
+
+/**
+ * Validates the subset of a provider request payload used for normalization.
+ *
+ * Other payload fields are intentionally ignored and survive reconstruction.
+ *
+ * @param value - Candidate provider request payload
+ * @returns Whether the payload has the shape needed for free-tier normalization
+ */
+export function isProviderRequestPayload(value: unknown): value is ProviderRequestPayload {
+  if (value === null || typeof value !== "object" || !("model" in value)) return false;
+
+  if (typeof value.model !== "string") return false;
+
+  if ("stream" in value && value.stream !== undefined && typeof value.stream !== "boolean") {
+    return false;
+  }
+
+  if ("tools" in value && value.tools !== undefined) {
+    if (!Array.isArray(value.tools)) return false;
+
+    for (const tool of value.tools) {
+      if (!isToolDeclaration(tool)) return false;
+    }
+  }
+
+  if ("tool_choice" in value && value.tool_choice !== undefined) {
+    if (!isToolChoice(value.tool_choice)) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Applies the free-tier request contract to a provider payload.
+ *
+ * The request must stream and must declare a tool named exactly `read`.
+ * Both `tool_choice: "none"` and `tool_choice: { type: "none" }` are removed
+ * because the gate rejects them, while every other field and tool declaration
+ * is preserved. The original payload is not mutated.
+ *
+ * @param payload - Validated provider request payload
+ * @returns A normalized copy suitable for the free-tier endpoint
+ */
+export function normalizeFreeRequestPayload(
+  payload: ProviderRequestPayload,
+): ProviderRequestPayload {
+  const tools = appendReadTool(payload.tools);
+
+  const normalized: ProviderRequestPayload = {
+    ...payload,
+    stream: true,
+  };
+
+  if (tools !== payload.tools) normalized.tools = tools;
+
+  if (isNoneToolChoice(payload.tool_choice)) delete normalized.tool_choice;
+
+  return normalized;
+}
+
+/** Reuses tools containing an exact `read` name, or returns a new list with the default appended. */
+function appendReadTool(tools: readonly ToolDeclaration[] | undefined): readonly ToolDeclaration[] {
+  if (!tools) return [READ_TOOL];
+
+  for (const tool of tools) {
+    if (tool.function?.name === "read") return tools;
+  }
+
+  return [...tools, READ_TOOL];
+}
+
+/** Recognizes both the string and object forms of the rejected `none` tool choice. */
+function isNoneToolChoice(value: unknown): value is "none" | ToolChoiceObject {
+  if (value === "none") return true;
+
+  return value !== null && typeof value === "object" && "type" in value && value.type === "none";
+}
+
+/** Accepts any string or non-null object without validating a particular tool-choice schema. */
+function isToolChoice(value: unknown): value is string | ToolChoiceObject {
+  if (typeof value === "string") return true;
+
+  return value !== null && typeof value === "object";
+}
+
+/** Requires a function object with a string name; other declaration fields are not validated. */
+function isToolDeclaration(value: unknown): value is ToolDeclaration {
+  if (value === null || typeof value !== "object" || !("function" in value)) return false;
+
+  const fn = value.function;
+
+  if (fn === null || typeof fn !== "object" || !("name" in fn)) return false;
+
+  return typeof fn.name === "string";
+}