opencode2pi 0.0.0-stage → 0.3.1

package/src/metadata.ts

@@ -0,0 +1,198 @@
+/**
+ * Capability metadata for the free lane (docs/PLAN.md §T1), sourced from
+ * models.dev.
+ *
+ * Why this file exists at all: a provider that under-reports capabilities does
+ * not fail loudly. It fails by *quietly truncating* — the host falls back to a
+ * generic 128000/16384 and the request dies somewhere deep in a long context
+ * with nothing pointing at the real cause (docs/FINDINGS.md §7.2). So every
+ * value this module emits is either measured or explicitly defaulted *here*,
+ * and each default carries a reason string that reaches the log.
+ *
+ * The mapping is deliberately flat. The host adopts `contextWindow`,
+ * `maxTokens`, `cost`, `input`, `reasoning` and `thinking` verbatim and
+ * silently ignores a nested `limits: {context, output}` (docs/FINDINGS.md
+ * §7.1/§7.2), so models.dev's `limit.context` / `limit.output` must be renamed
+ * on the way through rather than passed through.
+ */
+
+import type { Effort } from '@earendil-works/pi-ai'
+import type { ProviderModelConfig } from '@oh-my-pi/pi-coding-agent'
+
+import { UNAVAILABLE } from './seed.ts'
+
+/**
+ * Fallbacks used only when models.dev has nothing usable for a field. These
+ * mirror the host's generic values on purpose: matching them keeps behaviour
+ * identical to today, while emitting them explicitly (with a logged reason)
+ * removes the silent part.
+
+ */
+export const DEFAULT_CONTEXT_WINDOW = 128_000
+export const DEFAULT_MAX_TOKENS = 16_384
+
+/** Effort levels the host accepts; anything else is dropped rather than forwarded. */
+const KNOWN_EFFORTS: ReadonlySet<string> = new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+
+function isEffort(value: unknown): value is Effort {
+	return typeof value === 'string' && KNOWN_EFFORTS.has(value)
+}
+
+/**
+ * A models.dev entry, read defensively: this is third-party JSON, so every
+ * field is `unknown` until proven otherwise.
+ */
+export interface ModelsDevEntry {
+	readonly id: string
+	readonly name?: string
+	readonly limit?: { readonly context?: unknown; readonly output?: unknown }
+	readonly cost?: { readonly input?: unknown; readonly output?: unknown; readonly cache_read?: unknown; readonly cache_write?: unknown }
+	readonly modalities?: { readonly input?: unknown }
+	readonly reasoning?: unknown
+	readonly reasoning_options?: unknown
+	readonly deprecated?: unknown
+}
+
+/** Reads a token limit, falling back to `fallback` and recording why. */
+function readLimit(raw: unknown, label: string, fallback: number, notes: string[]): number {
+	if (typeof raw !== 'number' || !Number.isInteger(raw) || raw <= 0) {
+		notes.push(`${label} missing or invalid → ${fallback}`)
+		return fallback
+	}
+	return raw
+}
+
+/** Reads a price component, falling back to free (0) and recording why. */
+function readCost(raw: unknown, label: string, notes: string[]): number {
+	if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) {
+		notes.push(`${label} missing or invalid → 0`)
+		return 0
+	}
+	return raw
+}
+
+/** Text + image are the only input kinds the host models; audio/video are dropped. */
+function inputModalities(entry: ModelsDevEntry, notes: string[]): ('text' | 'image')[] {
+	const raw = entry.modalities?.input
+	if (!Array.isArray(raw)) {
+		notes.push('modalities.input missing or invalid → text')
+		return ['text']
+	}
+	const declared = raw.filter((value): value is 'text' | 'image' => value === 'text' || value === 'image')
+	const unsupported = raw.filter(
+		(value) => typeof value === 'string' && value !== 'text' && value !== 'image',
+	)
+	if (unsupported.length > 0) notes.push(`input modalities not host-modellable, dropped: ${unsupported.join(', ')}`)
+	if (declared.includes('text')) return declared
+	notes.push('modalities.input declares no text → forcing text')
+	return ['text', ...declared]
+}
+
+/**
+ * Effort control surface. models.dev expresses this as a list of option
+ * objects; only `{type: 'effort', values: [...]}` maps onto the host's
+ * `thinking.efforts`. A `toggle` model has no effort axis, so it gets
+ * `thinking: undefined` and the host derives its default four levels from
+ * `reasoning: true` — which is exactly what an empty efforts list must NOT do,
+ * since the host contract requires efforts to be non-empty.
+ */
+function thinkingConfig(entry: ModelsDevEntry, reasoning: boolean): ProviderModelConfig['thinking'] {
+	if (!reasoning || !Array.isArray(entry.reasoning_options)) return undefined
+
+	const efforts: Effort[] = []
+	for (const option of entry.reasoning_options) {
+		if (typeof option !== 'object' || option === null) continue
+		if (!('type' in option) || option.type !== 'effort') continue
+		if (!('values' in option) || !Array.isArray(option.values)) continue
+		for (const value of option.values) {
+			if (isEffort(value) && !efforts.includes(value)) efforts.push(value)
+		}
+	}
+	if (efforts.length === 0) return undefined
+	return { mode: 'effort', efforts }
+}
+
+export interface NormalizedModel {
+	readonly config: ProviderModelConfig
+	/** Reasons any field fell back to a default. Empty when the entry was complete. */
+	readonly notes: readonly string[]
+}
+
+/**
+ * Project one models.dev entry onto the host's model config contract.
+ *
+ * `maxTokens` is clamped to `contextWindow`: `nemotron-3.5-lightning-free`
+ * reports `output == context == 262144`, and a per-response cap that exceeds
+ * the model's own window is nonsense even when upstream publishes it.
+ */
+export function normalizeEntry(entry: ModelsDevEntry): NormalizedModel {
+	const notes: string[] = []
+
+	const contextWindow = readLimit(entry.limit?.context, 'limit.context', DEFAULT_CONTEXT_WINDOW, notes)
+	const declaredMax = readLimit(entry.limit?.output, 'limit.output', DEFAULT_MAX_TOKENS, notes)
+	let maxTokens = declaredMax
+	if (maxTokens > contextWindow) {
+		notes.push(`limit.output ${maxTokens} exceeds context ${contextWindow} → clamped`)
+		maxTokens = contextWindow
+	}
+
+	const reasoning = entry.reasoning === true
+	const thinking = thinkingConfig(entry, reasoning)
+	if (reasoning && Array.isArray(entry.reasoning_options) && thinking === undefined) {
+		notes.push('reasoning_options carries no effort axis → host defaults')
+	}
+
+	const name = typeof entry.name === 'string' && entry.name.length > 0 ? entry.name : entry.id
+	if (name === entry.id) notes.push('name missing → using id')
+
+	const config: ProviderModelConfig = {
+		id: entry.id,
+		name,
+		reasoning,
+		input: inputModalities(entry, notes),
+		cost: {
+			input: readCost(entry.cost?.input, 'cost.input', notes),
+			output: readCost(entry.cost?.output, 'cost.output', notes),
+			cacheRead: readCost(entry.cost?.cache_read, 'cost.cache_read', notes),
+			cacheWrite: readCost(entry.cost?.cache_write, 'cost.cache_write', notes),
+		},
+		contextWindow,
+		maxTokens,
+	}
+	if (thinking) config.thinking = thinking
+
+	return { config, notes }
+}
+
+/**
+ * Free-lane judgment for one id.
+ *
+ * Order is the whole point (docs/PLAN.md §T2):
+ *
+ *  1. a verified-rejected id never ships, whatever its price says — both are
+ *     priced at zero upstream and would otherwise be re-advertised forever;
+ *  2. `deprecated` vetoes, including a `*-free` name: upstream retiring a
+ *     model outranks the name it was published under;
+ *  3. verified ids pass unconditionally, because their name carries no signal
+ *     (`big-pickle` is the case that matters);
+ *  4. **metadata decides when it is complete.** `deepseek-v4-flash-free` stayed
+ *     in opencode2dsh's list forever precisely because name-matching ran
+ *     first, so price outranks name here;
+ *  5. only when metadata is absent or incomplete does the `free` name
+ *     heuristic apply — the branch exists for ids that are live upstream and
+ *     missing from models.dev entirely.
+ */
+export function isFreeModel(
+	id: string,
+	entry: ModelsDevEntry | undefined,
+	verifiedFree: Readonly<Record<string, true>>,
+): boolean {
+	if (id in UNAVAILABLE) return false
+	if (entry?.deprecated) return false
+	if (verifiedFree[id] === true) return true
+
+	const costInput = entry?.cost?.input
+	const costOutput = entry?.cost?.output
+	if (typeof costInput !== 'number' || typeof costOutput !== 'number') return id.includes('free')
+	return costInput === 0 && costOutput === 0
+}

