opencode2pi 0.0.0-stage → 0.3.1

package/src/discovery.ts

@@ -0,0 +1,260 @@
+/**
+ * Free-model discovery (docs/PLAN.md §T2).
+ *
+ * Three sources, and the ladder is deliberate:
+ *
+ *   S1  GET {zen}/v1/models   — who is actually for sale right now
+ *   S2  models.dev            — what each one costs, and its real capabilities
+ *   S3  static seed           — works with no network at all
+ *
+ * S1 is what keeps dead ids out. Measured 2026-10-05: 36 ids are priced at
+ * zero in models.dev but only 13 of those are live on Zen — intersecting the
+ * two is the difference between a useful list and 23 entries that 400 on first
+ * use. S2 is what makes the judgment trustworthy: it is also the capability
+ * source for T1, so both tiers share one parse.
+ *
+ * Everything runs concurrently and under our own deadline, because the host
+ * kills `fetchDynamicModels` at a hard 15 s
+ * (`RUNTIME_DYNAMIC_MODEL_FETCH_TIMEOUT_MS`) and a rejected fetch leaves the
+ * provider with nothing. Returning the seed on any failure is the whole
+ * contract: discovery must never be able to break the provider.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { ProviderModelConfig } from '@oh-my-pi/pi-coding-agent'
+
+import { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, isFreeModel, normalizeEntry, type ModelsDevEntry } from './metadata.ts'
+import { SEED_MODELS, VERIFIED_FREE } from './seed.ts'
+
+const ZEN_BASE = 'https://opencode.ai/zen/v1'
+const MODELS_DEV_URL = 'https://models.dev/api.json'
+const MODELS_DEV_PROVIDER = 'opencode'
+const ANONYMOUS_KEY = 'public'
+
+/** Per-request deadline. Both run concurrently, so this is the whole budget. */
+const REQUEST_TIMEOUT_MS = 9_000
+/** models.dev changes sub-daily; a day-old cache costs nothing and survives outages. */
+const METADATA_TTL_MS = 24 * 60 * 60 * 1000
+
+interface MetadataCache {
+	readonly fetchedAt: number
+	readonly entries: readonly ModelsDevEntry[]
+}
+
+function cacheFile(): string {
+	return join(tmpdir(), 'opencode2pi', `models-dev-${MODELS_DEV_PROVIDER}.json`)
+}
+
+/** Narrows an arbitrary parsed JSON blob to a models.dev entry, or drops it. */
+function readEntry(raw: unknown): ModelsDevEntry | undefined {
+	if (typeof raw !== 'object' || raw === null) return undefined
+	if (!('id' in raw) || typeof raw.id !== 'string' || raw.id.length === 0) return undefined
+	// The published shape is trusted field-by-field at use time; the container
+	// is the only thing worth checking structurally, because a malformed entry
+	// would otherwise surface as a confusing default-value log line.
+	return raw as ModelsDevEntry
+}
+
+async function readDiskCache(): Promise<MetadataCache | undefined> {
+	try {
+		const parsed: unknown = JSON.parse(await readFile(cacheFile(), 'utf8'))
+		if (typeof parsed !== 'object' || parsed === null) return undefined
+		if (!('entries' in parsed) || !('fetchedAt' in parsed)) return undefined
+		const { entries, fetchedAt } = parsed
+		if (typeof entries !== 'object' || entries === null) return undefined
+		if (typeof fetchedAt !== 'number' || !Number.isFinite(fetchedAt)) return undefined
+
+		const restored: ModelsDevEntry[] = []
+		for (const value of Object.values(entries)) {
+			const entry = readEntry(value)
+			if (entry) restored.push(entry)
+		}
+		return restored.length > 0 ? { entries: restored, fetchedAt } : undefined
+	} catch {
+		return undefined
+	}
+}
+
+async function writeDiskCache(entries: readonly ModelsDevEntry[]): Promise<void> {
+	const cache: MetadataCache = {
+		fetchedAt: Date.now(),
+		entries: [...entries],
+	}
+	try {
+		await mkdir(join(tmpdir(), 'opencode2pi'), { recursive: true })
+		await writeFile(cacheFile(), JSON.stringify(cache), 'utf8')
+	} catch {
+		// A cache we cannot write is a performance loss, never a failure.
+	}
+}
+
+/** Parse the provider slice out of models.dev's whole-catalogue payload. */
+function parseCatalog(payload: unknown): ModelsDevEntry[] {
+	if (typeof payload !== 'object' || payload === null) return []
+	if (!(MODELS_DEV_PROVIDER in payload)) return []
+	const provider = payload[MODELS_DEV_PROVIDER]
+	if (typeof provider !== 'object' || provider === null) return []
+	if (!('models' in provider)) return []
+	const models = provider.models
+	if (typeof models !== 'object' || models === null) return []
+
+	const entries: ModelsDevEntry[] = []
+	for (const value of Object.values(models)) {
+		const entry = readEntry(value)
+		if (entry) entries.push(entry)
+	}
+	return entries
+}
+
+interface MetadataOutcome {
+	readonly entries: readonly ModelsDevEntry[]
+	readonly source: 'network' | 'cache' | 'none'
+	readonly detail?: string
+}
+
+let metadataInflight: Promise<MetadataOutcome> | undefined
+
+/**
+ * Resolve models.dev entries.
+ *
+ * models.dev turns over sub-daily, so a cache younger than the TTL is used
+ * without touching the network at all — that is what keeps the discovery
+ * budget spent on the Zen catalogue, which genuinely has to be live. A stale
+ * cache still beats nothing: last month's capabilities are worth more than
+ * the host's silent 128000/16384 fallback.
+ */
+export function loadMetadata(): Promise<MetadataOutcome> {
+	metadataInflight ??= (async (): Promise<MetadataOutcome> => {
+		const disk = await readDiskCache()
+		if (disk && Date.now() - disk.fetchedAt < METADATA_TTL_MS) {
+			return { entries: disk.entries, source: 'cache', detail: 'fresh' }
+		}
+		try {
+			const response = await fetch(MODELS_DEV_URL, {
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+				headers: { accept: 'application/json' },
+			})
+			if (!response.ok) throw new Error(`HTTP ${response.status}`)
+			const entries = parseCatalog(await response.json())
+			if (entries.length === 0) throw new Error(`no models for provider ${MODELS_DEV_PROVIDER}`)
+			await writeDiskCache(entries)
+			return { entries, source: 'network' }
+		} catch (error) {
+			if (disk) return { entries: disk.entries, source: 'cache', detail: `stale: ${String(error)}` }
+			return { entries: [], source: 'none', detail: String(error) }
+		}
+	})()
+	return metadataInflight
+}
+
+/** Live catalogue straight from Zen: the authority on what exists right now. */
+async function fetchLiveModelIds(): Promise<string[]> {
+	const response = await fetch(`${ZEN_BASE}/models`, {
+		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+		headers: { accept: 'application/json', authorization: `Bearer ${'public'}` },
+	})
+	if (!response.ok) throw new Error(`HTTP ${response.status}`)
+	const payload: unknown = await response.json()
+	if (typeof payload !== 'object' || payload === null) throw new Error('unexpected /models shape')
+	if (!('data' in payload) || !Array.isArray(payload.data)) throw new Error('missing data[]')
+	const ids: string[] = []
+	for (const item of payload.data) {
+		if (typeof item === 'object' && item !== null && 'id' in item && typeof item.id === 'string') {
+			ids.push(item.id)
+		}
+	}
+	return ids
+}
+
+export interface DiscoveryResult {
+	readonly models: readonly ProviderModelConfig[]
+	readonly diagnostics: readonly string[]
+}
+
+/**
+ * Resolve the free lane. Never rejects and never returns an empty list: an
+ * empty or rejected fetch would leave the provider with no models at all.
+ */
+export async function discoverFreeModels(): Promise<DiscoveryResult> {
+	const diagnostics: string[] = []
+
+	const [live, metadata] = await Promise.all([
+		fetchLiveModelIds().catch((error: unknown) => {
+			diagnostics.push(`S1 Zen /models unavailable (${String(error)}) → seed candidates`)
+			return undefined
+		}),
+		loadMetadata(),
+	])
+
+	if (metadata.source === 'network') {
+		diagnostics.push(`S2 models.dev: ${metadata.entries.length} entries (network)`)
+	} else if (metadata.source === 'cache') {
+		diagnostics.push(`S2 models.dev: ${metadata.entries.length} entries (disk cache, ${metadata.detail ?? 'stale'})`)
+	} else {
+		diagnostics.push(`S2 models.dev unavailable (${metadata.detail ?? 'unknown'}) → seed capabilities`)
+	}
+
+	const byId = new Map<string, ModelsDevEntry>()
+	for (const entry of metadata.entries) byId.set(entry.id, entry)
+
+	// S3: the seed is always a candidate, so a Zen outage cannot empty the list.
+	const candidates = live ?? SEED_MODELS.map((model) => model.id)
+	if (live) diagnostics.push(`S1 Zen /models: ${live.length} ids live`)
+
+	const models: ProviderModelConfig[] = []
+	const seen = new Set<string>()
+	for (const id of candidates) {
+		if (seen.has(id)) continue
+		seen.add(id)
+		if (!isFreeModel(id, byId.get(id), VERIFIED_FREE)) continue
+
+		const entry = byId.get(id)
+		if (entry) {
+			const normalized = normalizeEntry(entry)
+			// Capability notes are the whole point of T1: a defaulted field that
+			// nobody logs is the failure mode FINDINGS §7.2 describes.
+			if (normalized.notes.length > 0) diagnostics.push(`${id}: ${normalized.notes.join('; ')}`)
+			const { config } = normalized
+			models.push({
+				...config,
+				name: /free/i.test(config.name) ? config.name : `${config.name} (free)`,
+			})
+			continue
+		}
+
+		// No metadata for this id: the seed carries measured capabilities for the
+		// ids we have actually exercised, so prefer it over guessing.
+		const seed = SEED_MODELS.find((model) => model.id === id)
+		if (seed) {
+			models.push(seed)
+			continue
+		}
+		// Live and free-by-name but entirely unknown (no models.dev entry at
+		// all). Conservative on every capability: no reasoning, text only,
+		// host-generic limits — stated, not silent.
+		diagnostics.push(
+			`${id}: no metadata, free by name → conservative defaults ` +
+				`(${DEFAULT_CONTEXT_WINDOW}/${DEFAULT_MAX_TOKENS}, text only)`,
+		)
+		models.push({
+			id,
+			name: `${id} (free)`,
+			reasoning: false,
+			input: ['text'],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: DEFAULT_CONTEXT_WINDOW,
+			maxTokens: DEFAULT_MAX_TOKENS,
+		})
+	}
+
+	if (models.length === 0) {
+		diagnostics.push('discovery produced no models → seed')
+		return { models: SEED_MODELS, diagnostics }
+	}
+
+	diagnostics.push(`final: ${models.length} free models`)
+	return { models, diagnostics }
+}

