@phi-code-admin/phi-code 0.74.2 → 0.75.0

package/examples/sdk/README.md

@@ -0,0 +1,147 @@
+# SDK Examples
+
+Programmatic usage of pi-coding-agent via `createAgentSession()` and `createAgentSessionRuntime()`.
+
+The runtime example shows how to build a recreate function that closes over process-global fixed inputs and recreates cwd-bound services and sessions as the active session cwd changes.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `01-minimal.ts` | Simplest usage with all defaults |
+| `02-custom-model.ts` | Select model and thinking level |
+| `03-custom-prompt.ts` | Replace or modify system prompt |
+| `04-skills.ts` | Discover, filter, or replace skills |
+| `05-tools.ts` | Built-in tools, custom tools |
+| `06-extensions.ts` | Logging, blocking, result modification |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-slash-commands.ts` | File-based slash commands |
+| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
+| `10-settings.ts` | Override compaction, retry, terminal settings |
+| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
+| `12-full-control.ts` | Replace everything, no discovery |
+| `13-session-runtime.ts` | Manage runtime-backed session replacement |
+
+## Running
+
+```bash
+cd packages/coding-agent
+npx tsx examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@earendil-works/pi-ai";
+import {
+  AuthStorage,
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRegistry,
+  SessionManager,
+  SettingsManager,
+  codingTools,
+  readOnlyTools,
+  readTool, bashTool, editTool, writeTool,
+} from "@earendil-works/pi-coding-agent";
+
+// Auth and models setup
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
+
+// Minimal
+const { session } = await createAgentSession({ authStorage, modelRegistry });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });
+
+// Read-only
+const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry });
+
+// In-memory
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  authStorage,
+  modelRegistry,
+});
+
+// Full control
+const customAuth = AuthStorage.create("/my/app/auth.json");
+customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+const customRegistry = ModelRegistry.create(customAuth);
+
+const resourceLoader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are helpful.",
+  extensionFactories: [myExtension],
+  skillsOverride: () => ({ skills: [], diagnostics: [] }),
+  agentsFilesOverride: () => ({ agentsFiles: [] }),
+  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+});
+await resourceLoader.reload();
+
+const { session } = await createAgentSession({
+  model,
+  authStorage: customAuth,
+  modelRegistry: customRegistry,
+  resourceLoader,
+  tools: [readTool, bashTool],
+  customTools: [{ tool: myTool }],
+  sessionManager: SessionManager.inMemory(),
+  settingsManager: SettingsManager.inMemory(),
+});
+
+// Run prompts
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await session.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `authStorage` | `AuthStorage.create()` | Credential storage |
+| `modelRegistry` | `ModelRegistry.create(authStorage)` | Model registry |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.pi/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `tools` | `codingTools` | Built-in tools |
+| `customTools` | `[]` | Additional tool definitions |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
+
+## Events
+
+```typescript
+session.subscribe((event) => {
+  switch (event.type) {
+    case "message_update":
+      if (event.assistantMessageEvent.type === "text_delta") {
+        process.stdout.write(event.assistantMessageEvent.delta);
+      }
+      break;
+    case "tool_execution_start":
+      console.log(`Tool: ${event.toolName}`);
+      break;
+    case "tool_execution_end":
+      console.log(`Result: ${event.result}`);
+      break;
+    case "agent_end":
+      console.log("Done");
+      break;
+  }
+});
+```

package/extensions/phi/init.ts

@@ -152,6 +152,13 @@ function detectProviders(): DetectedProvider[] {
 			models: ["qwen3.5-plus", "qwen3-max-2026-01-23", "qwen3-coder-plus", "qwen3-coder-next", "kimi-k2.5", "glm-5", "glm-4.7", "MiniMax-M2.5"],
 			available: false,
 		},