package/src/seed.ts

@@ -0,0 +1,133 @@
+/**
+ * Static model seed — tier S3 of the discovery ladder (docs/PLAN.md §T2) and the
+ * offline fallback for capability metadata (docs/PLAN.md §T1).
+ *
+ * Two jobs, both forced by measured host behaviour:
+ *
+ *  1. **`models` must be populated at registration time.** With only
+ *     `fetchDynamicModels`, `--model provider/id` fails cold with
+ *     `Model not found` in 0.6 s — async discovery lands too late to take part
+ *     in `--model` resolution (docs/FINDINGS.md §7.3). The seed is what makes
+ *     cold start work at all.
+ *
+ *  2. **Every entry carries real numbers.** `ProviderModelConfig` marks
+ *     `contextWindow` / `maxTokens` required, and a nested `limits: {context,
+ *     output}` is silently ignored, falling back to the host's generic
+ *     128000/16384 with no warning (docs/FINDINGS.md §7.2). The values below
+ *     are snapshots of models.dev `limit` for these ids, so an offline run
+ *     gets true capabilities instead of the silent fallback.
+ */
+
+import type { ProviderModelConfig } from '@oh-my-pi/pi-coding-agent'
+
+/** Ids verified end-to-end against the anonymous lane. */
+export const SEED_MODELS: readonly ProviderModelConfig[] = [
+	{
+		id: 'big-pickle',
+		name: 'big-pickle (free)',
+		reasoning: true,
+		input: ['text'],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 200_000,
+		maxTokens: 32_000,
+	},
+	{
+		id: 'mimo-v2.6-flash-free',
+		name: 'MiMo v2.6 Flash (free)',
+		reasoning: true,
+		input: ['text', 'image'],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 200_000,
+		maxTokens: 32_000,
+	},
+	{
+		id: 'ling-3.1-flash-free',
+		name: 'Ling 3.1 Flash (free)',
+		reasoning: true,
+		input: ['text'],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 262_144,
+		maxTokens: 32_768,
+	},
+	{
+		id: 'nemotron-3.5-lightning-free',
+		name: 'Nemotron 3.5 Lightning (free)',
+		reasoning: true,
+		input: ['text'],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 262_144,
+		maxTokens: 262_144,
+	},
+	{
+		// models.dev also declares `video`; the host models text+image only.
+		id: 'space-bunny-free',
+		name: 'Space Bunny (free)',
+		reasoning: true,
+		input: ['text', 'image'],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 524_288,
+	},
+	{
+		id: 'fledge-alpha-free',
+		name: 'Fledge Alpha (free)',
+		reasoning: true,
+		input: ['text', 'image'],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
+	},
+	{
+		id: 'longcat-2.5-preview-free',
+		name: 'LongCat 2.5 Preview (free)',
+		reasoning: true,
+		input: ['text', 'image'],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 1_000_000,
+		maxTokens: 131_072,
+	},
+]
+
+/**
+ * Ids on the free lane whose *name* says nothing about it, so the free
+ * judgment can never be reached by name alone. `big-pickle` is the case that
+ * matters: free by pricing, invisible to `id.includes('free')`.
+ */
+export const VERIFIED_FREE: Readonly<Record<string, true>> = {
+	'big-pickle': true,
+	'mimo-v2.6-flash-free': true,
+	'ling-3.1-flash-free': true,
+	'nemotron-3.5-lightning-free': true,
+	'space-bunny-free': true,
+	'fledge-alpha-free': true,
+	'longcat-2.5-preview-free': true,
+}
+
+/**
+ * Ids upstream refuses on the anonymous lane. Each reason is the verbatim
+ * upstream response from a gate-shaped probe.
+ *
+ * `mimo-v2.5-free` is the case that proves this list earns its keep: retired
+ * from the live lane (gone from `/models`, `401 ModelError`) while models.dev
+ * still publishes it at zero cost — metadata alone would keep re-advertising
+ * a dead id.
+ *
+ * `exo-free`, `jev-1.13-free` and `ling-3.0-flash-fin-free` (all measured
+ * 2026-10-11, three identical probes each) are the same shape of fact from
+ * the opposite direction: Zen still lists all three live and models.dev still
+ * prices two of them at zero, so S1 and S2 both vouch for ids the chat lane
+ * refuses. `ling-3.0-flash-fin-free` is the one that reverses a decision —
+ * it used to flip 400/503 and was deliberately kept while it still showed up
+ * in the catalogue, but it now answers `400 Model is unavailable` on every
+ * request, which is a refusal and not an outage.
+ */
+export const UNAVAILABLE: Readonly<Record<string, string>> = {
+	'mimo-v2.5-free': '401 ModelError: not supported upstream (retired, measured 2026-10-08)',
+	'exo-free': '410 ModelDeprecated: deprecated upstream (3/3 measured 2026-10-11)',
+	'jev-1.13-free': '400 ModelProtocolUnsupported: not served on this protocol (3/3 measured 2026-10-11)',
+	'ling-3.0-flash-fin-free': '400 Model is unavailable (3/3 measured 2026-10-11)',
+	// Zen spells this with hyphens; the dotted spelling never matched a live id.
+	'nemotron-3-ultra-free': '401 ModelError: not supported upstream',
+	'muse-spark-1.2-contributor-free': '403 RegionError: blocked in this region',
+	'muse-spark-1.3-contributor-free': '403 RegionError: blocked in this region',
+}