package/src/doctor.ts

@@ -0,0 +1,64 @@
+/**
+ * `/opencode2pi doctor` (docs/PLAN.md §T5).
+ *
+ * The shape gate is hardcoded in this extension, and nothing about it is
+ * negotiated: when upstream changes the check, *every* request starts failing
+ * with a bare 403 and no model in particular looks guilty. Upstream has revised
+ * its policy three times in three weeks, so this turns that silent total
+ * failure into one explicit, classified verdict.
+ *
+ * One request, because the gate is global — a second probe would only confirm
+ * what the first already decided.
+ */
+
+import { classifyUpstreamFailure, type UpstreamFailure } from './errors.ts'
+import { GATE_CONDITIONS, sendGateProbe } from './gate.ts'
+
+export interface DoctorReport {
+	readonly ok: boolean
+	readonly kind: UpstreamFailure | 'OK'
+	readonly headline: string
+	readonly detail: string
+	readonly latencyMs: number
+	readonly modelId: string
+}
+
+export async function runDoctor(modelId: string): Promise<DoctorReport> {
+	const probe = await sendGateProbe(modelId)
+
+	if (probe.ok) {
+		return {
+			ok: true,
+			kind: 'OK',
+			modelId,
+			headline: `✅ 闸门正常（${modelId}，${probe.latencyMs}ms）`,
+			detail: '三个必要条件仍然成立，匿名通道可用。',
+			latencyMs: probe.latencyMs,
+		}
+	}
+
+	if (probe.transportError !== undefined) {
+		return {
+			ok: false,
+			kind: 'UPSTREAM',
+			modelId,
+			headline: `无法连接 Zen：${probe.transportError}`,
+			detail: '这是网络或代理问题，不是闸门问题。检查 PI_PROXY / 网络连通性后重试。',
+			latencyMs: probe.latencyMs,
+		}
+	}
+
+	const classification = classifyUpstreamFailure(probe.status, probe.body)
+	const shapeBroken = classification.kind === 'SHAPE_REJECTED'
+
+	return {
+		ok: false,
+		kind: classification.kind,
+		modelId,
+		latencyMs: probe.latencyMs,
+		headline: `${shapeBroken ? '🚨' : '⚠️'} 网关拒绝了这次请求：${classification.summary}`,
+		detail: shapeBroken
+			? `上游很可能改了形状闸门，本扩展的硬编码已过期。本次发送的条件：\n${GATE_CONDITIONS.map((c) => `  - ${c}`).join('\n')}\n请提 issue。原始响应：${probe.body.slice(0, 300)}`
+			: `原始响应（HTTP ${probe.status}）：${probe.body.slice(0, 300)}`,
+	}
+}

