@hyav/pi-provider 0.1.0-oidc-bootstrap.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+This file is the authoritative user-facing release history for `@hyav/pi-provider`.
+
+## 0.1.0 - 2026-08-16
+
+- Initial public release of `@hyav/pi-provider`.
+- Provider Kit host for dynamic providers, status, preflight, live checks, and request tuners.
+- Manifest-discovered adapter extensions with deterministic ordering, reload isolation, validation, and conflict handling.
+- Cached model catalogs, bounded background refresh, pricing metadata, and explicit free-versus-billable diagnostics.
+- Built-in Charm Hyper, DeepSeek, Google Gemini, OpenAI Codex, OpenCode Zen, and OpenCode Go integrations.

package/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thank you for helping improve `@hyav/pi-provider`. The canonical user contract is in [README.md](README.md); adapter extension contracts are in [`docs/adapter-extensions.md`](docs/adapter-extensions.md).
+
+## Before you start
+
+- Search existing [GitHub issues](https://github.com/hyav/pi-provider/issues) before opening a new one.
+- For suspected vulnerabilities, follow [SECURITY.md](SECURITY.md) instead of using a public issue.
+- Keep changes focused. Do not include credentials, personal data, private fixtures, generated local state, or ignored private overlays.
+
+## Development setup
+
+Use Node.js `22.19.0` or later with npm. The tested Pi host baseline is `0.84.1`:
+
+```sh
+npm ci --ignore-scripts
+```
+
+Pi loads the published TypeScript source through its extension loader. Do not add a compiled `dist/` tree unless the package contract is deliberately changed and documented.
+
+## Required checks
+
+Run the same deterministic gate used by CI:
+
+```sh
+npm run audit:runtime
+npm run audit:all
+npm run check
+npm test
+npm run artifact:check
+```
+
+- `npm run audit:runtime` checks the published dependency boundary for high-severity advisories.
+- `npm run audit:all` also checks the development and tested-host dependency tree.
+- `npm run check` runs Biome and TypeScript type checking.
+- `npm test` runs Node test runner suites under `test/` against local servers, isolated caches, and deterministic fixtures.
+- `npm run artifact:check` builds a real npm tarball, rejects repository-only files, installs it in a temporary consumer, and loads the published Pi entry points.
+
+The ordinary gate must not make real model requests or require billable credentials.
+
+## Changes and review
+
+- Public behavior changes must include behavior-focused tests and documentation updates.
+- Keep `README.md` canonical and update `README.zh-CN.md` when user-visible behavior changes.
+- Update [CHANGELOG.md](CHANGELOG.md) for release-relevant behavior, compatibility, security, or migration changes.
+- Preserve the source-package boundary in `package.json.files`; tests, fixtures, scripts, and local caches must not enter the npm artifact.
+- Treat model IDs, pricing metadata, and provider status as security-sensitive input. Keep validation, deadlines, and footer boundaries intact.
+
+## Reporting defects
+
+Use a public [GitHub issue](https://github.com/hyav/pi-provider/issues) for reproducible defects and include, when safe:
+
+- package version or commit;
+- Node.js, Pi, and Provider versions;
+- Provider and model IDs, without API keys or OAuth tokens;
+- expected and actual behavior;
+- a minimal reproduction and redacted logs.
+
+Do not disclose vulnerability details or credentials publicly; follow [SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contribution is provided under the repository's [MIT License](LICENSE).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hyav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @hyav/pi-provider
+
+[简体中文](README.zh-CN.md)
+
+A provider extension toolkit for [Pi](https://pi.dev). It registers LLM providers, discovers model catalogs, tunes requests, and reports cached or explicitly refreshed account status while preserving Pi's native footer.
+
+[Adapter contract](https://github.com/hyav/pi-provider/blob/main/docs/adapter-extensions.md) · [Support](SUPPORT.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md)
+
+## Highlights
+
+- One Provider Kit Host for registration, status, preflight checks, live checks, and request tuners
+- Manifest-discovered provider, status, preflight, and tuner adapters reloaded with `/reload`
+- Resilient model catalogs with cached fallback, bounded background refresh, and failure retention
+- Provider-first pricing metadata with optional OpenRouter completion and quality indicators
+- Explicit diagnostics: cached `/status`, free `/status refresh`, and potentially billable `/status check`
+- Built-in integrations for Charm Hyper, DeepSeek, Google Gemini, OpenAI Codex, OpenCode Zen, and OpenCode Go
+
+## Install
+
+Requires Node.js 22.19.0 or newer, Pi, and credentials for the providers you use.
+
+```sh
+pi install npm:@hyav/pi-provider
+```
+
+
+## Quick start
+
+1. Configure credentials in Pi. Charm Hyper accepts `HYPER_API_KEY` or Pi's `/login` OAuth flow.
+2. Select a model, for example:
+
+   ```text
+   /model charm-hyper/deepseek-v4-pro
+   ```
+
+3. Inspect the cached report:
+
+   ```text
+   /status
+   ```
+
+Use `/status refresh` for free endpoint, authentication, catalog, and account checks. Use `/status check` only when you explicitly accept a real model request and possible usage charges.
+
+## Common configuration
+
+| Name | Required | Default | Effect |
+|---|---:|---|---|
+| `HYPER_API_KEY` | For Charm Hyper API-key auth | None | Supplies the built-in `charm-hyper` provider credential; OAuth users may use `/login` |
+| `PI_CODING_AGENT_DIR` | No | `~/.pi/agent` | Changes the base directory for public OpenRouter metadata cache |
+
+Programmatic integrations can configure pricing fallback, pricing policies, request timeouts, metadata URLs, and cache paths through `createProviderKitRuntime()` or `createProviderKitHost()`. The source definition [`ProviderKitDependencies`](core/runtime-config.ts) is authoritative.
+
+Trusted packages can add adapters through manifest entries under `providers/`, `status/`, `preflight/`, and `tuners/`. See the [adapter extension contract](https://github.com/hyav/pi-provider/blob/main/docs/adapter-extensions.md) for helpers, validation, conflicts, reload behavior, and lifecycle boundaries. The root [`index.ts`](index.ts) defines the public TypeScript exports.
+
+## Before you use it
+
+`/status` is offline, `/status refresh` performs free remote checks, and `/status check` sends a live model request that may consume quota. Configured credentials are sent only to the corresponding provider endpoints and are omitted from status output.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,61 @@
+# @hyav/pi-provider
+
+[English](README.md)
+
+为 [Pi](https://pi.dev) 提供 Provider 扩展工具包，用于注册 LLM Provider、发现模型目录、调优请求，以及查看缓存或显式刷新的账户状态，同时保留 Pi 原生 Footer。
+
+[适配器契约](https://github.com/hyav/pi-provider/blob/main/docs/adapter-extensions.zh-CN.md) · [支持策略](SUPPORT.md) · [参与贡献](CONTRIBUTING.md) · [更新记录](CHANGELOG.md) · [安全策略](SECURITY.md)
+
+## 核心能力
+
+- 由一个 Provider Kit Host 统一负责注册、Status、Preflight、实时检查和请求 Tuner
+- 通过 manifest 发现 Provider、Status、Preflight 和 Tuner Adapter，并在 `/reload` 后重新加载
+- 通过缓存回退、有界后台刷新和失败保留提供可靠的模型目录
+- 优先采用 Provider 价格元数据，并可由 OpenRouter 补全价格和质量指标
+- 显式诊断：缓存 `/status`、免费 `/status refresh` 和可能计费的 `/status check`
+- 内置 Charm Hyper、DeepSeek、Google Gemini、OpenAI Codex、OpenCode Zen 和 OpenCode Go 集成
+
+## 安装
+
+需要 Node.js 22.19.0 或更高版本、Pi，以及所用 Provider 的凭据。
+
+```sh
+pi install npm:@hyav/pi-provider
+```
+
+
+## 快速开始
+
+1. 在 Pi 中配置凭据。Charm Hyper 接受 `HYPER_API_KEY` 或 Pi 的 `/login` OAuth 流程。
+2. 选择模型，例如：
+
+   ```text
+   /model charm-hyper/deepseek-v4-pro
+   ```
+
+3. 查看缓存报告：
+
+   ```text
+   /status
+   ```
+
+使用 `/status refresh` 执行免费的端点、鉴权、目录和账户检查。只有明确接受一次真实模型请求及其可能产生的用量费用时，才使用 `/status check`。
+
+## 常用配置
+
+| 名称 | 必需 | 默认值 | 作用 |
+|---|---:|---|---|
+| `HYPER_API_KEY` | Charm Hyper API Key 鉴权需要 | 无 | 为内置 `charm-hyper` Provider 提供凭据；OAuth 用户可以使用 `/login` |
+| `PI_CODING_AGENT_DIR` | 否 | `~/.pi/agent` | 修改公开 OpenRouter 元数据缓存的基础目录 |
+
+程序化集成可以通过 `createProviderKitRuntime()` 或 `createProviderKitHost()` 配置价格回退、价格策略、请求超时、元数据 URL 和缓存路径。源码定义 [`ProviderKitDependencies`](core/runtime-config.ts) 是权威依据。
+
+可信包可以通过 manifest 中的 `providers/`、`status/`、`preflight/` 和 `tuners/` 条目添加 Adapter。Helper、校验、冲突、reload 行为和生命周期边界见 [Adapter Extension 契约](https://github.com/hyav/pi-provider/blob/main/docs/adapter-extensions.zh-CN.md)。根目录 [`index.ts`](index.ts) 定义公开 TypeScript 导出。
+
+## 使用须知
+
+`/status` 离线运行，`/status refresh` 执行免费远程检查，`/status check` 会发送可能消耗配额的真实模型请求。配置的凭据只会发送给对应 Provider 端点，并且不会出现在 Status 输出中。
+
+## 许可证
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+`@hyav/pi-provider` is a Pi extension. Its TypeScript source runs with the user's system privileges, can access configured Provider endpoints and credentials, and may perform explicitly requested account or model checks. Review the source and package artifact before installing extensions from untrusted sources.
+
+## Supported versions
+
+| Version or branch | Support |
+|---|---|
+| Latest published release | Best-effort security fixes |
+| Older published releases | Not supported |
+| Unreleased `main` | No compatibility or response-time promise |
+
+There is no long-term-support branch. Upgrade to the latest release before reporting whether a problem is still present.
+
+## Reporting a vulnerability
+
+Do **not** report suspected vulnerabilities in a public issue, pull request, chat, or forum.
+
+Please report vulnerabilities privately via [GitHub Security Advisories](https://github.com/hyav/pi-provider/security/advisories/new). Include:
+
+- affected package version, commit, or published artifact;
+- reproduction steps or a minimal proof of concept;
+- impact, prerequisites, and affected trust boundary;
+- logs or traces with credentials, tokens, private endpoints, and personal data removed;
+- a safe way to contact you for follow-up.
+
+## Response and disclosure
+
+Reports are handled on a best-effort basis; no acknowledgement, remediation, or disclosure deadline is guaranteed. The maintainer will coordinate a fix and public disclosure when affected users have a reasonable mitigation or upgrade path. Please do not publish details before then.
+
+## Scope and dependency boundary
+
+This policy covers the source repository, the published `@hyav/pi-provider` npm artifact, its Pi manifest, built-in adapters, credential handling, remote response validation, deadlines, and the Provider Kit runtime. The published artifact has no bundled runtime dependencies; its Pi core imports are host-supplied peers. CI runs both `npm run audit:runtime` for the published boundary and `npm run audit:all` for development and tested-host dependencies. Scanner findings are triaged rather than force-fixed across an untested host version.
+
+Vulnerabilities in Pi, a Provider service, npm, GitHub, or another dependency should also be reported to the relevant upstream maintainer. For ordinary defects and usage questions, use [SUPPORT.md](SUPPORT.md) and the [public issue tracker](https://github.com/hyav/pi-provider/issues).
+

package/SUPPORT.md

@@ -0,0 +1,25 @@
+# Support
+
+Support is best effort for the latest published release line. This project has no long-term-support branch or guaranteed response SLA. Older release lines are unsupported. The `main` branch may contain unreleased behavior and is not a compatibility promise.
+
+## Where to ask
+
+- **Reproducible bugs:** open a [GitHub issue](https://github.com/hyav/pi-provider/issues).
+- **Feature requests:** open an issue with the user problem, proposed behavior, and compatibility impact.
+- **Usage questions:** open an issue after checking the [README](README.md) and [adapter documentation](docs/adapter-extensions.md).
+- **Security vulnerabilities:** do not use a public issue; follow [SECURITY.md](SECURITY.md).
+- **Provider outages or billing disputes:** contact the affected Provider. This package only reports the upstream data it can retrieve.
+
+## Include in a useful report
+
+Please provide:
+
+- the package version or commit;
+- Node.js and Pi versions;
+- operating system and installation method;
+- Provider and model IDs, without API keys or OAuth tokens;
+- expected and actual behavior;
+- a minimal reproduction and redacted logs.
+
+Avoid posting prompts, account IDs, cookies, authorization headers, private source code, or personal data. If a report contains sensitive material, close it and follow [SECURITY.md](SECURITY.md) instead.
+

package/core/adapter-extensions.ts

@@ -0,0 +1,175 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	type AdapterKind,
+	type AdapterRegistrationEnvelope,
+	PROVIDER_KIT_ADAPTER_EVENT,
+	PROVIDER_KIT_ADAPTER_PROTOCOL_VERSION,
+	PROVIDER_KIT_STARTUP_BRIDGE_EVENT,
+	type StartupBridge,
+	type StartupBridgeRequest,
+} from "./adapter-protocol.ts";
+import { isStableAdapterId, validateAdapter, validateAdapterIdentity } from "./adapter-validation.ts";
+import type { PreflightAdapter } from "./preflight-manager.ts";
+import { registerProviderAdapter } from "./provider-registration.ts";
+import type { ProviderKitDependencies } from "./runtime-config.ts";
+import { getDefaultProviderKitDependencies } from "./runtime-config.ts";
+import type { ProviderAdapter, StatusAdapter, TunerAdapter } from "./types.ts";
+
+/** Context supplied to an Adapter Extension factory. */
+export interface AdapterExtensionContext extends ProviderKitDependencies {
+	/** The Pi API that owns this extension factory. */
+	pi: ExtensionAPI;
+}
+
+export interface ProviderExtensionDefinition {
+	id: string;
+	create(context: AdapterExtensionContext): ProviderAdapter | Promise<ProviderAdapter>;
+}
+
+export interface StatusExtensionDefinition {
+	id: string;
+	providerId: string;
+	create(context: AdapterExtensionContext): StatusAdapter | Promise<StatusAdapter>;
+}
+
+export interface PreflightExtensionDefinition {
+	id: string;
+	providerId: string;
+	create(context: AdapterExtensionContext): PreflightAdapter | Promise<PreflightAdapter>;
+}
+
+export interface TunerExtensionDefinition {
+	id: string;
+	create(context: AdapterExtensionContext): TunerAdapter | Promise<TunerAdapter>;
+}
+
+function validateStaticIdentity(kind: AdapterKind, id: string, providerId?: string): void {
+	if (!isStableAdapterId(id)) throw new Error(`${kind} static ID must be a non-empty ID without whitespace`);
+	if ((kind === "status" || kind === "preflight") && !isStableAdapterId(providerId)) {
+		throw new Error(`${kind} static provider ID must be a non-empty ID without whitespace`);
+	}
+}
+
+function getStartupBridge(pi: ExtensionAPI): StartupBridge {
+	const request: StartupBridgeRequest = {};
+	pi.events.emit(PROVIDER_KIT_STARTUP_BRIDGE_EVENT, request);
+	return (
+		request.bridge ?? {
+			dependencies: getDefaultProviderKitDependencies(),
+			officialPricing: Promise.resolve({}),
+		}
+	);
+}
+
+function emitRegistration(pi: ExtensionAPI, envelope: AdapterRegistrationEnvelope): void {
+	pi.events.emit(PROVIDER_KIT_ADAPTER_EVENT, envelope);
+	pi.on("session_start", () => {
+		pi.events.emit(PROVIDER_KIT_ADAPTER_EVENT, envelope);
+	});
+}
+
+function createAdapterExtension<TAdapter extends ProviderAdapter | StatusAdapter | PreflightAdapter | TunerAdapter>(
+	kind: AdapterKind,
+	id: string,
+	providerId: string | undefined,
+	create: (context: AdapterExtensionContext) => TAdapter | Promise<TAdapter>,
+): (pi: ExtensionAPI) => Promise<void> {
+	validateStaticIdentity(kind, id, providerId);
+	const token = {};
+	return async (pi) => {
+		const bridge = getStartupBridge(pi);
+		const createAdapter = (context: AdapterExtensionContext) => create(context);
+		const adapter = await createAdapter({ ...bridge.dependencies, pi });
+		if (kind === "provider") {
+			const providerAdapter = adapter as ProviderAdapter;
+			validateAdapter("provider", providerAdapter);
+			validateAdapterIdentity("provider", id, providerAdapter);
+			const modelDrafts = providerAdapter.provider.models;
+			// The startup registration is intentionally independent of Host
+			// acknowledgement. Host re-registers the accepted catalog after the
+			// session_start barrier with official pricing and conflict resolution.
+			// Keep the pre-normalization drafts in the plain event envelope: the
+			// Host runs in a different Pi module context and cannot use this
+			// extension's module-local state. The factory is retained so a Host
+			// loaded later can recreate the adapter with its configured runtime.
+			registerProviderAdapter(pi, providerAdapter, bridge.dependencies, {}, modelDrafts);
+			emitRegistration(pi, {
+				version: PROVIDER_KIT_ADAPTER_PROTOCOL_VERSION,
+				kind: "provider",
+				id,
+				token,
+				adapter: providerAdapter,
+				factory: createAdapter,
+				startupDependencies: bridge.dependencies,
+				modelDrafts,
+			});
+			return;
+		}
+		if (kind === "status") {
+			const statusAdapter = adapter as StatusAdapter;
+			validateAdapter("status", statusAdapter);
+			validateAdapterIdentity("status", id, providerId, statusAdapter);
+			emitRegistration(pi, {
+				version: PROVIDER_KIT_ADAPTER_PROTOCOL_VERSION,
+				kind: "status",
+				id,
+				providerId: providerId!,
+				token,
+				adapter: statusAdapter,
+				factory: createAdapter,
+				startupDependencies: bridge.dependencies,
+			});
+			return;
+		}
+		if (kind === "preflight") {
+			const preflightAdapter = adapter as PreflightAdapter;
+			validateAdapter("preflight", preflightAdapter);
+			validateAdapterIdentity("preflight", id, providerId, preflightAdapter);
+			emitRegistration(pi, {
+				version: PROVIDER_KIT_ADAPTER_PROTOCOL_VERSION,
+				kind: "preflight",
+				id,
+				providerId: providerId!,
+				token,
+				adapter: preflightAdapter,
+				factory: createAdapter,
+				startupDependencies: bridge.dependencies,
+			});
+			return;
+		}
+		const tunerAdapter = adapter as TunerAdapter;
+		validateAdapter("tuner", tunerAdapter);
+		validateAdapterIdentity("tuner", id, tunerAdapter);
+		emitRegistration(pi, {
+			version: PROVIDER_KIT_ADAPTER_PROTOCOL_VERSION,
+			kind: "tuner",
+			id,
+			token,
+			adapter: tunerAdapter,
+			factory: createAdapter,
+			startupDependencies: bridge.dependencies,
+		});
+	};
+}
+
+/** Define a Pi extension factory that contributes one Provider Adapter. */
+export function defineProviderExtension(definition: ProviderExtensionDefinition): (pi: ExtensionAPI) => Promise<void> {
+	return createAdapterExtension("provider", definition.id, undefined, definition.create);
+}
+
+/** Define a Pi extension factory that contributes one Status Adapter. */
+export function defineStatusExtension(definition: StatusExtensionDefinition): (pi: ExtensionAPI) => Promise<void> {
+	return createAdapterExtension("status", definition.id, definition.providerId, definition.create);
+}
+
+/** Define a Pi extension factory that contributes one Preflight Adapter. */
+export function definePreflightExtension(
+	definition: PreflightExtensionDefinition,
+): (pi: ExtensionAPI) => Promise<void> {
+	return createAdapterExtension("preflight", definition.id, definition.providerId, definition.create);
+}
+
+/** Define a Pi extension factory that contributes one Tuner Adapter. */
+export function defineTunerExtension(definition: TunerExtensionDefinition): (pi: ExtensionAPI) => Promise<void> {
+	return createAdapterExtension("tuner", definition.id, undefined, definition.create);
+}

package/core/adapter-protocol.ts

@@ -0,0 +1,120 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { OfficialModelMeta } from "./official-pricing.ts";
+import type { PreflightAdapter } from "./preflight-manager.ts";
+import type { ProviderKitDependencies } from "./runtime-config.ts";
+import type { ProviderAdapter, ProviderModelDraft, StatusAdapter, TunerAdapter } from "./types.ts";
+
+/** Registration protocol version shared by Host and Adapter Extensions. */
+export const PROVIDER_KIT_ADAPTER_PROTOCOL_VERSION = 2 as const;
+
+/** Event-bus channel used for Adapter Extension registration envelopes. */
+export const PROVIDER_KIT_ADAPTER_EVENT = "provider-kit:adapter";
+
+/** Event-bus channel used by the Host to expose the factory-stage startup bridge. */
+export const PROVIDER_KIT_STARTUP_BRIDGE_EVENT = "provider-kit:startup-bridge";
+
+/** Event-bus channel used to detect more than one Provider Kit Host. */
+export const PROVIDER_KIT_HOST_CLAIM_EVENT = "provider-kit:host-claim";
+
+export type AdapterKind = "provider" | "status" | "preflight" | "tuner";
+
+export interface AdapterFactoryContext extends ProviderKitDependencies {
+	pi: ExtensionAPI;
+}
+
+export type AdapterFactory = (
+	context: AdapterFactoryContext,
+) =>
+	| ProviderAdapter
+	| StatusAdapter
+	| PreflightAdapter
+	| TunerAdapter
+	| Promise<ProviderAdapter | StatusAdapter | PreflightAdapter | TunerAdapter>;
+
+export interface AdapterRegistrationEnvelopeBase {
+	version: typeof PROVIDER_KIT_ADAPTER_PROTOCOL_VERSION;
+	kind: AdapterKind;
+	id: string;
+	token: object;
+	/** Factory retained for Host-side rehydration when Host loaded after Adapter. */
+	factory: AdapterFactory;
+	/** Exact dependency object used by the initial factory invocation. */
+	startupDependencies: ProviderKitDependencies;
+}
+
+export interface ProviderAdapterRegistrationEnvelope extends AdapterRegistrationEnvelopeBase {
+	kind: "provider";
+	adapter: ProviderAdapter;
+	/** Original model drafts, before the startup catalog is normalized. */
+	modelDrafts?: ProviderModelDraft[];
+}
+
+export interface StatusAdapterRegistrationEnvelope extends AdapterRegistrationEnvelopeBase {
+	kind: "status";
+	providerId: string;
+	adapter: StatusAdapter;
+}
+
+export interface PreflightAdapterRegistrationEnvelope extends AdapterRegistrationEnvelopeBase {
+	kind: "preflight";
+	providerId: string;
+	adapter: PreflightAdapter;
+}
+
+export interface TunerAdapterRegistrationEnvelope extends AdapterRegistrationEnvelopeBase {
+	kind: "tuner";
+	adapter: TunerAdapter;
+}
+
+export type AdapterRegistrationEnvelope =
+	| ProviderAdapterRegistrationEnvelope
+	| StatusAdapterRegistrationEnvelope
+	| PreflightAdapterRegistrationEnvelope
+	| TunerAdapterRegistrationEnvelope;
+
+export interface StartupBridge {
+	dependencies: ProviderKitDependencies;
+	officialPricing: Promise<Record<string, OfficialModelMeta>>;
+}
+
+export interface StartupBridgeRequest {
+	bridge?: StartupBridge;
+}
+
+export interface HostClaimRequest {
+	token: object;
+	occupied: boolean;
+}
+
+export function isHostClaimRequest(value: unknown): value is HostClaimRequest {
+	return (
+		value !== null &&
+		typeof value === "object" &&
+		"token" in value &&
+		(value as { token?: unknown }).token !== null &&
+		typeof (value as { token?: unknown }).token === "object" &&
+		"occupied" in value &&
+		typeof (value as { occupied?: unknown }).occupied === "boolean"
+	);
+}
+
+export function isAdapterRegistrationEnvelope(value: unknown): value is AdapterRegistrationEnvelope {
+	if (value === null || typeof value !== "object") return false;
+	const candidate = value as Partial<AdapterRegistrationEnvelope>;
+	return (
+		candidate.version === PROVIDER_KIT_ADAPTER_PROTOCOL_VERSION &&
+		(candidate.kind === "provider" ||
+			candidate.kind === "status" ||
+			candidate.kind === "preflight" ||
+			candidate.kind === "tuner") &&
+		typeof candidate.id === "string" &&
+		candidate.token !== null &&
+		typeof candidate.token === "object" &&
+		typeof candidate.factory === "function" &&
+		candidate.startupDependencies !== null &&
+		typeof candidate.startupDependencies === "object" &&
+		candidate.adapter !== null &&
+		typeof candidate.adapter === "object" &&
+		(candidate.kind !== "provider" || candidate.modelDrafts === undefined || Array.isArray(candidate.modelDrafts))
+	);
+}