package/src/session.ts

@@ -0,0 +1,107 @@
+/**
+ * Per-conversation session identity (docs/PLAN.md §T3).
+ *
+ * Upstream does prompt-cache affinity per session id, so sharing one id across
+ * every conversation in a process makes unrelated sessions evict each other's
+ * cache. The previous implementation used a process-level constant.
+ *
+ * `options.sessionId` was **probed**, not assumed: a dump of the custom-API
+ * handler's runtime `options` (omp 18.6.1, 2026-10-05) shows a real per-session
+ * UUID (`01a10bfe-…`), mirrored in `options.metadata.user_id`. Neither is
+ * declared in the host's published `SimpleStreamOptions` type, so both are read
+ * through runtime narrowing rather than trusted casts.
+ *
+ * The id must be attached per *request*: `ProviderConfig.headers` is fixed at
+ * registration time and cannot vary by conversation, so the caller merges these
+ * onto the model it hands the engine — the model is rebuilt on every request,
+ * which is the seam that actually varies.
+ */
+
+import { createHash } from 'node:crypto'
+
+import type { SimpleStreamOptions } from '@earendil-works/pi-ai'
+
+const CANONICAL_SESSION = /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+
+function base62Fixed(value: bigint, width: number): string {
+	let out = ''
+	let v = value
+	for (let i = 0; i < width; i++) {
+		out = BASE62[Number(v % 62n)] + out
+		v /= 62n
+	}
+	return out
+}
+
+/** OpenCode's canonical session shape, ported from opencode2dsh `ids.ts`. */
+export function canonicalSessionID(signal: string): string {
+	if (CANONICAL_SESSION.test(signal)) return signal
+	const sum = createHash('sha256').update(`ses\0${signal}`).digest()
+	return `ses_${sum.subarray(0, 6).toString('hex')}${base62Fixed(BigInt(`0x${sum.subarray(6, 16).toString('hex')}`), 14)}`
+}
+
+/** Process-level fallback, used when the host gives us no session identity. */
+export const PROCESS_SESSION = canonicalSessionID(`omp:${process.pid}:${new Date().toISOString().slice(0, 10)}`)
+
+/**
+ * Resolve the signal to derive this request's session id from.
+ *
+ * Preference order: the host's own `sessionId`, then the `user_id` blob it
+ * mirrors into metadata, then the process constant. Returns null when nothing
+ * usable is present so the caller can log the fallback rather than pretend.
+ */
+function sessionSignal(options: SimpleStreamOptions | undefined): string | null {
+	if (!options) return null
+
+	if ('sessionId' in options && typeof options.sessionId === 'string' && options.sessionId.length > 0) {
+		return options.sessionId
+	}
+
+	if ('metadata' in options) {
+		const metadata = options.metadata
+		if (typeof metadata === 'object' && metadata !== null && 'user_id' in metadata) {
+			const userId = metadata.user_id
+			if (typeof userId === 'string') {
+				try {
+					const parsed: unknown = JSON.parse(userId)
+					if (
+						typeof parsed === 'object' &&
+						parsed !== null &&
+						'session_id' in parsed &&
+						typeof parsed.session_id === 'string' &&
+						parsed.session_id.length > 0
+					) {
+						return parsed.session_id
+					}
+				} catch {
+					// Not JSON: fall through to the process constant.
+				}
+			}
+		}
+	}
+
+	return null
+}
+
+/**
+ * Canonical session id for this request, stable across every turn of one
+ * conversation and distinct between conversations in the same process.
+ */
+export function sessionForRequest(options: SimpleStreamOptions | undefined): {
+	readonly id: string
+	readonly derived: boolean
+} {
+	const signal = sessionSignal(options)
+	if (signal === null) return { id: PROCESS_SESSION, derived: false }
+	return { id: canonicalSessionID(`omp:${signal}`), derived: true }
+}
+
+/** Headers the upstream shape check and cache affinity both key on. */
+export function sessionHeaders(sessionId: string): Record<string, string> {
+	return {
+		'x-opencode-session': sessionId,
+		'x-session-affinity': sessionId,
+		'x-session-id': sessionId,
+	}
+}