package/src/errors.ts

@@ -0,0 +1,95 @@
+/**
+ * Upstream failure classification (docs/PLAN.md §T4).
+ *
+ * Without this the user sees `Error from provider (Console): ...` and has to
+ * guess. On the anonymous lane the difference is not cosmetic: a region block
+ * and a broken shape gate produce *both* a 403, and telling someone their
+ * "API key is invalid" when their network is geo-blocked sends them looking in
+ * exactly the wrong place. opencode2dsh shipped that same bug until 0.3.5.
+ *
+ * So the classifier is ordered by how much the distinction costs when missed:
+ * region and credential are checked before the generic auth verdict, because
+ * both are 403/401 responses that otherwise collapse into "auth problem".
+ */
+
+export type UpstreamFailure =
+	| 'SHAPE_REJECTED'
+	| 'REGION_BLOCKED'
+	| 'MODEL_GONE'
+	| 'RATE_LIMIT'
+	| 'REQUEST_REJECTED'
+	| 'UPSTREAM'
+	| 'AUTH'
+	| 'UNKNOWN'
+
+export interface Classification {
+	readonly kind: UpstreamFailure
+	/** Operator-facing explanation; this replaces the raw provider string. */
+	readonly summary: string
+}
+
+const ADVICE: Readonly<Record<UpstreamFailure, string>> = {
+	SHAPE_REJECTED: '上游形状闸门拒绝（FreeTierError）：通常是本扩展的 bug，请提 issue。闸门需要 Bearer public + 规范 session id + tools 里同时有 bash 和 read。',
+	REGION_BLOCKED: '该模型在当前网络地区不可用（RegionError）：这是地区封锁，不是凭据问题，换一个模型或网络节点。',
+	MODEL_GONE: '模型已下线（ModelError）：上游已不再支持该模型，请查看可用模型列表。',
+	RATE_LIMIT: '匿名配额按出口 IP 限流（429）：等待配额恢复，或设置 PI_PROXY_OPENCODE_ZEN_FREE 换出口（宿主按 provider id 派生命名：opencode-zen-free → OPENCODE_ZEN_FREE）。',
+	REQUEST_REJECTED: '上游拒绝了请求（400）：该模型无法处理这次输入。最常见的是给只支持文本的模型发图片 —— 本扩展按 models.dev 的 modalities 声明放行，换一个支持对应输入的模型即可。',
+	UPSTREAM: '上游暂时不可用（5xx）：稍后重试，或换一个模型。',
+	AUTH: '匿名凭据被拒：本扩展不需要 API key，出现这个说明上游认证方式变了，请提 issue。',
+	UNKNOWN: '未分类的上游错误。',
+}
+
+/**
+ * Classify a failed response.
+ *
+ * `status` is the provider-reported HTTP status, which every provider in the
+ * host populates on the error message. Marker strings are checked first and are
+ * the stronger signal: they name the upstream failure mode outright, and they
+ * survive a change in how the status is surfaced.
+ */
+export function classifyUpstreamFailure(status: number | undefined, message: string): Classification {
+	const text = message.toLowerCase()
+
+	// Region before everything auth-shaped: a geo block is a 403, so any
+	// status-driven auth verdict reached first would mislabel it.
+	if (text.includes('regionerror') || text.includes('not available in your country') || text.includes('geo-block')) {
+		return { kind: 'REGION_BLOCKED', summary: ADVICE.REGION_BLOCKED }
+	}
+	if (text.includes('freetiererror') || text.includes('free tier') || text.includes('missingsessionid')) {
+		return { kind: 'SHAPE_REJECTED', summary: ADVICE.SHAPE_REJECTED }
+	}
+	if (text.includes('modelerror') || text.includes('model is unavailable') || text.includes('not supported')) {
+		return { kind: 'MODEL_GONE', summary: ADVICE.MODEL_GONE }
+	}
+	if (status === 429 || text.includes('rate limit') || text.includes('too many requests')) {
+		return { kind: 'RATE_LIMIT', summary: ADVICE.RATE_LIMIT }
+	}
+	if (status === 401) return { kind: 'AUTH', summary: ADVICE.AUTH }
+	if (status !== undefined && status >= 500) return { kind: 'UPSTREAM', summary: ADVICE.UPSTREAM }
+
+	// An unmarked 403 on this lane is overwhelmingly the shape gate: the
+	// anonymous credential is a fixed literal, so there is no key to have got
+	// wrong. Saying "auth" here would send users hunting for a key they do not
+	// have and never needed.
+	if (status === 403) return { kind: 'SHAPE_REJECTED', summary: ADVICE.SHAPE_REJECTED }
+
+	// A 400 is the model refusing the *content*, not the lane: measured on a
+	// text-only model handed a PNG, it arrives as "400 ... Endpoint is
+	// unavailable." — the same phrase a genuine outage uses. Status decides,
+	// because "retry later" advice for a request that can never succeed sends
+	// the user into a pointless loop.
+	if (status === 400) return { kind: 'REQUEST_REJECTED', summary: ADVICE.REQUEST_REJECTED }
+
+	// Only with no status at all does the free text decide between an outage
+	// and something unrecognized.
+	if (text.includes('endpoint is unavailable') || text.includes('service unavailable') || text.includes('bad gateway')) {
+		return { kind: 'UPSTREAM', summary: ADVICE.UPSTREAM }
+	}
+
+	return { kind: 'UNKNOWN', summary: `${ADVICE.UNKNOWN} ${message}` }
+}
+
+/** Compose the message the host will display for a classified failure. */
+export function formatFailure(modelId: string, classification: Classification): string {
+	return `[opencode2pi/${modelId}] ${classification.summary}`
+}

