@serviceme/devtools-shared 0.4.5

package/dist/index.d.ts

@@ -0,0 +1,1394 @@
+/**
+ * BYO Model Provider types — Phase 2 of the multi-vendor model
+ * configuration system.
+ *
+ * Source plan: docs/architecture/phase-2-byo-model-providers.md
+ *
+ * Phase 1 only exposed models that VSCode's language-model API knew
+ * about (effectively Copilot). Phase 2 lets the user register their
+ * own API providers (MiniMax / DeepSeek / OpenAI / Anthropic / any
+ * OpenAI-compatible service) and have @serviceme chat route directly
+ * to that provider's HTTP API, bypassing `copilot prompt --model`.
+ *
+ * The shape is intentionally small:
+ *   - {@link ProviderType}: picks an HTTP adapter
+ *   - {@link ProviderModel}: one entry per model the provider exposes
+ *   - {@link ProviderConfig}: persisted form (includes `apiKeyRef`,
+ *     a SecretStorage key reference — NEVER the actual key)
+ *   - {@link PublicProvider}: webview-facing projection (no secret
+ *     reference; only a `hasApiKey: boolean` flag)
+ *   - {@link ProviderTestResult}: result of a connectivity probe
+ *
+ * The secret/reference split is the invariant that lets us move
+ * ProviderConfig across the postMessage boundary safely (we send
+ * PublicProvider) while still being able to fetch the real key from
+ * SecretStorage on the extension side at chat time.
+ */
+/**
+ * Adapter family. Each type maps to one `IProviderAdapter`
+ * implementation in `apps/extension/src/services/providers/adapters/`.
+ *
+ * `vscode-builtin` is a read-only pseudo-provider that delegates to
+ * the Phase 1 `vscode.lm.selectChatModels` path — preserves existing
+ * Copilot-by-VSCode-LM behavior so users who don't BYO still see
+ * whatever VSCode already exposes.
+ *
+ * The named vendor types (`minimax`, `deepseek`) are thin aliases
+ * that pick a protocol family + sensible defaults (see
+ * {@link BUILTIN_PROVIDER_PRESETS}). The wire protocol is identical
+ * to the `-compatible` family; the named type exists so the UI can
+ * pre-fill baseUrl / displayName / default model list without
+ * requiring the user to look up endpoint docs.
+ */
+type ProviderType = "openai-compatible" | "anthropic-compatible" | "minimax" | "deepseek" | "kimi" | "zhipu" | "stepfun" | "siliconflow" | "openrouter" | "novita" | "agnes" | "vscode-builtin";
+/**
+ * Curated metadata for named, well-known models. Used as a
+ * **fallback** when a `ProviderModel` entry omits one of the
+ * extended fields (`detail` / `capabilities` / `pricing` /
+ * `priceCategory` / `thinkingSchema`). The lookup is keyed on
+ * the un-qualified model id (the `id` field, not the
+ * `providerId::modelId` qualified form) so it stays stable
+ * across providers.
+ *
+ * The UI pre-fills this metadata into `BUILTIN_PROVIDER_PRESETS`
+ * at extension load, so the user does not have to type it in for
+ * the named vendors (minimax / deepseek). For user-added
+ * `-compatible` providers, the metadata stays empty and the
+ * picker just shows the model without the cost column / thinking
+ * dropdown.
+ *
+ * Pricing numbers are stored once in USD; the CNY values live on
+ * the same entry so a single `lookupModelMetadata(id)` call
+ * gives the registrar everything it needs to format the picker's
+ * cost column under either currency (resolved from `baseUrl`).
+ *
+ * Source numbers:
+ *   - minimax M3: https://platform.minimaxi.com/docs/llms/overview
+ *     (USD $0.3 / $1.2 / $0.06; CNY ¥2.1 / ¥8.4 / ¥0.42)
+ *   - minimax M2.7: same family, half the speed tier
+ *   - minimax M2.7-highspeed: 2x the M2.7 price
+ *   - deepseek v4-flash: USD $0.14 / $0.28 / $0.0028
+ *   - deepseek v4-pro:   USD $0.435 / $0.87 / $0.003625
+ *     (CNY values from the per-region pricing pages on
+ *     https://api-docs.deepseek.com/quick_start/pricing)
+ */
+interface CuratedModelMetadata {
+    /** Short description for the picker's `detail` column. */
+    detail: ModelDetail;
+    /** Whether the model advertises vision. */
+    imageInput: boolean;
+    /** Whether the model supports tool calling. */
+    toolCalling: boolean;
+    /** USD pricing (per million tokens). */
+    pricingUSD: ModelPricing;
+    /** CNY pricing (per million tokens). */
+    pricingCNY: ModelPricing;
+    /** Tier tag for the picker's price column. */
+    priceCategory: ModelPriceCategory;
+    /** Thinking-dropdown schema (omit = no thinking dropdown). */
+    thinkingSchema?: Exclude<ModelThinkingSchema, "none">;
+    /**
+     * Context-window token caps. Centralized here (rather than as
+     * magic numbers scattered across `BUILTIN_PROVIDER_PRESETS` call
+     * sites) so every consumer — the named-vendor Add-form presets,
+     * "Fetch from API" enrichment (`ProviderRegistry.fetchRemoteModels`),
+     * and the chat-registration fallback
+     * (`LmChatProviderRegistrar.resolveModelMetadata`) — agrees on the
+     * same numbers for a given model id. Optional: a curated entry can
+     * exist purely for capability/pricing metadata without token caps
+     * (uncommon, but keeps the field honest for cases where only the
+     * cost/capability data is verified).
+     */
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+}
+/**
+ * Short one-line description rendered in the VSCode chat model
+ * picker's `detail` column. The full pricing block + baseUrl is
+ * surfaced separately as the picker's `tooltip` (multi-line). Kept
+ * short (one sentence) so it fits on a single line in the picker.
+ */
+type ModelDetail = string;
+/**
+ * Pricing column metadata. Both the chat model picker and the
+ * ProvidersTab form render this. `cacheRead` is the cache-hit cost
+ * per million tokens (USD or CNY depending on the resolved
+ * `baseUrl` — see `currencyForBaseUrl` in
+ * `apps/extension/src/services/providers/`). `null` means the
+ * provider has not published a cache-hit price; the picker shows
+ * "(not published)" rather than a misleading zero.
+ */
+interface ModelPricing {
+    /** Input cost per million tokens (USD or CNY per `currencyForBaseUrl`). */
+    input: number;
+    /** Output cost per million tokens. */
+    output: number;
+    /** Cache-hit cost per million tokens. `null` = provider has not published one. */
+    cacheRead: number | null;
+}
+/**
+ * Tier tag for the picker's price column. Aligned with the
+ * upstream Copilot Chat price categories so the visual bucket
+ * matches what GitHub Copilot uses for its own models.
+ */
+type ModelPriceCategory = "low" | "medium" | "high" | "very_high";
+/**
+ * Thinking dropdown schema the picker renders beneath the model
+ * name. The user's selection is delivered to
+ * `provideLanguageModelChatResponse` via
+ * `options.modelConfiguration[schemaKey]`. The request layer reads
+ * that value and translates it into the vendor's native
+ * `thinking` block.
+ *   - `thinkingEnabled`  — minimax M3 binary on/off
+ *     (Anthropic `thinking.type = "adaptive" | "disabled"`)
+ *   - `reasoningEffort`  — deepseek v4 three-level
+ *     `none | high | max` scale
+ *   - `none`             — picker hides the thinking dropdown
+ *     entirely (model has no configurable reasoning depth)
+ */
+type ModelThinkingSchema = "thinkingEnabled" | "reasoningEffort" | "none";
+/**
+ * One model that a provider exposes. Stable id within the provider.
+ *
+ * Optional fields beyond `id` + `maxInputTokens` + `maxOutputTokens`
+ * surface in the VSCode chat model picker (Copilot Chat) as the
+ * `detail` / `tooltip` / `statusIcon` / `capabilities` / `inputCost` /
+ * `outputCost` / `cacheCost` / `priceCategory` / `isBYOK` /
+ * `configurationSchema` fields on `LanguageModelChatInformation`.
+ * Missing fields fall back to the curated metadata table in
+ * `MODEL_METADATA` (see `lookupModelMetadata` in
+ * `apps/extension/src/services/providers/LmChatProviderRegistrar.ts`),
+ * so user-added models that omit these fields still work — they
+ * just show up in the picker without the cost column or thinking
+ * dropdown.
+ */
+interface ProviderModel {
+    /** Stable id within the provider (e.g. "deepseek-v4-flash", "MiniMax-M2.7") */
+    id: string;
+    /** Human-readable display name (defaults to id if omitted) */
+    displayName?: string;
+    /** Max input tokens (best-effort, may be approximate) */
+    maxInputTokens?: number;
+    /** Max output tokens */
+    maxOutputTokens?: number;
+    /** Short one-line description for the picker's `detail` column. */
+    detail?: ModelDetail;
+    /** Capability flags (advisory — adapter honors only what it supports) */
+    capabilities?: {
+        supportsImageToText?: boolean;
+        supportsToolCalling?: boolean;
+    };
+    /**
+     * Pricing block. Renders in the picker's `Input` / `Output` /
+     * `Cache Read` columns when this model is selected. Currency is
+     * resolved from `baseUrl` (minimaxi.com / deepseek.com → CNY,
+     * minimax.io / others → USD); the same numeric value is shown
+     * with the resolved currency symbol.
+     */
+    pricing?: ModelPricing;
+    /** Tier tag for the picker's price column (default bucket per upstream). */
+    priceCategory?: ModelPriceCategory;
+    /**
+     * Thinking-dropdown schema the picker renders for this model.
+     * Omit (or set to `none`) to hide the dropdown entirely.
+     */
+    thinkingSchema?: ModelThinkingSchema;
+}
+/**
+ * Persisted provider configuration. `apiKeyRef` is the SecretStorage
+ * key; the actual key never appears in this object after creation
+ * (it's stored under `ms-devtools.providers.<id>.apiKey` and resolved
+ * by `ProviderRegistry.getApiKey(id)`).
+ */
+interface ProviderConfig {
+    /** Stable identifier (UUID v4) — used as SecretStorage key suffix */
+    id: string;
+    /** UI-facing name, e.g. "MiniMax (prod)" */
+    displayName: string;
+    /** Provider type — picks the adapter */
+    type: ProviderType;
+    /** HTTP base URL (no trailing slash) */
+    baseUrl: string;
+    /** Reference to SecretStorage key. Format: "ms-devtools.providers.<id>.apiKey" */
+    apiKeyRef: string;
+    /** Models this provider exposes */
+    models: ProviderModel[];
+    /** Whether this provider is the user's default. At most one at a time. */
+    isDefault?: boolean;
+    /**
+     * Whether this provider is active. `undefined` is treated as
+     * `true` (pre-existing providers persisted before this field
+     * existed default to enabled). Set to `false` to stop the
+     * provider's models from being registered with `vscode.lm`
+     * (see `LmChatProviderRegistrar`) without deleting the provider
+     * config or its SecretStorage-held API key — the user can
+     * re-enable it later without re-entering credentials.
+     */
+    enabled?: boolean;
+    /**
+     * MiniMax billing type for this provider's API key.
+     * `token_plan` — key is on a coding plan; usage can be fetched via the coding_plan API.
+     * `pay_as_you_go` — key is pure pay-as-you-go; no usage API available.
+     * Ignored for non-minimax providers.
+     */
+    minimaxBillingType?: "token_plan" | "pay_as_you_go";
+    /** Created / updated timestamps (informational) */
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Display order hint. Lower values sort first. User-added providers
+     * that never had their order explicitly set default to `0`. Builtin
+     * (`vscode-builtin`) is always injected at position `0` regardless
+     * of this field — its sort order is fixed.
+     */
+    sortOrder?: number;
+}
+/**
+ * Public-facing projection of {@link ProviderConfig}. Strips
+ * `apiKeyRef` and timestamps before crossing the postMessage boundary.
+ *
+ * The Webview never sees the secret reference path; the extension
+ * resolves it at chat time. `hasApiKey` is a boolean only — never
+ * the actual value.
+ */
+type PublicProvider = Omit<ProviderConfig, "apiKeyRef"> & {
+    /** Whether this provider has a key configured (boolean only, never the value) */
+    hasApiKey: boolean;
+};
+/**
+ * Result of a connectivity probe. `ok=true` means credentials +
+ * reachability check passed. `latencyMs` is wall-clock from request
+ * start to first byte (or full response for tiny `/models` calls).
+ * `sampleModelId` is the first model id the provider reported
+ * (helpful when validating "does this base URL serve the models I expect").
+ */
+interface ProviderTestResult {
+    ok: boolean;
+    latencyMs?: number;
+    sampleModelId?: string;
+    error?: string;
+}
+/**
+ * Message types for the providers list. Used in `GetProviders` /
+ * `ProvidersResponse` envelopes.
+ */
+interface ProvidersResponsePayload {
+    providers: PublicProvider[];
+    defaultProviderId: string | null;
+}
+/**
+ * Payload for `AddProvider` / `UpdateProvider`. Does NOT include
+ * `apiKeyRef` (the registry generates it) or `id` (registry assigns
+ * on add; update receives it as a separate `id` field).
+ *
+ * `apiKey` is the user's plaintext key — the registry writes it to
+ * SecretStorage and never echoes it back. Pass empty string to
+ * leave an existing key untouched on update.
+ */
+interface ProviderMutationPayload {
+    id?: string;
+    displayName: string;
+    type: ProviderType;
+    baseUrl: string;
+    apiKey: string;
+    models: ProviderModel[];
+    isDefault?: boolean;
+    /** See {@link ProviderConfig.enabled}. Omit to leave unchanged on update / default to `true` on add. */
+    enabled?: boolean;
+    /** See {@link ProviderConfig.minimaxBillingType}. */
+    minimaxBillingType?: "token_plan" | "pay_as_you_go";
+}
+/** Which vendor API to call for usage data. */
+type ProviderUsageKind = "minimax" | "deepseek" | "kimi" | "zhipu" | "stepfun" | "siliconflow" | "openrouter" | "novita";
+/**
+ * One quota window (5h or weekly) from a coding-plan provider.
+ * `utilizationPercent` is precomputed as `100 - remaining_percent`.
+ */
+interface UsageWindow {
+    /** 0..100 utilization */
+    utilizationPercent: number;
+    /** ISO 8601 reset time */
+    resetsAt: string;
+    /** Precomputed epoch ms (webview convenience) */
+    resetsAtMs: number;
+}
+/** MiniMax `/coding_plan/remains` response, normalised. */
+interface MinimaxUsage {
+    kind: "minimax";
+    /** 5-hour billing window (always present, derived from model_name === "general") */
+    interval: UsageWindow;
+    /** Weekly quota — only present when the account has a weekly cap. */
+    weekly?: UsageWindow;
+}
+/**
+ * Shared coding-plan usage for Kimi / Zhipu (same five_hour + optional weekly structure).
+ * Parsed from their respective API responses into this normalised shape.
+ */
+interface CodingPlanUsage {
+    kind: "kimi" | "zhipu";
+    /** Five-hour billing window */
+    interval: UsageWindow;
+    /** Weekly quota — only present when the account has a weekly cap. */
+    weekly?: UsageWindow;
+}
+/** One currency row in a balance response. */
+interface BalanceEntry {
+    currency: string;
+    totalBalance: number;
+}
+/** DeepSeek-specific balance entry (includes granted + topped-up breakdown). */
+interface DeepseekBalanceEntry {
+    currency: string;
+    totalBalance: number;
+    grantedBalance?: number;
+    toppedUpBalance?: number;
+}
+/** DeepSeek `/user/balance` response, normalised. */
+interface DeepseekUsage {
+    kind: "deepseek";
+    isAvailable: boolean;
+    balances: DeepseekBalanceEntry[];
+}
+/**
+ * Generic balance for StepFun / SiliconFlow / OpenRouter / Novita.
+ * Each provider returns a different response shape; the parse function normalises
+ * all four into this shared interface.
+ */
+interface GenericBalanceUsage {
+    kind: "stepfun" | "siliconflow" | "openrouter" | "novita";
+    balances: BalanceEntry[];
+}
+/** Union of all supported vendor usage shapes. */
+type ProviderUsageData = MinimaxUsage | DeepseekUsage | CodingPlanUsage | GenericBalanceUsage;
+/**
+ * Result of a usage probe. `transient` governs the webview's keep-last-good
+ * strategy: true = network/timeout (retry silently), false = deterministic
+ * (auth/parse/4xx — drop last good, show hard error).
+ */
+type ProviderUsageResult = {
+    ok: true;
+    data: ProviderUsageData;
+    fetchedAtMs: number;
+} | {
+    ok: false;
+    transient: boolean;
+    code: string;
+    message: string;
+};
+/**
+ * Cache_control capability declaration, keyed by provider type.
+ *
+ * `supportsCacheControl` — does that protocol/vendor implementation
+ * claim a stable prompt-prefix cache?
+ *   - Anthropic path: writes body `cache_control: {type:"ephemeral"}` —
+ *     independent of this flag (P0.1 4-breakpoint logic).
+ *   - OpenAI path: writes `prompt_cache_key` HEADER only when this
+ *     flag is `true`. Metadata absence == opt-out (safer than 400).
+ *   - minimax (Anthropic-compat host) → supportsCacheControl:true
+ *     means the upstream honours ephemeral cache.
+ *   - deepseek v4 / agnes (OpenAI-compat) → supportsCacheControl:true
+ *     means the upstream `prompt_cache_key` header is honoured.
+ *   - generic `-compatible` providers (no curated entry) → flag absent
+ *     == entire cache path is SKIPPED. Avoids 400 risk on unknown
+ *     upstreams.
+ */
+interface ProviderCacheControlMetadata {
+    /** Stable prompt-prefix cache declared by the upstream? (OpenAI path reads this) */
+    supportsCacheControl?: boolean;
+}
+/**
+ * A single known-good baseUrl candidate for a provider type, offered
+ * as a dropdown suggestion in the ProvidersTab form. The baseUrl
+ * `<input>` stays freely editable — these are suggestions, not an
+ * enum; the user can always type a custom endpoint.
+ */
+interface ProviderBaseUrlPreset {
+    /** Short human label distinguishing candidates (e.g. "国内" / "全球"). */
+    label: string;
+    baseUrl: string;
+}
+
+/**
+ * Provider-type → known baseUrl candidates (e.g. mainland-China vs.
+ * global endpoints for the same vendor, like Agnes/MiniMax/DeepSeek).
+ * Purely a UI convenience for the Add/Edit form's baseUrl dropdown —
+ * no runtime auto-switching reads this (that mechanism was removed;
+ * see git history for the retired `autoSwitch` feature).
+ */
+declare const PROVIDER_BASE_URL_PRESETS: Readonly<Record<ProviderType, readonly ProviderBaseUrlPreset[]>>;
+/**
+ * Resolve the dropdown candidate list for a provider type. Returns
+ * an empty array (NEVER throws) for `-compatible` types or provider
+ * types the table doesn't cover.
+ */
+declare function getProviderBaseUrlPresets(type: ProviderType): readonly ProviderBaseUrlPreset[];
+
+/**
+ * Provider-type → cache_control capability lookup. Read by the
+ * OpenAI adapter's `prompt_cache_key` decision (T-04) via
+ * {@link isProviderCacheControlAware}.
+ */
+declare const PROVIDER_CACHE_CONTROL_METADATA: Readonly<Record<ProviderType, ProviderCacheControlMetadata>>;
+/**
+ * Does this provider type declare "stable prompt cache" support?
+ * The OpenAI path reads this flag to decide whether to write
+ * `prompt_cache_key`; the Anthropic path uses its own 4-breakpoint
+ * logic and ignores this flag.
+ */
+declare function isProviderCacheControlAware(type: ProviderType): boolean;
+
+declare const MODEL_METADATA: Readonly<Record<string, CuratedModelMetadata>>;
+/**
+ * Look up curated metadata for a model by its un-qualified id
+ * (the part after the last `::` in a qualified id, or the raw id
+ * for a non-namespaced provider). Returns `undefined` for
+ * user-added / `-compatible` models that have no curated entry;
+ * callers should then fall back to whatever the user typed into
+ * the ProvidersTab.
+ */
+declare function lookupModelMetadata(modelId: string): CuratedModelMetadata | undefined;
+/**
+ * Resolve the currency for a baseUrl. Strict hostname match —
+ * `api.minimaxi.com` and `api.minimaxi.cn` map to CNY (the China
+ * platform), `api.minimax.io` maps to USD (the global platform),
+ * `api.deepseek.com` maps to CNY (DeepSeek's regional pricing is
+ * published in CNY on the public docs even though the API is
+ * global), everything else falls back to USD. The match is
+ * exact-host so a typo in the hostname never silently flips
+ * currency.
+ */
+declare function currencyForBaseUrl(baseUrl: string): "USD" | "CNY";
+
+declare const BUILTIN_PROVIDER_PRESETS: Readonly<Record<"minimax" | "deepseek" | "kimi" | "zhipu" | "stepfun" | "siliconflow" | "openrouter" | "novita" | "agnes", {
+    displayName: string;
+    baseUrl: string;
+    models: ProviderModel[];
+}>>;
+/**
+ * Look up the default config (displayName / baseUrl / models) for a
+ * named vendor type. Returns `null` for the `-compatible` family —
+ * those have no canned defaults; the user enters them by hand.
+ */
+declare function getBuiltinProviderPreset(type: ProviderType): {
+    displayName: string;
+    baseUrl: string;
+    models: ProviderModel[];
+} | null;
+
+/**
+ * Shared AI model types.
+ *
+ * Lifted from `apps/extension/src/services/ai/types.ts` so the Webview
+ * (which imports from `@serviceme/devtools-shared`) can use the same contract as
+ * the extension host. Phase 1 only needs these two types; Phase 2
+ * (provider registration) will extend `AIModelInfo` with
+ * provider-specific fields.
+ *
+ * Source plan: docs/architecture/extension-llm-providers.md (v3)
+ */
+/**
+ * Persisted "current model" configuration. Stored in
+ * `context.globalState` and used to select a model from
+ * `vscode.lm.selectChatModels({ vendor, family })`.
+ */
+interface AIModelConfig {
+    vendor: string;
+    family?: string;
+    version?: string;
+}
+/**
+ * Webview-friendly projection of `vscode.LanguageModelChat`.
+ *
+ * `vscode.LanguageModelChat.capabilities` is a lazy method bag; once
+ * we cross the `postMessage` boundary, those function references are
+ * lost. This type freezes the boolean fields we care about so the
+ * Webview can render capability badges (tool calling, image input)
+ * without a second round-trip.
+ */
+interface AIModelInfo {
+    id: string;
+    name: string;
+    vendor: string;
+    family?: string;
+    version?: string;
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+    capabilities?: {
+        supportsImageToText?: boolean;
+        supportsToolCalling?: boolean;
+    };
+}
+
+/**
+ * Certificate bundle download — wire types shared between the certificate
+ * Webview (apps/webview-ui/src/certificate) and the extension panel service
+ * (apps/extension/src/services/view/CertificatePanelService). The actual
+ * conversion work is delegated to the `sslkit` npm package on the extension
+ * side; these types just describe the IPC payload for choosing a target
+ * format and receiving the resulting zip.
+ */
+/** Target formats that the extension can produce via `sslkit`. */
+type CertificateBundleFormat = "pem" | "pfx" | "crt" | "jks";
+/** Static metadata describing each supported bundle format — used by the UI
+ * to render the format picker without hard-coding labels in two places. */
+interface CertificateBundleFormatDescriptor {
+    readonly format: CertificateBundleFormat;
+    /** Short label shown in the picker (e.g. "Nginx PEM"). */
+    readonly label: string;
+    /** One-line description of what the format is for. */
+    readonly description: string;
+    /** Icon name (lucide) for the picker button. */
+    readonly icon: string;
+    /** Whether this format requires a password (PFX / JKS). */
+    readonly requiresPassword: boolean;
+    /** Conventional file extension(s) for the primary artifact(s) the user
+     * is downloading, shown in the picker subtitle. */
+    readonly artifactExtension: string;
+}
+declare const CERTIFICATE_BUNDLE_FORMATS: readonly CertificateBundleFormatDescriptor[];
+/** Request sent from the Webview when the user picks a format. */
+interface DownloadCertificateBundleRequest {
+    id: string;
+    format: CertificateBundleFormat;
+    /** Override for the export password (PFX / JKS only). When omitted, the
+     * extension falls back to the `ms-devtools.certificate.exportPassword`
+     * setting (default "123456", matching `sslkit`). */
+    password?: string;
+}
+/** Response sent back to the Webview — same shape as the existing PEM bundle
+ * download (filename + base64 zip), so the Webview side can reuse its
+ * existing download helper without branching on format. */
+interface DownloadCertificateBundleResponse {
+    success: boolean;
+    filename?: string;
+    mime?: string;
+    base64?: string;
+    error?: string;
+}
+/** Feature availability reported by the extension to the Webview so the UI
+ * can grey out formats whose prerequisites aren't met on this machine. */
+interface CertificateBundleEnvironmentSupport {
+    /** `true` once `sslkit` was resolved via `node_modules/.bin` or PATH. */
+    sslkitAvailable: boolean;
+    /** `true` once `keytool` was found on PATH (required only for JKS). */
+    jdkAvailable: boolean;
+    /** Mirror of `msDevTools.certificate.exportPassword` — surfaces the
+     * effective default so the UI doesn't have to subscribe to config
+     * change events. */
+    defaultPassword: string;
+}
+
+/**
+ * Git URL Utilities
+ *
+ * Pure functions for parsing and validating Git remote URLs into canonical slugs.
+ * No platform-specific logic — suitable for both Node.js and browser environments.
+ */
+/**
+ * Built-in hostname aliases for Git remotes.
+ *
+ * Some users/teams configure `~/.ssh/config` `Host` aliases (e.g. to pick a
+ * specific SSH identity for a work GitHub account) so their remotes read
+ * `git@github-msc:owner/repo.git` instead of `git@github.com:owner/repo.git`.
+ * Resolving these here — rather than only on the client — keeps the server's
+ * independently-recomputed canonical slug (see `ensureRemotesMatchCanonicalSlug`
+ * in `apps/server/src/app/api/v1/projects/_validators.ts`) consistent with
+ * whatever the client already resolved and sent as `canonical_slug`.
+ */
+declare const GIT_REMOTE_HOST_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Apply {@link GIT_REMOTE_HOST_ALIASES} to an already-canonical `host/owner/repo`
+ * slug string (as opposed to a raw Git URL — see `normalizeGitUrl` for that).
+ */
+declare function normalizeCanonicalSlug(slug: string): string;
+/**
+ * Normalize a Git remote URL to a canonical slug: host/owner/repo
+ * - Supports HTTPS, SSH, and SCP-like syntax
+ * - Strips credentials, ports, and .git suffix
+ * - Lowercases host and every path segment
+ * - Resolves known host aliases (see {@link GIT_REMOTE_HOST_ALIASES})
+ *
+ * @throws Error if the input cannot be parsed into a valid slug
+ */
+declare function normalizeGitUrl(input: string): string;
+/**
+ * Validate whether a string matches the canonical slug format: host/owner/repo
+ * Requires at least three segments (host + two path parts).
+ * Allows percent-encoded characters (e.g. %20) for hosts like Azure DevOps
+ * that permit spaces in project/repo names.
+ */
+declare function isValidCanonicalSlug(slug: string): boolean;
+
+interface GitHubUser {
+    id: number;
+    login: string;
+    email: string | null;
+    name: string | null;
+    avatar_url: string | null;
+    plan?: {
+        name: string;
+        space: number;
+        collaborators: number;
+        private_repos: number;
+    };
+    [key: string]: unknown;
+}
+interface GitHubEmailRecord {
+    email: string;
+    primary: boolean;
+    verified: boolean;
+    visibility: "public" | "private" | null;
+}
+type GitHubOrgMembershipStatus = "active" | "pending" | "not_member" | "forbidden" | "unauthorized";
+interface GitHubOrgMembershipCheckResult {
+    status: GitHubOrgMembershipStatus;
+    httpStatus: number;
+    organization: string;
+    role: string | null;
+    directMembership: boolean | null;
+}
+/**
+ * Fetch user info from GitHub API
+ * @param token GitHub Personal Access Token or OAuth Access Token
+ * @returns GitHubUser object
+ * @throws Error if request fails or token is invalid
+ */
+declare function fetchGitHubUser(token: string): Promise<GitHubUser>;
+declare function pickPreferredGitHubEmail(emails: GitHubEmailRecord[]): string | null;
+declare function sanitizeEmail(email: string | null | undefined): string | null;
+declare const __internal: {
+    pickPreferredGitHubEmail: typeof pickPreferredGitHubEmail;
+    sanitizeEmail: typeof sanitizeEmail;
+};
+/**
+ * Fetch the authenticated user's membership details for a GitHub organization.
+ * Uses the memberships list endpoint so callers can distinguish active, pending,
+ * and indeterminate states instead of collapsing everything into a boolean.
+ */
+declare function getGitHubOrgMembership(token: string, org: string): Promise<GitHubOrgMembershipCheckResult>;
+/**
+ * Check if the token owner is authorized for a given GitHub organization.
+ * Uses the authenticated user's own token — works for both public and private membership.
+ * Returns true if the user is active or has a pending invitation, false otherwise.
+ * @param token GitHub Personal Access Token or OAuth Access Token
+ * @param org GitHub organization name
+ */
+declare function checkGitHubOrgMembership(token: string, org: string): Promise<boolean>;
+
+declare function isGitHubLocalEmail(email: string | null | undefined): boolean;
+declare function buildGitHubLocalEmail(login: string): string;
+declare function resolvePrimaryEmail(login: string, email: string | null | undefined): string;
+
+/**
+ * Unified, environment-agnostic logger contract for the SERVICEME monorepo.
+ *
+ * This module intentionally has NO dependency on `vscode`, the extension
+ * runtime, or `@serviceme/devtools-core` so it can be consumed by every
+ * package (shared → protocol → core → cli → webview → extension → server)
+ * without creating cycles or pulling in heavyweight environment-specific
+ * APIs.
+ *
+ * Consumers route their telemetry through an {@link ILogger}:
+ *  - the extension uses the OutputChannel + file-backed `Logger` (see
+ *    `apps/extension/src/core/logger/Logger.ts`);
+ *  - server / cli / webview use the console / postMessage-backed
+ *    implementations provided by their own package, or the
+ *    {@link createConsoleLogger} fallback defined here.
+ */
+/** Severity levels, ordered low → high. */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+/**
+ * The logger contract every package implements / consumes.
+ *
+ * Method signatures are intentionally `(message: string, ...args: unknown[])`
+ * so callers can attach an error object or structured context without
+ * pre-formatting. `error` takes an optional leading `error` argument so the
+ * implementation can normalize / redact it; implementations SHOULD run
+ * {@link normalizeErrorForLog} on that value before emitting.
+ */
+interface ILogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, error?: unknown, ...args: unknown[]): void;
+    setLevel(level: LogLevel): void;
+    /** Optional — file-backed loggers return their directory. */
+    getLogDir?(): string | undefined;
+    /** Optional — UI-backed loggers reveal their sink (e.g. an OutputChannel). */
+    show?(): void;
+}
+/**
+ * Normalize any thrown value into a serializable record for logging.
+ *
+ * Handles `Error` (canonical fields + protocol-level extras), strings,
+ * primitives, and plain objects, so log sinks can `JSON.stringify` the
+ * result without throwing on circular refs or dropping context. This is a
+ * pure function with no environment dependencies and was promoted from
+ * `apps/extension/src/core/logger/Logger.ts` so every package shares one
+ * normalization path.
+ */
+declare function normalizeErrorForLog(error: unknown): Record<string, unknown>;
+/**
+ * Create a console-backed {@link ILogger}.
+ *
+ * - `debug` is gated to `NODE_ENV !== "production"` (verbose traces only in
+ *   dev / test), mirroring the server's legacy `logDebug` behavior.
+ * - `info` / `warn` / `error` always emit to the matching `console` method.
+ * - `error`'s leading `error` argument is run through
+ *   {@link normalizeErrorForLog} so serialized errors stay structured and
+ *   circular-ref safe.
+ *
+ * This is the canonical fallback for packages without a richer sink (cli,
+ * webview bootstrap, extension logger self-diagnostics).
+ */
+declare function createConsoleLogger(name: string): ILogger;
+
+/**
+ * Protocol Contract Types — single source of truth.
+ *
+ * This module is the canonical home for the protocol contract types that are
+ * shared by the devtools protocol package (CLI / core / extension / server),
+ * the webview (`apps/webview-ui`), and `@serviceme/devtools-shared` itself.
+ *
+ * Why this file exists (code-cleanliness Phase 3, T04):
+ *
+ * Previously these types lived in the devtools protocol package and were
+ * re-exported from `@serviceme/devtools-shared`, which forced `@serviceme/devtools-shared` to
+ * depend on the protocol package — an inverted layering (the leaf
+ * shared package should not depend on the richer protocol package). Sinking
+ * the type definitions here makes `@serviceme/devtools-shared` the single source, lets
+ * `@serviceme/devtools-shared` drop its dependency on the protocol package, and lets
+ * the protocol package re-exports these same types (API-stable) from
+ * `@serviceme/devtools-shared`.
+ *
+ * Rules for this file:
+ *
+ * - Self-contained: it must NOT import from the protocol package or
+ *   any runtime package. Only the TypeScript standard lib is allowed.
+ * - Type-only: no runtime values (no enums with runtime behavior, no functions).
+ *   The protocol package keeps the structural validators (`isXxx`) next to
+ *   where they are used.
+ * - Transitive bases are included: a sunk type whose shape references another
+ *   type that is not itself part of the public 19 must also be defined here so
+ *   the module stays self-contained (e.g. `ScheduledTaskV1`, `TaskWorkspaceRef`,
+ *   `TaskRunStatus`, `BridgeLinkMode`).
+ */
+type ScheduledTaskType = "command" | "shell" | "http_request" | "github_copilot_cli";
+interface CommandPayload {
+    command: string;
+    args?: unknown[];
+}
+interface ShellPayload {
+    script: string;
+    cwd?: string;
+    /** Timeout in seconds. Omit for default 60s; use 0 for no limit. */
+    timeout?: number;
+}
+interface HttpRequestPayload {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: string;
+    /** Timeout in seconds. Omit for default 30s; use 0 for no limit. */
+    timeout?: number;
+}
+interface GithubCopilotCliPayload {
+    prompt: string;
+    workspace?: string;
+    autopilot?: boolean;
+    allowTools?: string[];
+    /** Timeout in seconds. Omit for default 300s; use 0 for no limit. */
+    timeout?: number;
+    model?: string;
+    agent?: string;
+}
+type TaskPayload = CommandPayload | ShellPayload | HttpRequestPayload | GithubCopilotCliPayload;
+/** Reference to the workspace a scheduled task is bound to. Required by v2. */
+interface TaskWorkspaceRef {
+    /** Absolute path to the workspace root. Required and unique. */
+    path: string;
+    /** Display name. Defaults to `path` basename; users may override. */
+    name: string;
+    /** `git@github.com:owner/repo.git` — auto-detected at task creation. */
+    gitRemote?: string;
+    /** Current branch — auto-detected at task creation; verified at execute. */
+    gitBranch?: string;
+    /** Last time the extension saw this workspace alive. */
+    lastSeenAt?: string;
+}
+/**
+ * v1 task shape — kept for reading legacy `<workspace>/.serviceme/scheduled-tasks.json`
+ * during migration. New code should always use {@link ScheduledTask} (v2).
+ */
+interface ScheduledTaskV1 {
+    id: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    scheduleType: "cron" | "interval";
+    schedule: string;
+    taskType: ScheduledTaskType;
+    payload: TaskPayload;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Runtime status of the most recent execution for a task. */
+type TaskRunStatus = "ok" | "error" | "skipped";
+/**
+ * v2 scheduled task — adds required `workspace` reference and runtime metadata
+ * fields. See `docs/architecture/skill-agent-v2-repo.md` §14.2.
+ */
+interface ScheduledTask extends ScheduledTaskV1 {
+    /** Required in v2. The workspace this task executes in. */
+    workspace: TaskWorkspaceRef;
+    /** ISO timestamp of the most recent execution. */
+    lastRunAt?: string;
+    /** Status of the most recent execution. */
+    lastRunStatus?: TaskRunStatus;
+    /** Error message from the most recent failed execution. */
+    lastRunError?: string;
+    /** Duration of the most recent execution, in milliseconds. */
+    lastRunDurationMs?: number;
+    /** Next scheduled run (computed by scheduler). */
+    nextRunAt?: string;
+    /** Total successful executions. */
+    runCount?: number;
+}
+/** v2 config — single source of truth for the global scheduler. */
+interface ScheduledTasksConfig {
+    version: 2;
+    tasks: ScheduledTask[];
+}
+type TaskExecutionStatus = "running" | "success" | "failure" | "timeout" | "cancelled";
+interface TaskExecutionLog {
+    id: string;
+    taskId: string;
+    taskName: string;
+    startedAt: string;
+    finishedAt: string;
+    status: Exclude<TaskExecutionStatus, "running">;
+    output?: string;
+    error?: string;
+}
+type AgentToolRiskLevel = "high" | "medium" | "low";
+interface AgentToolPermission {
+    tool: string;
+    riskLevel: AgentToolRiskLevel;
+}
+interface AgentPermissionSummary {
+    agentId: string;
+    agentName: string;
+    tools: AgentToolPermission[];
+    highRiskCount: number;
+    mediumRiskCount: number;
+    lowRiskCount: number;
+}
+/** Kinds of artifacts in the catalog. */
+type BridgeSkillKind = "skill" | "agent";
+/** Which side of the link is reported. Matches SkillLinker's `LinkMode`. */
+type BridgeLinkMode = "symlink" | "junction" | "copy";
+/** A single skill/agent entry inside a repo (SkillStore.SkillEntry). */
+interface BridgeSkillRepoEntry {
+    repoId: string;
+    name: string;
+    kind: BridgeSkillKind;
+    /** Absolute path to the manifest file. */
+    manifestPath: string;
+    /** Absolute path to the entry's directory. */
+    dir: string;
+    /** Best-effort parsed frontmatter. */
+    frontmatter: Record<string, unknown>;
+    /** ISO timestamp of the manifest's mtime. */
+    modifiedAt: string;
+}
+/** A single file inside an entry (SkillStore.SkillFile). */
+interface BridgeSkillRepoFile {
+    /** Path relative to the entry's directory. */
+    path: string;
+    /** UTF-8 content. */
+    content: string;
+}
+/** A symlink/junction currently present in a workspace or user (global) scope. */
+interface BridgeLinkedSkill {
+    repoId: string;
+    name: string;
+    linkPath: string;
+    targetPath: string;
+    mode: BridgeLinkMode;
+    /** Which scope this link lives in — "workspace" or "user" (global, `~/.agents/...`). */
+    scope: "workspace" | "user";
+}
+/** A single entry from `repos.json` (subset of RepoConfig). */
+interface BridgeRepoEntry {
+    id: string;
+    name: string;
+    url: string;
+    branch: string;
+    enabled: boolean;
+    useProxy?: boolean;
+    writeEnabled: boolean;
+    source: "default" | "user";
+    description?: string;
+    addedAt: string;
+    lastSyncAt?: string;
+    lastSyncCommitSha?: string;
+    lastSyncStatus?: "ok" | "error";
+    lastSyncError?: string;
+}
+/** A single line of a sync run. */
+interface BridgeRepoSyncPull {
+    repoId: string;
+    status: "ok" | "error";
+    commitSha?: string;
+    error?: string;
+}
+
+declare enum WebviewMessageType {
+    WebviewReady = "webviewReady",
+    Ready = "ready",
+    Log = "log",
+    ExecuteCommand = "executeCommand",
+    OpenUrl = "openUrl",
+    UsePrompt = "usePrompt",
+    UpdateAzureProfiles = "updateAzureProfiles",
+    UpdateAzureProfile = "updateAzureProfile",
+    GetApiConfig = "getApiConfig",
+    UpdateApiConfig = "updateApiConfig",
+    SaveApiConfig = "saveApiConfig",
+    ApiConfigSaveFailed = "apiConfigSaveFailed",
+    ExportApiConfig = "exportApiConfig",
+    ImportApiConfig = "importApiConfig",
+    ApiConfigImported = "apiConfigImported",
+    AddExternalTool = "addExternalTool",
+    UpdateExternalTool = "updateExternalTool",
+    UpdateExternalTools = "updateExternalTools",
+    DeleteExternalTool = "deleteExternalTool",
+    ReorderExternalTools = "reorderExternalTools",
+    UpdateNgrokStatus = "updateNgrokStatus",
+    UpdateServerStatus = "updateServerStatus",
+    GetAuthState = "getAuthState",
+    UpdateAuthState = "updateAuthState",
+    Login = "login",
+    Logout = "logout",
+    GetAccounts = "getAccounts",
+    UpdateAccounts = "updateAccounts",
+    SwitchAccount = "switchAccount",
+    GetUserProfile = "getUserProfile",
+    UpdateUserProfile = "updateUserProfile",
+    UserProfileUpdated = "userProfileUpdated",
+    AddExtraEmail = "addExtraEmail",
+    DeleteExtraEmail = "deleteExtraEmail",
+    GetCalendarHolidays = "getCalendarHolidays",
+    UpdateCalendarHolidays = "updateCalendarHolidays",
+    GetCalendarLeaves = "getCalendarLeaves",
+    UpdateCalendarLeaves = "updateCalendarLeaves",
+    CreateCalendarLeave = "createCalendarLeave",
+    DeleteCalendarLeave = "deleteCalendarLeave",
+    GetCalendarNotes = "getCalendarNotes",
+    UpdateCalendarNotes = "updateCalendarNotes",
+    SaveCalendarNote = "saveCalendarNote",
+    GetCalendarMonthSchedule = "getCalendarMonthSchedule",
+    GetScheduledTasks = "getScheduledTasks",
+    UpdateScheduledTasks = "updateScheduledTasks",
+    CreateScheduledTask = "createScheduledTask",
+    EditScheduledTask = "editScheduledTask",
+    DeleteScheduledTask = "deleteScheduledTask",
+    ToggleScheduledTask = "toggleScheduledTask",
+    TriggerScheduledTask = "triggerScheduledTask",
+    CancelTaskExecution = "cancelTaskExecution",
+    GetTaskExecutionLogs = "getTaskExecutionLogs",
+    ClearTaskExecutionLogs = "clearTaskExecutionLogs",
+    UpdateTaskExecutionLogs = "updateTaskExecutionLogs",
+    UpdateTaskExecutionState = "updateTaskExecutionState",
+    GetCurrentWorkspace = "getCurrentWorkspace",
+    UpdateCurrentWorkspace = "updateCurrentWorkspace",
+    GetProviders = "getProviders",
+    ProvidersResponse = "providersResponse",
+    AddProvider = "addProvider",
+    UpdateProvider = "updateProvider",
+    RemoveProvider = "removeProvider",
+    SetDefaultProvider = "setDefaultProvider",
+    SetProviderEnabled = "setProviderEnabled",
+    SetProviderOrder = "setProviderOrder",
+    TestProvider = "testProvider",
+    ProviderTestResultMessage = "providerTestResult",
+    DefaultProviderChanged = "defaultProviderChanged",
+    FetchProviderModels = "fetchProviderModels",
+    FetchProviderModelsResult = "fetchProviderModelsResult",
+    GetProviderUsage = "getProviderUsage",
+    ProviderUsageResponse = "providerUsageResponse",
+    SetCacheControlEnabled = "setCacheControlEnabled",
+    GetByomSettings = "getByomSettings",
+    ByomSettingsResponse = "byomSettingsResponse",
+    ListSkillRepoEntries = "listSkillRepoEntries",
+    GetSkillRepoEntry = "getSkillRepoEntry",
+    InstallSkillRepoEntry = "installSkillRepoEntry",
+    ConvertSkillRepoEntryToSymlink = "convertSkillRepoEntryToSymlink",
+    UninstallSkillRepoEntry = "uninstallSkillRepoEntry",
+    ListLinkedSkills = "listLinkedSkills",
+    UpdateSkillRepoCatalog = "updateSkillRepoCatalog",
+    UpdateSkillRepoInstall = "updateSkillRepoInstall",
+    UpdateLinkedSkills = "updateLinkedSkills",
+    CreateSkillRepoDraft = "createSkillRepoDraft",
+    CommitSkillRepoDraft = "commitSkillRepoDraft",
+    ListSkillRepoDrafts = "listSkillRepoDrafts",
+    DeleteSkillRepoDraft = "deleteSkillRepoDraft",
+    UpdateSkillRepoDraft = "updateSkillRepoDraft",
+    ListRepositories = "listRepositories",
+    AddRepository = "addRepository",
+    UpdateRepository = "updateRepository",
+    RemoveRepository = "removeRepository",
+    EnableRepository = "enableRepository",
+    DisableRepository = "disableRepository",
+    SyncRepository = "syncRepository",
+    SyncAllRepositories = "syncAllRepositories",
+    UpdateRepositoryList = "updateRepositoryList",
+    UpdateRepositoryAdd = "updateRepositoryAdd",
+    UpdateRepositoryUpdate = "updateRepositoryUpdate",
+    UpdateRepositoryRemove = "updateRepositoryRemove",
+    UpdateRepositoryToggle = "updateRepositoryToggle",
+    UpdateRepositorySyncResult = "updateRepositorySyncResult",
+    GetUtilityModels = "getUtilityModels",
+    UtilityModelsResponse = "utilityModelsResponse",
+    UpdateUtilityModels = "updateUtilityModels",
+    GetServerProxyState = "getServerProxyState",
+    ServerProxyStateResponse = "serverProxyStateResponse",
+    SetServerProxyEnabled = "setServerProxyEnabled",
+    SetServerProxyAllowOverride = "setServerProxyAllowOverride",
+    GetCachedServerUrl = "getCachedServerUrl",
+    CachedServerUrlResponse = "cachedServerUrlResponse"
+}
+/**
+ * Top-level const aliases for the BYO Utility Models message-type
+ * members above. Re-exported as `export const` (rather than just enum
+ * members) because `@serviceme/devtools-shared` ships as CommonJS — bare
+ * `import { GetUtilityModels } from "@serviceme/devtools-shared"` from an ESM
+ * module resolves to `undefined` unless the binding is also exported
+ * as a top-level const. The webview's vitest tests compare against
+ * these by reference; without the const aliases, every
+ * `c[0] === UpdateUtilityModels` check matches the mount-time
+ * `vscode.post(GetUtilityModels)` call (because `undefined ===
+ * undefined` is true). Keep both the enum members AND the consts in
+ * sync; Task 5 (extension handler) uses the enum members, the webview
+ * component + tests use the consts.
+ */
+declare const GetUtilityModels: "getUtilityModels";
+declare const UtilityModelsResponse: "utilityModelsResponse";
+declare const UpdateUtilityModels: "updateUtilityModels";
+declare const SetCacheControlEnabled: "setCacheControlEnabled";
+declare const GetByomSettings: "getByomSettings";
+declare const ByomSettingsResponse: "byomSettingsResponse";
+declare const GetServerProxyState: "getServerProxyState";
+declare const ServerProxyStateResponse: "serverProxyStateResponse";
+declare const SetServerProxyEnabled: "setServerProxyEnabled";
+declare const SetServerProxyAllowOverride: "setServerProxyAllowOverride";
+declare const GetCachedServerUrl: "getCachedServerUrl";
+declare const CachedServerUrlResponse: "cachedServerUrlResponse";
+/**
+ * Snapshot of the r7 server-proxy toggle (HTTP CONNECT through intranet
+ * Server). Mirrors `IProxyConfigService`'s `ProxyState` shape so the
+ * webview can render the same fields without a reshape.
+ *
+ * Returned by `GetServerProxyState` and broadcast as
+ * `ServerProxyStateResponse` so the ProvidersTab's ServerProxyToggle
+ * component can paint at the persisted state on mount.
+ *
+ * See `apps/extension/src/services/proxy/ProxyConfigService.ts` for
+ * the authoritative source of truth.
+ */
+type ServerProxySupportMode = "off" | "on" | "fallback" | "override";
+interface ServerProxySnapshot {
+    httpProxy: string | undefined;
+    httpProxyStrictSSL: boolean;
+    httpProxySupport: ServerProxySupportMode;
+    /** Self-flag at serverProxy.enabled; computed by the extension handler. */
+    enabled: boolean;
+    /**
+     * rev.21 — opt-in to bypass the `proxySupport === "override"`
+     * guard. Power users (e.g. corp environments that WANT all
+     * extensions including GitHub Copilot Chat to route through the
+     * corp tunnel) tick the "Allow under proxySupport=override"
+     * checkbox in the Webview; this flag is persisted to
+     * `~/.serviceme/server-proxy.json` alongside `enabled`.
+     */
+    allowOverride: boolean;
+    /** Last server URL we toggled ON with. Used for re-toggling and UI hint. */
+    lastServerUrl?: string;
+}
+/**
+ * Payload for `SetServerProxyEnabled`. The extension handler is the
+ * sole owner of `http.proxy` writes — the webview only sends the
+ * desired state + (optional) target scope. Server URL is normally read
+ * from the snapshot the webview already received via
+ * `ServerProxyStateResponse`; if missing, the handler rejects with
+ * `serverProxy.error.missingServerUrl`.
+ *
+ * `serverUrl` is an OVERRIDE: when supplied, the handler uses it
+ * instead of the snapshot's `http.proxy` for the `enable` write
+ * path. The Webview's "Use Cached Base URL" affordance relies on this
+ * so the cached `ServerConnectionService.getBaseUrl()` value gets
+ * applied as `http.proxy` even when `http.proxy` is currently empty.
+ * Still subject to the `proxySupport !== "override"` server-side gate.
+ */
+interface ServerProxyTogglePayload {
+    enabled: boolean;
+    /** Optional — defaults to Workspace. */
+    target?: "workspace" | "global";
+    /**
+     * Optional — override the snapshot's `http.proxy` for the write.
+     * Only honoured when `enabled === true`; ignored on disable so the
+     * existing "only clear our own write" semantics stay intact.
+     */
+    serverUrl?: string;
+}
+/**
+ * rev.21 — payload for `SetServerProxyAllowOverride`. Toggles the
+ * `serverProxy.allowOverride` self-flag in `~/.serviceme/server-proxy.json`.
+ * Persisted across VS Code restarts; defaults to `false` so users
+ * must explicitly opt-in to the `override` mode bypass.
+ */
+interface ServerProxyAllowOverridePayload {
+    allowOverride: boolean;
+}
+/**
+ * Reply to `GetCachedServerUrl`. Carries the cached base URL resolved
+ * by `ServerConnectionService` (probe + cache of `SERVER_URL_CANDIDATES`)
+ * and the same `proxySupport` snapshot for the UI to gate the
+ * "Apply" button.
+ *
+ * `baseUrl: null` means the candidate probe has not yet resolved a
+ * reachable Server — the Webview should hide the "Apply cached base
+ * URL" affordance rather than offer a no-op button.
+ */
+interface CachedServerUrlSnapshot {
+    baseUrl: string | null;
+    httpProxySupport: ServerProxySupportMode;
+}
+/**
+ * Where the three `msDevTools.utilityModels.*` settings (and their
+ * derived `chat.*` mirrors) are persisted.
+ *
+ * - `"user"` — VS Code `ConfigurationTarget.Global`. Persists across
+ *   workspaces; the user's "default utility model setup".
+ * - `"workspace"` — VS Code `ConfigurationTarget.Workspace`. Persists
+ *   to `<workspace>/.vscode/settings.json` only; overrides the user
+ *   scope when the workspace file explicitly sets a key.
+ *
+ * VS Code itself implements multi-scope fallback (a workspace value
+ * wins over a user value when both are present), so we only need to
+ * write to ONE target — the other scope just naturally inherits.
+ */
+type UtilityModelScope = "user" | "workspace";
+/**
+ * Per-field source for UI "this value comes from user / workspace /
+ * default" indicators. Mirrors the `ConfigurationInspectionScope`
+ * categories of `vscode.WorkspaceConfiguration.inspect(key)`.
+ */
+interface UtilityModelsSource {
+    small: "user" | "workspace" | "default";
+    medium: "user" | "workspace" | "default";
+    fallbackToCopilot: "user" | "workspace" | "default";
+}
+/**
+ * The value Copilot is ACTUALLY using right now — VS Code's real
+ * merged resolution (workspace always wins over user when both are
+ * set), independent of which scope tab the UI currently has selected
+ * for editing. Computed via `configSection.get(key, default)`, the
+ * same call VS Code itself uses to resolve a setting.
+ */
+interface UtilityModelsEffective {
+    small: string;
+    medium: string;
+    fallbackToCopilot: boolean;
+}
+/**
+ * Snapshot of the three msDevTools.utilityModels.* settings plus the
+ * currently-enabled BYO model list (qualified `${providerId}::${modelId}`
+ * ids, sorted, deduplicated). Returned by GetUtilityModels and by
+ * UpdateUtilityModels after a successful write.
+ *
+ * - `scope` is the SCOPE THE WEBVIEW LAST WROTE / the scope the handler
+ *   will use for the next write. Computed from
+ *   `configSection.inspect(...)` per field and reduced to a single
+ *   scope: if ANY field is overridden at the workspace level, the
+ *   UI surfaces "workspace" (the user is actively overriding at
+ *   workspace scope). Otherwise "user".
+ * - `source` lets the UI render per-field origin badges without
+ *   re-running `inspect()` client-side.
+ * - `small` / `medium` / `fallbackToCopilot` are the values stored AT
+ *   `scope` specifically — used to populate the editing dropdowns for
+ *   whichever scope tab is selected. `effective` is the SEPARATE,
+ *   real merged value Copilot uses; the collapsed-section summary
+ *   badges must read from `effective`, not from these fields, so the
+ *   title always shows what's actually in effect regardless of which
+ *   scope tab happens to be open.
+ */
+interface UtilityModelsSnapshot {
+    small: string;
+    medium: string;
+    fallbackToCopilot: boolean;
+    enabledModelIds: string[];
+    /** Effective scope for the next write. Defaults to `"user"`. */
+    scope: UtilityModelScope;
+    /** Per-field source (which scope actually defined the value). */
+    source?: UtilityModelsSource;
+    /** The real merged value Copilot uses right now. See docstring above. */
+    effective: UtilityModelsEffective;
+}
+/**
+ * Partial-update payload for UpdateUtilityModels. Omit a field to
+ * leave it untouched; supply `""` to write the empty string (the user
+ * wants the slot cleared).
+ *
+ * `scope` is the persistence target for the write. Omit it to keep
+ * the previous scope; the first call (with no prior scope) defaults
+ * to `"user"`.
+ */
+interface UpdateUtilityModelsPayload {
+    small?: string;
+    medium?: string;
+    fallbackToCopilot?: boolean;
+    scope?: UtilityModelScope;
+}
+/**
+ * Per-provider BYOM toggle payload. Used by `SetCacheControlEnabled` —
+ * the extension handler writes the `cacheEnabled` key for the given
+ * provider id.
+ *
+ * The handler writes through `byomSettings.ts` so the
+ * `cacheEnabled` flag lands at the same
+ * `msDevTools.byom.<providerId>.<key>` key that the
+ * `LmChatProviderRegistrar` already reads on every chat invocation.
+ */
+interface ByomTogglePayload {
+    id: string;
+    enabled: boolean;
+}
+/**
+ * Snapshot of every BYOM provider's runtime toggles, keyed by
+ * providerId. Returned by `GetByomSettings` and broadcast as
+ * `ByomSettingsResponse` so the Webview can hydrate the per-provider
+ * cache_control switch at mount time without a per-provider
+ * round-trip.
+ *
+ * Providers that have never been touched fall through to the
+ * `byomSettings.ts` default (`cacheEnabled: true`) — the Webview
+ * does NOT need a separate "default" branch.
+ */
+type ByomSettingsSnapshot = Record<string, ByomProviderToggles>;
+/**
+ * Per-provider BYOM toggles. Mirrors the runtime contract in
+ * `apps/extension/src/services/providers/byomSettings.ts`
+ * (`ByomProviderToggles`) — keep the two in lock-step so a
+ * `GetByomSettings` payload round-trips without reshape code.
+ */
+interface ByomProviderToggles {
+    /** P0.1 + P0.2 cache toggle — default TRUE (main-line decision Q1). */
+    cacheEnabled: boolean;
+}
+/**
+ * Strict-typed shape for the inbound messages currently handled by
+ * `useAppMessages`. Stage 1 deliberately covers ONLY the variants whose
+ * payload types already live in `@serviceme/devtools-shared`
+ * (re-exported from the package index via `types/protocol-contracts` as
+ * `BridgeRepoEntry` / `BridgeSkillRepoEntry`) or here as named types
+ * (`LinkedSkillPayloadEntry`). The variants whose payload types live in
+ * `apps/webview-ui/src/types` (ExternalTool, AzureProfile, ApiConfig) stay
+ * on the enum path for now — moving those types into `@serviceme/devtools-shared` is
+ * its own refactor and not in scope.
+ *
+ * Each variant lists ONLY the fields the hook actually reads; optional
+ * fields are explicit (`workspaceOpen` on `UpdateSkillRepoCatalog`).
+ */
+type WebviewInboundMessage = {
+    type: typeof WebviewMessageType.UpdateRepositoryList;
+    repos: BridgeRepoEntry[];
+} | {
+    type: typeof WebviewMessageType.UpdateRepositoryUpdate;
+    repos: BridgeRepoEntry[];
+} | {
+    type: typeof WebviewMessageType.UpdateSkillRepoCatalog;
+    entries?: BridgeSkillRepoEntry[];
+    workspaceOpen?: boolean;
+} | {
+    type: typeof WebviewMessageType.UpdateLinkedSkills;
+    links: LinkedSkillPayloadEntry[];
+    kind: "skill" | "agent";
+};
+/**
+ * One entry inside the `UpdateLinkedSkills.links` array. Mirrors the
+ * inline cast in `useAppMessages.ts:102-106`. Keeping it named (rather
+ * than re-declared at the call site) lets the discriminated union's
+ * `links` field carry a real type instead of `unknown[]`.
+ */
+interface LinkedSkillPayloadEntry {
+    repoId: string;
+    name: string;
+    scope?: string;
+}
+
+/** Live execution state pushed to webview during task execution */
+interface TaskExecutionState {
+    executionId: string;
+    taskId: string;
+    taskName: string;
+    status: "running" | "success" | "failure" | "timeout" | "cancelled";
+    startedAt: string;
+    finishedAt?: string;
+    output: string;
+    error?: string;
+}
+/** Log file schema for .serviceme/scheduled-tasks-log.json */
+interface ScheduledTasksLogFile {
+    version: 1;
+    logs: TaskExecutionLog[];
+}
+
+/**
+ * Environment-agnostic cast helpers.
+ *
+ * These centralize the handful of `as unknown as` / `JSON.parse` fallbacks
+ * that used to be scattered across the codebase. They are intentionally
+ * thin wrappers that preserve the exact runtime behavior of the original
+ * inline casts — they exist for consistency and discoverability, not to
+ * change semantics. No `protocol`-level imports are used here so the helpers
+ * stay usable from any package (extension, server, webview) without pulling
+ * in transport types.
+ */
+/**
+ * Narrow an unknown payload into a typed shape.
+ *
+ * Equivalent to `raw as T`. Retains the original "blind cast" semantics used
+ * for scheduled-task payloads: callers own the contract and we do not validate
+ * the runtime shape here. Keeping the cast in one place makes the intent
+ * (and the assumption) explicit and grep-able.
+ */
+declare function parsePayload<T>(raw: unknown): T;
+/**
+ * Best-effort extraction of an `AbortSignal` from an inbound request object.
+ *
+ * The original code read `req.signal` via `req as unknown as { signal?: AbortSignal }`,
+ * which would return whatever sat on `.signal` — including a non-`AbortSignal`
+ * value. To avoid leaking an invalid signal into downstream `fetch`/`undici`
+ * calls (where a non-`AbortSignal` signal throws), we only return the value when
+ * it is a genuine `AbortSignal` instance; otherwise we return `undefined`, which
+ * is the same as "no signal". In practice the request signal is always a real
+ * `AbortSignal`, so behavior is unchanged for every production path.
+ */
+declare function asAbortSignal(input: unknown): AbortSignal | undefined;
+/**
+ * Parse a JSON string, returning `fallback` when parsing fails.
+ *
+ * Equivalent to wrapping `JSON.parse(text)` in a try/catch. Used to replace
+ * the previous `response.json().catch(() => ({}))` patterns (callers pair this
+ * with their own `.catch` so that a body-read failure still yields the same
+ * fallback as a malformed-body failure).
+ */
+declare function safeJson<T>(text: string, fallback: T): T;
+
+export { type AIModelConfig, type AIModelInfo, type AgentPermissionSummary, type AgentToolPermission, type AgentToolRiskLevel, BUILTIN_PROVIDER_PRESETS, type BalanceEntry, type BridgeLinkMode, type BridgeLinkedSkill, type BridgeRepoEntry, type BridgeRepoSyncPull, type BridgeSkillKind, type BridgeSkillRepoEntry, type BridgeSkillRepoFile, type ByomProviderToggles, ByomSettingsResponse, type ByomSettingsSnapshot, type ByomTogglePayload, CERTIFICATE_BUNDLE_FORMATS, CachedServerUrlResponse, type CachedServerUrlSnapshot, type CertificateBundleEnvironmentSupport, type CertificateBundleFormat, type CertificateBundleFormatDescriptor, type CodingPlanUsage, type CommandPayload, type CuratedModelMetadata, type DeepseekBalanceEntry, type DeepseekUsage, type DownloadCertificateBundleRequest, type DownloadCertificateBundleResponse, GIT_REMOTE_HOST_ALIASES, type GenericBalanceUsage, GetByomSettings, GetCachedServerUrl, GetServerProxyState, GetUtilityModels, type GitHubOrgMembershipCheckResult, type GitHubOrgMembershipStatus, type GitHubUser, type GithubCopilotCliPayload, type HttpRequestPayload, type ILogger, type LinkedSkillPayloadEntry, LogLevel, MODEL_METADATA, type MinimaxUsage, type ModelDetail, type ModelPriceCategory, type ModelPricing, type ModelThinkingSchema, PROVIDER_BASE_URL_PRESETS, PROVIDER_CACHE_CONTROL_METADATA, type ProviderBaseUrlPreset, type ProviderCacheControlMetadata, type ProviderConfig, type ProviderModel, type ProviderMutationPayload, type ProviderTestResult, type ProviderType, type ProviderUsageData, type ProviderUsageKind, type ProviderUsageResult, type ProvidersResponsePayload, type PublicProvider, type ScheduledTask, type ScheduledTaskType, type ScheduledTaskV1, type ScheduledTasksConfig, type ScheduledTasksLogFile, type ServerProxyAllowOverridePayload, type ServerProxySnapshot, ServerProxyStateResponse, type ServerProxySupportMode, type ServerProxyTogglePayload, SetCacheControlEnabled, SetServerProxyAllowOverride, SetServerProxyEnabled, type ShellPayload, type TaskExecutionLog, type TaskExecutionState, type TaskExecutionStatus, type TaskPayload, type TaskRunStatus, type TaskWorkspaceRef, UpdateUtilityModels, type UpdateUtilityModelsPayload, type UsageWindow, type UtilityModelScope, type UtilityModelsEffective, UtilityModelsResponse, type UtilityModelsSnapshot, type UtilityModelsSource, type WebviewInboundMessage, WebviewMessageType, __internal, asAbortSignal, buildGitHubLocalEmail, checkGitHubOrgMembership, createConsoleLogger, currencyForBaseUrl, fetchGitHubUser, getBuiltinProviderPreset, getGitHubOrgMembership, getProviderBaseUrlPresets, isGitHubLocalEmail, isProviderCacheControlAware, isValidCanonicalSlug, lookupModelMetadata, normalizeCanonicalSlug, normalizeErrorForLog, normalizeGitUrl, parsePayload, resolvePrimaryEmail, safeJson };