+		{
+			name: "OpenCode Go",
+			envVar: "OPENCODE_GO_API_KEY",
+			baseUrl: "https://opencode.ai/zen/go/v1",
+			models: ["kimi-k2.6", "kimi-k2.5", "qwen3-coder", "qwen3-coder-plus", "glm-4.6", "glm-5", "deepseek-v3", "minimax-m2", "MiniMax-M2.5", "moonshotai-kimi-thinking", "z-ai-glm-4.7", "gpt-oss-120b"],
+			available: false,
+		},
 		{
 			name: "OpenAI",
 			envVar: "OPENAI_API_KEY",
@@ -408,8 +415,15 @@ _Edit this file to customize Phi Code's behavior for your project._
 	// ─── Command ─────────────────────────────────────────────────────
 
 	pi.registerCommand("phi-init", {
-		description: "Initialize Phi Code — interactive setup wizard",
+		description: "Initialize Phi Code (legacy alias — prefer /setup for the refined wizard)",
 		handler: async (args, ctx) => {
+			ctx.ui.notify(
+				"NOTE: `/phi-init` is the legacy wizard. The refined replacement is `/setup` " +
+					"(richer flow: Alibaba dual-endpoint, OpenCode Go auto-fetch, ping validation, " +
+					"separate chat/orchestration assignments, hot-reload integration). " +
+					"This legacy command still works for backwards compatibility.",
+				"info",
+			);
 			try {
 				ctx.ui.notify("╔══════════════════════════════════════╗", "info");
 				ctx.ui.notify("║     φ  Phi Code Setup Wizard        ║", "info");

package/extensions/phi/keys.ts

@@ -0,0 +1,186 @@
+/**
+ * Keys Extension - /keys command for managing API keys + file watcher hot-reload.
+ *
+ * Per Q5 strategy C: explicit /keys command AND file watcher on
+ * ~/.phi/agent/models.json + routing.json.
+ *
+ * Subcommands:
+ *   /keys            : list configured providers with masked keys
+ *   /keys set <id> <key>  : set or update a provider key
+ *   /keys remove <id>     : remove a provider key (preserves the rest of config)
+ *   /keys test <id>       : ping the provider API to validate the key
+ *   /keys reload          : force reload from disk (triggers store_reloaded event)
+ *
+ * File watcher (started at session_start) reloads automatically when the
+ * user edits ~/.phi/agent/models.json or routing.json with their text editor.
+ * The smart-router and orchestrator listen for these events to invalidate
+ * their internal caches.
+ *
+ * Security (Q6): keys are stored in plain text in ~/.phi/agent/models.json
+ * with chmod 0600 on Unix. The user is warned in /setup and on `set`.
+ */
+
+import { ApiKeyStore, type ExtensionAPI, getApiKeyStore, getConfigWatcher } from "phi-code";
+
+interface ProviderPingFn {
+	(key: string, timeoutMs?: number): Promise<{ ok: boolean; error?: string }>;
+}
+
+const PROVIDER_PING_REGISTRY: Record<string, ProviderPingFn> = {};
+
+/**
+ * Public helper for other extensions to register a ping function for a provider.
+ * Used by alibaba.ts / opencode-go.ts to expose validation.
+ */
+export function registerProviderPing(providerId: string, ping: ProviderPingFn): void {
+	PROVIDER_PING_REGISTRY[providerId] = ping;
+}
+
+export default function keysExtension(pi: ExtensionAPI) {
+	const store = getApiKeyStore();
+	const watcher = getConfigWatcher();
+
+	pi.registerCommand("keys", {
+		description: "Manage API keys (list / set / remove / test / reload)",
+		handler: async (args, ctx) => {
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const sub = tokens[0]?.toLowerCase() ?? "";
+
+			try {
+				if (sub === "" || sub === "list") {
+					const providers = store.listProviders();
+					if (providers.length === 0) {
+						ctx.ui.notify(
+							"No providers configured. Use `/keys set <provider-id> <key>` or `/setup` to add one.",
+							"info",
+						);
+						return;
+					}
+					let out = `**API Keys (${providers.length} providers)**\n\n`;
+					out += `Storage: \`${store.configPath}\` (chmod 0600 on Unix)\n\n`;
+					for (const id of providers) {
+						const cfg = store.getProvider(id);
+						const masked = ApiKeyStore.maskKey(cfg?.apiKey);
+						const url = cfg?.baseUrl ?? "(no baseUrl)";
+						out += `  **${id}** : \`${masked}\` -> ${url}\n`;
+					}
+					out += `\nCommands: \`/keys set <id> <key>\`, \`/keys remove <id>\`, \`/keys test <id>\`, \`/keys reload\``;
+					ctx.ui.notify(out, "info");
+					return;
+				}
+
+				if (sub === "set") {
+					const id = tokens[1];
+					const key = tokens.slice(2).join(" ");
+					if (!id || !key) {
+						ctx.ui.notify("Usage: `/keys set <provider-id> <api-key>`", "warning");
+						return;
+					}
+					watcher.muteForWrite("models_json_changed");
+					store.setKey(id, key);
+					ctx.ui.notify(
+						`Key set for \`${id}\` (\`${ApiKeyStore.maskKey(key)}\`). Stored in ${store.configPath}.\n` +
+							`Hot-reload will propagate to providers using this key.\n` +
+							`Use \`/keys test ${id}\` to validate.`,
+						"info",
+					);
+					return;
+				}
+
+				if (sub === "remove" || sub === "rm" || sub === "delete") {
+					const id = tokens[1];
+					if (!id) {
+						ctx.ui.notify("Usage: `/keys remove <provider-id>`", "warning");
+						return;
+					}
+					const before = store.getKey(id);
+					if (!before) {
+						ctx.ui.notify(`No key configured for \`${id}\`. Nothing to remove.`, "info");
+						return;
+					}
+					watcher.muteForWrite("models_json_changed");
+					store.removeKey(id);
+					ctx.ui.notify(`Key removed for \`${id}\` (provider config retained).`, "info");
+					return;
+				}
+
+				if (sub === "test") {
+					const id = tokens[1];
+					if (!id) {
+						ctx.ui.notify("Usage: `/keys test <provider-id>`", "warning");
+						return;
+					}
+					const key = store.getKey(id);
+					if (!key) {
+						ctx.ui.notify(`No key configured for \`${id}\`.`, "warning");
+						return;
+					}
+					const ping = PROVIDER_PING_REGISTRY[id];
+					if (!ping) {
+						ctx.ui.notify(
+							`No ping handler registered for \`${id}\`. Built-in pings exist for: ${Object.keys(PROVIDER_PING_REGISTRY).join(", ") || "(none)"}.`,
+							"warning",
+						);
+						return;
+					}
+					ctx.ui.notify(`Pinging \`${id}\`...`, "info");
+					const result = await ping(key);
+					if (result.ok) {
+						ctx.ui.notify(`\`${id}\`: API key valid (200 OK).`, "info");
+					} else {
+						ctx.ui.notify(`\`${id}\`: ${result.error ?? "ping failed"}`, "error");
+					}
+					return;
+				}
+
+				if (sub === "reload") {
+					store.reloadFromDisk();
+					ctx.ui.notify("Reloaded keys from disk. Listeners notified.", "info");
+					return;
+				}
+
+				ctx.ui.notify(
+					"Unknown subcommand. Use: `/keys [list|set|remove|test|reload]`",
+					"warning",
+				);
+			} catch (err) {
+				ctx.ui.notify(`/keys error: ${err instanceof Error ? err.message : String(err)}`, "error");
+			}
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			store.load();
+		} catch {
+			// Empty/missing models.json on first run is normal
+		}
+
+		watcher.start();
+		watcher.on("models_json_changed", () => {
+			try {
+				store.reloadFromDisk();
+				ctx.ui.notify("Detected change in `models.json`. Keys reloaded.", "info");
+			} catch (err) {
+				ctx.ui.notify(`Failed to reload models.json: ${err}`, "warning");
+			}
+		});
+		watcher.on("routing_json_changed", () => {
+			ctx.ui.notify("Detected change in `routing.json`. Smart-router will reload on next input.", "info");
+			pi.events.emit("routing_json_changed", { source: "watcher" });
+		});
+		watcher.on("watcher_error", (data: unknown) => {
+			const d = data as { path: string; error: unknown };
+			ctx.ui.notify(`Config watcher error on ${d.path}: ${d.error}`, "warning");
+		});
+
+		const providers = store.listProviders();
+		if (providers.length > 0) {
+			ctx.ui.notify(
+				`Loaded ${providers.length} provider key(s) from \`~/.phi/agent/models.json\` (chmod 0600). ` +
+					`Use \`/keys\` to list/manage. Editing this file in your editor will hot-reload.`,
+				"info",
+			);
+		}
+	});
+}

package/extensions/phi/providers/alibaba.ts

@@ -0,0 +1,126 @@
+/**
+ * Alibaba Coding Plan Provider - Source of truth for Alibaba config.
+ *
+ * Provides 2 variants:
+ *  - alibaba-codingplan          : OpenAI-compat (/v1) — legacy, works everywhere
+ *  - alibaba-codingplan-anthropic: Anthropic-compat (/apps/anthropic) — ~99.7% prompt cache hit
+ *
+ * Both share ALIBABA_CODING_PLAN_KEY env var (format: sk-sp-xxxxx).
+ *
+ * Models are STATIC versioned (no public listing endpoint).
+ * To refresh: run `npx tsx scripts/refresh-alibaba-models.ts` (Q3 strategy C).
+ *
+ * Rate limits (Pro Plan, $50/month):
+ *  - 6,000 requests / 5-hour sliding window
+ *  - 45,000 requests / week (resets Mon 00:00 UTC+8)
+ *  - 90,000 requests / month (resets on subscription anniversary)
+ */
+
+export const ALIBABA_ENV_VAR = "ALIBABA_CODING_PLAN_KEY";
+export const ALIBABA_API_KEY_PREFIX = "sk-sp-";
+
+export const ALIBABA_PROVIDERS = {
+	openai: {
+		id: "alibaba-codingplan",
+		displayName: "Alibaba Coding Plan (OpenAI-compat)",
+		baseUrl: "https://coding-intl.dashscope.aliyuncs.com/v1",
+		api: "openai-completions" as const,
+	},
+	anthropic: {
+		id: "alibaba-codingplan-anthropic",
+		displayName: "Alibaba Coding Plan (Anthropic-compat, native prompt cache)",
+		baseUrl: "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic",
+		api: "anthropic-messages" as const,
+	},
+} as const;
+
+export interface AlibabaModelSpec {
+	id: string;
+	name: string;
+	contextWindow: number;
+	maxTokens: number;
+	reasoning: boolean;
+}
+
+/**
+ * Bundled Alibaba models. Refresh via `scripts/refresh-alibaba-models.ts`.
+ * Last verified: 2026-05-10.
+ */
+export const ALIBABA_MODELS: readonly AlibabaModelSpec[] = [
+	{ id: "qwen3.5-plus", name: "Qwen 3.5 Plus", contextWindow: 1_000_000, maxTokens: 16_384, reasoning: true },
+	{ id: "qwen3-max-2026-01-23", name: "Qwen 3 Max", contextWindow: 262_144, maxTokens: 16_384, reasoning: true },
+	{ id: "qwen3-coder-plus", name: "Qwen 3 Coder Plus", contextWindow: 1_000_000, maxTokens: 16_384, reasoning: true },
+	{ id: "qwen3-coder-next", name: "Qwen 3 Coder Next", contextWindow: 1_000_000, maxTokens: 16_384, reasoning: true },
+	{ id: "kimi-k2.5", name: "Kimi K2.5", contextWindow: 262_144, maxTokens: 16_384, reasoning: true },
+	{ id: "glm-5", name: "GLM 5", contextWindow: 200_000, maxTokens: 128_000, reasoning: true },
+	{ id: "glm-4.7", name: "GLM 4.7", contextWindow: 200_000, maxTokens: 128_000, reasoning: true },
+	{ id: "MiniMax-M2.5", name: "MiniMax M2.5", contextWindow: 1_000_000, maxTokens: 16_384, reasoning: true },
+] as const;
+
+export const ALIBABA_RATE_LIMITS = {
+	per5Hours: 6_000,
+	perWeek: 45_000,
+	perMonth: 90_000,
+	weekResetUTC: "Mon 00:00 UTC+8",
+	subscriptionType: "Pro Plan ($50/month)",
+} as const;
+
+/**
+ * Validate Alibaba Coding Plan API key format.
+ * Returns null if valid, error message otherwise.
+ */
+export function validateAlibabaApiKey(key: string): string | null {
+	const trimmed = key.trim();
+	if (trimmed.length === 0) return "API key is empty";
+	if (trimmed.length < 10) return "API key too short";
+	if (!trimmed.startsWith(ALIBABA_API_KEY_PREFIX)) {
+		return `API key should start with "${ALIBABA_API_KEY_PREFIX}" (Coding Plan prefix)`;
+	}
+	return null;
+}
+
+/**
+ * Build a models.json provider entry for one variant.
+ * Used by init.ts/setup.ts when user picks Alibaba.
+ */
+export function buildAlibabaProviderConfig(variant: "openai" | "anthropic", apiKey: string) {
+	const provider = ALIBABA_PROVIDERS[variant];
+	const isAnthropic = variant === "anthropic";
+	return {
+		baseUrl: provider.baseUrl,
+		api: provider.api,
+		apiKey,
+		models: ALIBABA_MODELS.map((m) => ({
+			id: m.id,
+			name: isAnthropic ? `${m.name} (Anthropic-compat)` : m.name,
+			reasoning: m.reasoning,
+			input: ["text"] as const,
+			contextWindow: m.contextWindow,
+			maxTokens: m.maxTokens,
+			...(isAnthropic ? { compat: { supportsLongCacheRetention: true } } : {}),
+		})),
+	};
+}
+
+/**
+ * Test an Alibaba API key by hitting /v1/models (lightweight).
+ * Returns true if 200, false otherwise.
+ */
+export async function pingAlibaba(apiKey: string, timeoutMs = 5_000): Promise<{ ok: boolean; error?: string }> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const res = await fetch(`${ALIBABA_PROVIDERS.openai.baseUrl}/models`, {
+			signal: controller.signal,
+			headers: { Authorization: `Bearer ${apiKey}` },
+		});
+		clearTimeout(timeout);
+		if (res.ok) return { ok: true };
+		if (res.status === 401) return { ok: false, error: "Invalid API key (401)" };
+		return { ok: false, error: `HTTP ${res.status}` };
+	} catch (err) {
+		clearTimeout(timeout);
+		const msg = err instanceof Error ? err.message : String(err);
+		return { ok: false, error: msg };
+	}
+}

package/extensions/phi/providers/opencode-go.ts

@@ -0,0 +1,204 @@
+/**
+ * OpenCode Go (zen) Provider - Runtime auto-fetch of available models.
+ *
+ * Per Q4 strategy A:
+ *  - Fetch live list from https://opencode.ai/zen/go/v1/models at runtime
+ *  - Cache TTL 1 hour in memory + refresh background
+ *  - Fallback to bundled static list versioned (last sync date) on network failure
+ *
+ * Authentication is API-key only (no OAuth device code per opencode.ai docs).
+ * Users get key from https://opencode.ai/auth after subscribing to Go ($5 first month).
+ *
+ * Provider id: opencode-go (already a KnownProvider in phi-code-ai).
+ * Endpoints:
+ *  - Models list: https://opencode.ai/zen/go/v1/models
+ *  - OpenAI-compat: https://opencode.ai/zen/go/v1/chat/completions
+ *  - Anthropic-compat: https://opencode.ai/zen/go/v1/messages
+ *
+ * Model IDs follow format: opencode-go/<model-id> (e.g., opencode-go/kimi-k2.6).
+ */
+
+export const OPENCODE_GO_ENV_VAR = "OPENCODE_GO_API_KEY";
+export const OPENCODE_GO_AUTH_URL = "https://opencode.ai/auth";
+export const OPENCODE_GO_MODELS_URL = "https://opencode.ai/zen/go/v1/models";
+export const OPENCODE_GO_OPENAI_URL = "https://opencode.ai/zen/go/v1/chat/completions";
+export const OPENCODE_GO_ANTHROPIC_URL = "https://opencode.ai/zen/go/v1/messages";
+
+export interface OpenCodeGoModel {
+	id: string;
+	name?: string;
+	contextWindow?: number;
+	maxTokens?: number;
+}
+
+interface OpenCodeGoModelsResponse {
+	data?: Array<{
+		id: string;
+		name?: string;
+		context_length?: number;
+		max_tokens?: number;
+		context_window?: number;
+	}>;
+}
+
+/**
+ * Fallback static list of OpenCode Go models.
+ * Last verified: 2026-05-10 (12 models).
+ * Used when network unreachable or auth fails before configuration.
+ */
+export const OPENCODE_GO_FALLBACK_MODELS: readonly OpenCodeGoModel[] = [
+	{ id: "kimi-k2.6", name: "Kimi K2.6", contextWindow: 256_000, maxTokens: 16_384 },
+	{ id: "kimi-k2.5", name: "Kimi K2.5", contextWindow: 256_000, maxTokens: 16_384 },
+	{ id: "qwen3-coder", name: "Qwen 3 Coder", contextWindow: 1_000_000, maxTokens: 16_384 },
+	{ id: "qwen3-coder-plus", name: "Qwen 3 Coder Plus", contextWindow: 1_000_000, maxTokens: 16_384 },
+	{ id: "glm-4.6", name: "GLM 4.6", contextWindow: 200_000, maxTokens: 128_000 },
+	{ id: "glm-5", name: "GLM 5", contextWindow: 200_000, maxTokens: 128_000 },
+	{ id: "deepseek-v3", name: "DeepSeek V3", contextWindow: 128_000, maxTokens: 8_192 },
+	{ id: "minimax-m2", name: "MiniMax M2", contextWindow: 1_000_000, maxTokens: 16_384 },
+	{ id: "MiniMax-M2.5", name: "MiniMax M2.5", contextWindow: 1_000_000, maxTokens: 16_384 },
+	{ id: "moonshotai-kimi-thinking", name: "Kimi Thinking", contextWindow: 256_000, maxTokens: 16_384 },
+	{ id: "z-ai-glm-4.7", name: "Z-AI GLM 4.7", contextWindow: 200_000, maxTokens: 128_000 },
+	{ id: "gpt-oss-120b", name: "GPT-OSS 120B", contextWindow: 128_000, maxTokens: 8_192 },
+] as const;
+
+interface CacheEntry {
+	models: OpenCodeGoModel[];
+	fetchedAt: number;
+}
+
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+let cache: CacheEntry | null = null;
+let inflightFetch: Promise<OpenCodeGoModel[]> | null = null;
+
+function isCacheValid(now: number): boolean {
+	return cache !== null && now - cache.fetchedAt < CACHE_TTL_MS;
+}
+
+async function fetchModelsRaw(apiKey: string | undefined, timeoutMs: number): Promise<OpenCodeGoModel[]> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const headers: Record<string, string> = { Accept: "application/json" };
+		if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+		const res = await fetch(OPENCODE_GO_MODELS_URL, { signal: controller.signal, headers });
+		clearTimeout(timeout);
+		if (!res.ok) {
+			throw new Error(`HTTP ${res.status}`);
+		}
+		const json = (await res.json()) as OpenCodeGoModelsResponse;
+		const data = json.data ?? [];
+		return data.map((m) => ({
+			id: m.id,
+			name: m.name ?? m.id,
+			contextWindow: m.context_length ?? m.context_window,
+			maxTokens: m.max_tokens,
+		}));
+	} catch (err) {
+		clearTimeout(timeout);
+		throw err;
+	}
+}
+
+/**
+ * Get OpenCode Go models. Uses cache (TTL 1h) when fresh,
+ * else fetches live with fallback to static list on failure.
+ */
+export async function getOpenCodeGoModels(options?: {
+	apiKey?: string;
+	forceRefresh?: boolean;
+	timeoutMs?: number;
+}): Promise<{ models: OpenCodeGoModel[]; source: "cache" | "live" | "fallback" }> {
+	const now = Date.now();
+	const force = options?.forceRefresh === true;
+	const timeoutMs = options?.timeoutMs ?? 5_000;
+
+	if (!force && isCacheValid(now)) {
+		return { models: cache!.models, source: "cache" };
+	}
+
+	if (inflightFetch) {
+		try {
+			const models = await inflightFetch;
+			return { models, source: "live" };
+		} catch {
+			// fall through to fresh attempt
+		}
+	}
+
+	inflightFetch = fetchModelsRaw(options?.apiKey, timeoutMs);
+	try {
+		const models = await inflightFetch;
+		cache = { models, fetchedAt: now };
+		return { models, source: "live" };
+	} catch {
+		if (cache) {
+			return { models: cache.models, source: "cache" };
+		}
+		return { models: [...OPENCODE_GO_FALLBACK_MODELS], source: "fallback" };
+	} finally {
+		inflightFetch = null;
+	}
+}
+
+/**
+ * Validate OpenCode Go API key by hitting /models with auth.
+ * No standardized key prefix is documented, so we only check non-empty.
+ */
+export function validateOpenCodeGoApiKey(key: string): string | null {
+	const trimmed = key.trim();
+	if (trimmed.length === 0) return "API key is empty";
+	if (trimmed.length < 10) return "API key too short";
+	return null;
+}
+
+/**
+ * Ping the OpenCode Go API with a given key.
+ */
+export async function pingOpenCodeGo(apiKey: string, timeoutMs = 5_000): Promise<{ ok: boolean; error?: string }> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const res = await fetch(OPENCODE_GO_MODELS_URL, {
+			signal: controller.signal,
+			headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+		});
+		clearTimeout(timeout);
+		if (res.ok) return { ok: true };
+		if (res.status === 401) return { ok: false, error: "Invalid API key (401)" };
+		return { ok: false, error: `HTTP ${res.status}` };
+	} catch (err) {
+		clearTimeout(timeout);
+		const msg = err instanceof Error ? err.message : String(err);
+		return { ok: false, error: msg };
+	}
+}
+
+/**
+ * Build a models.json provider entry from a fetched/fallback model list.
+ * OpenCode Go is a KnownProvider in phi-code-ai, so this is only used
+ * when the user wants to override defaults (e.g., add a new model
+ * not yet in models.generated.ts).
+ */
+export function buildOpenCodeGoProviderConfig(apiKey: string, models: OpenCodeGoModel[]) {
+	return {
+		baseUrl: "https://opencode.ai/zen/go/v1",
+		api: "openai-completions" as const,
+		apiKey,
+		models: models.map((m) => ({
+			id: m.id,
+			name: m.name ?? m.id,
+			reasoning: true,
+			input: ["text"] as const,
+			contextWindow: m.contextWindow ?? 128_000,
+			maxTokens: m.maxTokens ?? 16_384,
+		})),
+	};
+}
+
+/**
+ * Reset the in-memory cache. Useful for tests.
+ */
+export function _resetOpenCodeGoCache(): void {
+	cache = null;
+	inflightFetch = null;
+}