package/src/filters.ts

@@ -0,0 +1,121 @@
+/**
+ * Which models the roster hides, decided by the user rather than by us.
+ *
+ * Health is annotation by default: a model that failed one probe stays in the
+ * list, because the evidence says verdicts move (docs/FINDINGS.md §8 —
+ * `nemotron-3.ultra-free` answered `401 ModelError` and then `200` a minute
+ * apart). Anything automatic would therefore be wrong half the time, so the rule
+ * set is opt-in and the user picks it in the TUI.
+ *
+ * What is *never* offered is hiding on a quota pause or an unreachable lane:
+ * those are facts about the channel, not about the model, and hiding on them
+ * empties the roster at exactly the moment it is worth having.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { HealthStore, ModelHealth } from './health.ts'
+
+export interface ProbeFilters {
+	/** Hide models the upstream refuses from this egress. */
+	readonly hideRegionBlocked: boolean
+	/** Hide models that failed for a reason attributable to them. */
+	readonly hideFailed: boolean
+}
+
+export const DEFAULT_FILTERS: ProbeFilters = { hideRegionBlocked: false, hideFailed: false }
+
+/**
+ * Verdicts that belong to the model rather than to the lane.
+ *
+ * Keyed on the *displayed* verdict rather than on the failure kind, because that
+ * is what the roster line shows and what the promise has to hold against:
+ * `RATE_LIMIT` and a transport timeout are both 🚧 `limited`, and a 400 or an
+ * unrecognised 5xx is ⚠️ `flaky`. Keying on the verdict makes "配额与链路故障
+ * 永远不隐藏任何模型" true by construction instead of by a list someone can
+ * forget to update.
+ */
+const HIDDEN_VERDICTS: ReadonlySet<ModelHealth> = new Set<ModelHealth>(['dead', 'flaky'])
+
+/** Ids the roster should not advertise under these filters. */
+export function hiddenFromStore(store: HealthStore, filters: ProbeFilters): ReadonlySet<string> {
+	if (!filters.hideFailed && !filters.hideRegionBlocked) return new Set()
+	const hidden = new Set<string>()
+	for (const [id, record] of Object.entries(store)) {
+		if (filters.hideFailed && HIDDEN_VERDICTS.has(record.health)) hidden.add(id)
+		else if (filters.hideRegionBlocked && record.kind === 'REGION_BLOCKED') hidden.add(id)
+	}
+	return hidden
+}
+
+function storeFile(): string {
+	return join(tmpdir(), 'opencode2pi', 'filters.json')
+}
+
+export async function loadFilters(): Promise<ProbeFilters> {
+	try {
+		const parsed: unknown = JSON.parse(await readFile(storeFile(), 'utf8'))
+		if (typeof parsed !== 'object' || parsed === null) return DEFAULT_FILTERS
+		const record = parsed as Partial<ProbeFilters>
+		return {
+			hideRegionBlocked: record.hideRegionBlocked === true,
+			hideFailed: record.hideFailed === true,
+		}
+	} catch {
+		return DEFAULT_FILTERS
+	}
+}
+
+export async function saveFilters(filters: ProbeFilters): Promise<void> {
+	try {
+		await mkdir(join(tmpdir(), 'opencode2pi'), { recursive: true })
+		await writeFile(storeFile(), JSON.stringify(filters), 'utf8')
+	} catch {
+		// An unwritable filter file costs one re-selection, never a wrong roster.
+	}
+}
+
+let activeFilters: ProbeFilters = DEFAULT_FILTERS
+let activeHealth: HealthStore = {}
+let activeHidden: ReadonlySet<string> = new Set()
+
+const listeners: (() => void)[] = []
+
+/** Ids the roster must not advertise right now. */
+export function hidden(): ReadonlySet<string> {
+	return activeHidden
+}
+
+/** Re-derive the hidden set and tell the provider registry when it moved. */
+function republish(): void {
+	const next = hiddenFromStore(activeHealth, activeFilters)
+	if (next.size === activeHidden.size && [...next].every((id) => activeHidden.has(id))) return
+	activeHidden = next
+	for (const listener of listeners) listener()
+}
+
+/**
+ * Adopt the user's choice. The caller has already asked; this only records the
+ * answer and re-derives what it hides.
+ */
+export function publishFilters(filters: ProbeFilters): void {
+	activeFilters = filters
+	republish()
+}
+
+/** Adopt a fresh verdict store, so the hidden set follows every probe. */
+export function publishHealth(store: HealthStore): void {
+	activeHealth = store
+	republish()
+}
+
+/** Called by the provider registration when the roster it advertises changes. */
+export function onHiddenChange(listener: () => void): () => void {
+	listeners.push(listener)
+	return () => {
+		const index = listeners.indexOf(listener)
+		if (index >= 0) listeners.splice(index, 1)
+	}
+}

package/src/gate.ts

@@ -0,0 +1,94 @@
+/**
+ * The gate-shaped request, in one place.
+ *
+ * Both `doctor` and the per-model health probe need to put a minimal
+ * agent-shaped request in front of Zen, and they must send *exactly* the same
+ * bytes: if the two drifted, `doctor` could report a healthy gate that the real
+ * path no longer satisfies, which is the one failure this code exists to catch.
+ *
+ * The shape is not negotiable (docs/FINDINGS.md §2). All three conditions are
+ * load-bearing, and the third has two independent halves — a non-streaming
+ * request is rejected even with both tools present.
+ */
+
+import { canonicalSessionID, sessionHeaders } from './session.ts'
+
+const ZEN_BASE = 'https://opencode.ai/zen/v1'
+const ANONYMOUS_KEY = 'public'
+const GATE_TIMEOUT_MS = 30_000
+
+export interface GateProbe {
+	readonly ok: boolean
+	readonly status: number | undefined
+	readonly body: string
+	readonly latencyMs: number
+	/** Set when the request never produced an HTTP response. */
+	readonly transportError?: string
+}
+
+/** Tool stubs the gate requires; never meant to be called. */
+function gateTools() {
+	const stub = (name: string) => ({
+		type: 'function' as const,
+		function: {
+			name,
+			description: 'Reserved for the host runtime; do not call it.',
+			parameters: { type: 'object', properties: {} },
+		},
+	})
+	return [stub('bash'), stub('read')]
+}
+
+
+/** The three gate conditions, restated so a failing `doctor` is actionable. */
+export const GATE_CONDITIONS: readonly string[] = [
+	'Authorization: Bearer public',
+	'canonical session id  ^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$',
+	'agent-shaped body: stream:true and tools containing bash and read',
+]
+/**
+ * Send one minimal gate-shaped streaming request and report what came back.
+ *
+ * On success the stream is cancelled rather than drained: reaching a 200 *is*
+ * the verdict, and reading a completion would spend tokens to learn nothing new.
+ * The session id is derived per call so repeated probes do not share upstream
+ * cache affinity.
+ */
+export async function sendGateProbe(modelId: string): Promise<GateProbe> {
+	const startedAt = Date.now()
+	const session = canonicalSessionID(`opencode2pi:gate:${modelId}:${startedAt}`)
+
+	let response: Response
+	try {
+		response = await fetch(`${ZEN_BASE}/chat/completions`, {
+			method: 'POST',
+			headers: {
+				'user-agent': 'opencode/1.18.31 (win32 x64; node24.19.0)',
+				'x-opencode-client': 'cli',
+				'x-opencode-project': 'prj_opencode2pi00000000000000',
+				authorization: `Bearer ${ANONYMOUS_KEY}`,
+				'content-type': 'application/json',
+				...sessionHeaders(session),
+			},
+			body: JSON.stringify({
+				model: modelId,
+				stream: true,
+				max_tokens: 16,
+				messages: [{ role: 'user', content: 'Reply with OK.' }],
+				tools: gateTools(),
+			}),
+			signal: AbortSignal.timeout(GATE_TIMEOUT_MS),
+		})
+	} catch (error) {
+		return { ok: false, status: undefined, body: '', latencyMs: Date.now() - startedAt, transportError: String(error) }
+	}
+
+	const latencyMs = Date.now() - startedAt
+	if (response.ok) {
+		await response.body?.cancel()
+		return { ok: true, status: response.status, body: '', latencyMs }
+	}
+
+	const body = await response.text().catch(() => '')
+	return { ok: false, status: response.status, body, latencyMs }
+}