@stackstackstack/dsh-llm-pi-ai 0.1.5

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@stackstackstack/dsh-llm-pi-ai`.
+* @module @stackstackstack/dsh-llm-pi-ai/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-llm-pi-ai";
+/** Cordis companion plugin name. */
+const name = "llm-pi-ai-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/adapter.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Generic pi-ai-backed implementation of the Harness LLM seam.
+ *
+ * Each resolution produces one **immutable** snapshot — the profiles plus a
+ * `Models` collection holding the `Provider` each route built — and an
+ * operation captures a whole snapshot before its first `await`. A
+ * configuration change builds a *new* collection rather than mutating the one
+ * in use, because `Models.streamSimple()` is lazy: it resolves the provider
+ * when the stream is first consumed, which is after the credential await, so a
+ * mutated collection would let a request that started under one configuration
+ * finish under another — or fail with a provider that no longer exists. This is
+ * what makes the seam's per-step call freeze (`llm.prepareCall()`) hold all the
+ * way down: switching models mid-reply takes effect on the next step, never
+ * inside the one in flight.
+ *
+ * Credentials stay outside that collection. The harness resolves a route's key
+ * through its own seam and passes it as the request's `apiKey` option, which
+ * pi-ai treats as the highest-priority auth override — so `Models` never holds
+ * a credential store and the harness keeps its fail-loud reference semantics.
+ *
+ * @module dsh-llm-pi-ai/adapter
+ */
+import { LlmAdapter } from '@stackstackstack/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ResolvedRetryPolicy, StreamChunk } from '@stackstackstack/dsh-llm';
+import type { AttachmentStore } from '@stackstackstack/dsh-attachment';
+import type { ResolvedPiAiProviderProfile } from './config.ts';
+/** Constructor options for {@link PiAiAdapter}: the two resolution hooks the plugin owns. */
+export interface PiAiAdapterOptions {
+    /** Current validated profiles by provider route; called once per operation. */
+    profiles: () => ReadonlyMap<string, ResolvedPiAiProviderProfile>;
+    /**
+     * Resolve the credential for one already-resolved profile; called once per
+     * stream call and frozen for that call. `undefined` defers to the route's own
+     * pi-ai auth, which for an installed catalog route is its provider-native
+     * ambient discovery; the plugin allows that only for a profile naming no
+     * credential at all, because a named reference that misses throws `LlmError`
+     * `MISSING_CREDENTIAL` rather than falling back.
+     */
+    resolveApiKey: (provider: string, profile: ResolvedPiAiProviderProfile) => Promise<string | undefined>;
+    /** Resolve the optional durable attachment service at request time. */
+    resolveAttachments?: () => AttachmentStore | undefined;
+}
+/**
+ * pi-ai-backed multi-provider adapter. Each operation reads the current
+ * profiles, so a configuration change reaches the next request without a
+ * restart; model descriptors come from the collection those profiles built.
+ */
+export declare class PiAiAdapter extends LlmAdapter {
+    private readonly config;
+    private snapshot;
+    constructor(config: PiAiAdapterOptions);
+    /**
+     * The snapshot for the current profiles. Resolution memoizes its result, so
+     * an unchanged configuration is recognized by identity; a changed one gets a
+     * brand-new collection, leaving any snapshot an operation already captured
+     * untouched for as long as that operation holds it.
+     */
+    private current;
+    /** The profile for one route within one snapshot, or the not-owned failure. */
+    private profileOf;
+    /** The configured descriptor for one exact route/model pair within one snapshot. */
+    private modelOf;
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(provider: string): ResolvedRetryPolicy | undefined;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/lib/types/catalog.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Materialization of one provider route's model catalog. The installed pi-ai
+ * catalog supplies defaults keyed by model id, and a profile's own model
+ * entries override them field by field, so a route naming a catalog provider
+ * stays configuration-free while a route pi-ai has never heard of is fully
+ * describable from `settings.yaml`.
+ *
+ * Every pi-ai `Model` field the harness cannot default is required here rather
+ * than at request time: an unserviceable route fails while its configuration is
+ * being resolved, which is the earliest point that can name the offending key.
+ *
+ * @module dsh-llm-pi-ai/catalog
+ */
+import type { Api, Model, ModelThinkingLevel, OpenAICompletionsCompat, Provider } from '@earendil-works/pi-ai';
+/** One request modality a pi-ai model may accept. */
+export type PiAiModality = Model<Api>['input'][number];
+/** Every request modality a profile may declare. */
+export declare const MODALITIES: readonly PiAiModality[];
+/** Every pi-ai thinking level a profile may declare, in escalation order. */
+export declare const THINKING_LEVELS: readonly ModelThinkingLevel[];
+/** The `compat.thinkingFormat` spellings pi-ai accepts on an `openai-completions` model. */
+type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>;
+/**
+ * pi-ai thinking formats a profile cannot name: both drive the request through
+ * `chatTemplateKwargs`, which this configuration does not expose.
+ */
+type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template';
+/** One reasoning-dispatch wire format a profile may name. */
+export type PiAiThinkingFormat = Exclude<PiThinkingFormat, WithheldThinkingFormat>;
+/** Reasoning-dispatch wire formats a profile may name, most-reached first. */
+export declare const SUPPORTED_THINKING_FORMATS: readonly PiAiThinkingFormat[];
+/**
+ * The installed catalog provider for one route, when pi-ai ships one.
+ * @param provider - provider route key.
+ * @returns the catalog provider, or `undefined` for a route pi-ai does not ship.
+ */
+export declare function catalogProvider(provider: string): Provider | undefined;
+/**
+ * Every provider route the installed pi-ai catalog ships.
+ * @returns the catalog provider ids.
+ */
+export declare function catalogProviderIds(): readonly string[];
+/**
+ * Whether the installed catalog provider for one route declares an api-key
+ * method — the only authentication this adapter obtains on its own.
+ *
+ * A key is what the harness resolves through its own credential seam and hands
+ * pi-ai per request. pi-ai's other method, OAuth, resolves from a *stored*
+ * OAuth credential alone: `resolveProviderAuth` has no ambient path for it,
+ * this adapter builds its `Models` collection with no credential store, and
+ * nothing here runs a login flow. So a provider offering OAuth by itself
+ * leaves nothing for this adapter to authenticate with, and the posture such a
+ * provider invites — no key configured, credentials discovered by the provider
+ * — fails every request with `Provider is not configured`.
+ * @param provider - provider route key.
+ * @returns whether the catalog provider takes an api key; false for a route
+ *   pi-ai does not ship, which the caller answers for separately.
+ */
+export declare function catalogProviderTakesApiKey(provider: string): boolean;
+/**
+ * The installed catalog models for one route, indexed by model id.
+ * @param provider - provider route key.
+ * @returns catalog models by id; empty for a route pi-ai does not ship.
+ */
+export declare function catalogModels(provider: string): Map<string, Model<Api>>;
+/**
+ * Selectable reasoning efforts for one model: each key is a level the model
+ * offers (and selectors show), and its value is the wire spelling dispatch
+ * sends for it. `off` alone may leave its value empty — "supported, send
+ * nothing" — because for most providers not thinking is the parameter's
+ * absence; every other declared level must name a wire value. A level absent
+ * from the dict is not offered.
+ */
+export type PiAiReasoningEfforts = Partial<Record<ModelThinkingLevel, string | null>>;
+/**
+ * Reasoning-dispatch compatibility switches, set on the route (its models'
+ * default) or per model (winning over the route). Only the switches pi-ai's
+ * reasoning dispatch reads are offered; the rest of pi-ai's compat surface
+ * keeps its baseURL-derived auto-detection. pi-ai types both fields only on
+ * `OpenAICompletionsCompat` — the other wire protocols define their reasoning
+ * fields in the protocol itself — so resolution rejects a model-level switch
+ * anywhere else, while a route-level default skips past models it cannot fit.
+ */
+export interface PiAiCompatProfile {
+    /** Reasoning parameter format the endpoint expects; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+    thinkingFormat?: PiAiThinkingFormat;
+    /** Whether the endpoint accepts `reasoning_effort`; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+    supportsReasoningEffort?: boolean;
+}
+/** One configured model entry: an id plus the catalog fields it overrides. */
+export interface PiAiModelProfile {
+    /** Model id sent to the provider and accepted by {@link GenerateOptions.model}. */
+    id: string;
+    /** Display name for selectors; defaults to the catalog name, then the id. */
+    name?: string;
+    /** Maximum combined request and response context in tokens. */
+    contextWindow?: number;
+    /**
+     * Maximum output tokens. Configuring one also makes it this model's
+     * per-request default; a value inherited from the installed catalog, or the
+     * route's fallback, is the model's capability and never becomes a request
+     * default on its own.
+     */
+    maxTokens?: number;
+    /**
+     * Request modalities this model accepts. Absent — or empty, which describes
+     * a model that accepts nothing and so states no answer either — keeps the
+     * installed catalog entry's modalities, then the route's `defaultInput`.
+     * Declaring images is what makes a hand-declared vision model usable, and
+     * declaring text alone corrects a catalog model whose gateway does not serve
+     * what the catalog records. This is a claim about the endpoint, not a check
+     * of it: nothing interrogates a gateway for what it accepts, so a model
+     * claiming images its endpoint refuses is refused by the provider instead,
+     * mid-turn.
+     */
+    input?: PiAiModality[];
+    /**
+     * Selectable reasoning efforts. Absent inherits the installed catalog
+     * entry's capability (a hand-declared model has none and does not reason);
+     * `false` declares a non-reasoning model, which is how a profile strips
+     * reasoning from a catalog model its gateway cannot serve; a non-empty dict
+     * declares the offered levels and their wire spellings.
+     */
+    reasoningEfforts?: false | PiAiReasoningEfforts;
+    /** Reasoning-dispatch switches for this model, winning over the route's. */
+    compat?: PiAiCompatProfile;
+}
+/**
+ * Customization of one installed catalog model, keyed by its id in the
+ * route's `modelOverrides` dict — the same fields a `models` entry may set,
+ * with the id living in the key. Unlike a `models` list, overrides leave the
+ * rest of the catalog serving untouched, which is what makes "correct one
+ * model, keep the other thirty-seven" a three-line edit.
+ */
+export type PiAiModelOverride = Omit<PiAiModelProfile, 'id'>;
+/** The route-level facts model materialization reads. */
+export interface RouteCatalogRequest {
+    /** Provider route key, stamped onto every materialized model. */
+    provider: string;
+    /** Wire protocol override; absent defers to each catalog model's own API. */
+    api?: string;
+    /** Endpoint override; absent defers to the catalog model, then the catalog provider. */
+    baseURL?: string;
+    /** Configured catalog; absent means the whole installed catalog for this route. */
+    models?: readonly PiAiModelProfile[];
+    /** Installed-catalog customizations by model id; only meaningful while `models` is absent. */
+    modelOverrides?: Readonly<Record<string, PiAiModelOverride>>;
+    /** Reasoning-dispatch switches for every `openai-completions` model on the route; entries override per field. */
+    compat?: PiAiCompatProfile;
+    /** Context capacity for a model neither the entry nor the catalog sizes. */
+    defaultContextWindow: number;
+    /** Output capability for a model neither the entry nor the catalog sizes. */
+    defaultMaxTokens: number;
+    /** Modalities for a model neither the entry nor the catalog declares. */
+    defaultInput: Model<Api>['input'];
+}
+/** One route's materialized catalog, plus the request caps its profile chose. */
+export interface RouteCatalog {
+    /** The materialized models in configuration order. */
+    models: readonly Model<Api>[];
+    /**
+     * Per-request output caps this profile explicitly configured, by model id.
+     *
+     * Separate from `Model.maxTokens` because the two answer different
+     * questions: pi-ai requires `maxTokens` as the model's output *capability*,
+     * while the harness seam's `defaultMaxTokens` is a cap the deployment chose
+     * to send on requests that name none. Materializing a catalog capability as
+     * a request default would start capping every request at a number nobody
+     * picked, so only an explicit configuration lands here.
+     */
+    configuredMaxTokens: ReadonlyMap<string, number>;
+}
+/**
+ * Materialize one route's catalog by merging the installed catalog defaults
+ * under the configured entries. A route with no configured `models` serves the
+ * installed catalog unchanged, which is what keeps an existing
+ * `providers: { deepseek: { apiKeyEnv: … } }` profile working untouched.
+ * @param request - the route-level catalog facts.
+ * @returns the materialized models and the explicitly configured request caps.
+ */
+export declare function resolveRouteModels(request: RouteCatalogRequest): RouteCatalog;
+export {};
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/config.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Configuration schema and provider-profile validation for the pi-ai adapter.
+ * Profiles are a dict keyed by provider route, so the composition base and a
+ * user-settings layer merge per provider and the route set is structural.
+ *
+ * A route key is not required to name an installed pi-ai provider. When it does,
+ * that provider's endpoint, protocol, display name, and model catalog are the
+ * profile's defaults and the profile overrides them field by field; when it does
+ * not, the profile is the whole provider declaration. Resolution therefore ends
+ * in a built pi-ai `Provider` per route: everything a request needs is decided
+ * once, while the configuration key that made a route unserviceable can still be
+ * named in the failure.
+ *
+ * @module dsh-llm-pi-ai/config
+ */
+import type { CacheRetention, ModelThinkingLevel, Provider, ThinkingBudgets, Transport } from '@earendil-works/pi-ai';
+import z from '@deepseek-ai/schemastery';
+import type { CredentialRef } from '@stackstackstack/dsh-credentials';
+import type { ResolvedRetryPolicy, RetryPolicyConfig } from '@stackstackstack/dsh-llm';
+import type { PiAiCompatProfile, PiAiModality, PiAiModelOverride, PiAiModelProfile } from './catalog.ts';
+/** Default maximum idle interval while an adapter stream read is outstanding. */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/** Context capacity assumed for a model neither configuration nor the catalog sizes. */
+export declare const DEFAULT_CONTEXT_WINDOW = 262144;
+/** Output capability assumed for a model neither configuration nor the catalog sizes. */
+export declare const DEFAULT_MAX_TOKENS = 32768;
+/**
+ * Modalities assumed for a model neither configuration nor the catalog
+ * declares. Text is the floor every supported protocol certainly carries, so
+ * this is the absence of a declaration rather than a guess at the endpoint:
+ * nothing can interrogate a gateway for its modalities, and the two wrong
+ * answers do not cost the same. Under-claiming refuses the image before it is
+ * attached, naming the model. Over-claiming admits one the provider then
+ * rejects mid-turn, after the message is durable, leaving the session
+ * repeating a request that cannot succeed.
+ */
+export declare const DEFAULT_INPUT: readonly PiAiModality[];
+export type { PiAiCompatProfile, PiAiModality, PiAiModelOverride, PiAiModelProfile, PiAiReasoningEfforts, PiAiThinkingFormat, } from './catalog.ts';
+/** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
+export interface PiAiProviderProfile {
+    /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
+    apiKeyEnv?: string;
+    /** Name shown by configuration surfaces; defaults to the route key. */
+    displayName?: string;
+    /**
+     * Wire protocol every model on this route speaks. Omission keeps each
+     * installed catalog model's own protocol, which is why a catalog route needs
+     * no protocol at all; a route the catalog does not ship must name one.
+     */
+    api?: string;
+    /** Endpoint for this route's models; defaults to the installed catalog's endpoint. */
+    baseURL?: string;
+    /**
+     * This route's model catalog. Omission serves the installed catalog for the
+     * route unchanged; an explicit list replaces it, each entry defaulting its
+     * unset fields from the installed model of the same id.
+     */
+    models?: PiAiModelProfile[];
+    /**
+     * Installed-catalog customizations by model id: each entry reshapes that
+     * one model with the same fields a {@link models} entry takes, while the
+     * rest of the catalog keeps serving untouched. Only meaningful on a catalog
+     * route with no `models` list — `models` already replaces the catalog, so
+     * an override beside it, on a route the catalog does not ship, or naming a
+     * model the catalog does not describe is refused rather than skipped.
+     */
+    modelOverrides?: Record<string, PiAiModelOverride>;
+    /**
+     * Reasoning-dispatch switches for every `openai-completions` model on this
+     * route; each model's own `compat` overrides per field. What neither sets
+     * keeps the installed catalog entry's value, then pi-ai's baseURL-derived
+     * detection.
+     */
+    compat?: PiAiCompatProfile;
+    /**
+     * Context capacity for a model this route lists that neither the entry nor
+     * the installed catalog sizes (default 262,144). A guess by construction, so
+     * a deployment whose gateway serves smaller models corrects it here.
+     */
+    defaultContextWindow?: number;
+    /**
+     * Output capability for a model this route lists that neither the entry nor
+     * the installed catalog sizes (default 32,768). This sizes the model; it
+     * never becomes a per-request cap on its own.
+     */
+    defaultMaxTokens?: number;
+    /**
+     * Request modalities for a model this route lists that neither its entry's
+     * {@link PiAiModelProfile.input} nor the installed catalog declares (default
+     * `[text]`). A fallback like the capacities above, not an override: a
+     * catalog model keeps the modalities the catalog records for it, and this
+     * value never narrows one. A gateway serving vision models the catalog does
+     * not describe declares `[text, image]` once here instead of on every entry.
+     * Unlike an entry's list, this one may not be empty — nothing sits below it
+     * to answer instead.
+     */
+    defaultInput?: PiAiModality[];
+    /** Provider request headers; Harness attribution wins reserved names. */
+    headers?: Record<string, string>;
+    /** Provider-neutral pi-ai reasoning level. */
+    reasoning?: ModelThinkingLevel;
+    /** Token budgets used by reasoning providers that support them. */
+    thinkingBudgets?: ThinkingBudgets;
+    /** Prompt-cache retention preference. */
+    cacheRetention?: CacheRetention;
+    /** Streaming transport preference. */
+    transport?: Transport;
+    /** HTTP/provider SDK timeout in milliseconds. */
+    timeoutMs?: number;
+    /** WebSocket connection timeout in milliseconds. */
+    websocketConnectTimeoutMs?: number;
+    /** Maximum provider idle time while one stream read is outstanding. */
+    streamIdleTimeoutMs?: number;
+    /** Provider-owned model-request retry policy; omission uses normal defaults. */
+    retryPolicy?: RetryPolicyConfig;
+}
+/** Validated profile with its route stamped and every adapter-owned default resolved. */
+export interface ResolvedPiAiProviderProfile extends Omit<PiAiProviderProfile, 'apiKeyEnv' | 'retryPolicy' | 'models' | 'displayName'> {
+    /** Harness route key and the `Models` collection key (the configuration dict key). */
+    provider: string;
+    /** Resolved display name for selectors and configuration surfaces. */
+    displayName: string;
+    /** Validated credential reference, when one is configured. */
+    apiKeyEnv?: CredentialRef;
+    /** Positive finite provider-idle interval after defaulting. */
+    streamIdleTimeoutMs: number;
+    /** Immutable retry policy captured with this provider route. */
+    retryPolicy: ResolvedRetryPolicy;
+    /**
+     * The pi-ai provider this route registers, built from the resolved models.
+     * Construction happens here so an unserviceable protocol or an underspecified
+     * model fails with the rest of resolution, leaving the last good route set
+     * serving requests.
+     */
+    piProvider: Provider;
+    /**
+     * Per-request output caps this profile explicitly configured, by model id.
+     * The seam materializes one only into a request that names no cap of its
+     * own, so a catalog capability must not appear here.
+     */
+    configuredMaxTokens: ReadonlyMap<string, number>;
+}
+/** Plugin configuration: the provider routes this instance owns. */
+export interface Config {
+    /**
+     * pi-ai provider routes, keyed by provider. An empty (or omitted) dict is
+     * the dormant settings-driven posture: the adapter mounts with no routes
+     * and registers them the moment a settings section supplies profiles.
+     */
+    providers?: Record<string, PiAiProviderProfile>;
+}
+/** Runtime schema for {@link Config}. */
+export declare const Config: z<Config>;
+/**
+ * Reject a section this adapter could not serve. Registered as the settings
+ * namespace's validator, so an unserviceable profile is refused where it is
+ * *written* — `settings.mutate` answers `settings-rejected` with the offending
+ * route and model named — instead of being stored and then quietly disabling
+ * every route in the namespace. It stays a validator rather than a schema
+ * transform because the schema is also the shape a configuration surface
+ * renders and the value an absent section resolves to; wrapping it would break
+ * both.
+ * @param config - the resolved section to check.
+ * @throws Error naming the route and model that cannot be served.
+ */
+export declare function assertServiceable(config: Config): void;
+/**
+ * Validate profiles and return a detached route-keyed map suitable for
+ * per-request reads. This is the one explicit resolve step, so an omitted dict
+ * resolves to the empty (dormant) route set here rather than through a hidden
+ * fallback, and each route's models and pi-ai provider are materialized once.
+ * @param providers - configured provider profiles keyed by route.
+ * @returns validated profiles in configuration order.
+ */
+export declare function resolveProfiles(providers: Readonly<Record<string, PiAiProviderProfile>> | undefined): Map<string, ResolvedPiAiProviderProfile>;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Harness request-history conversion into pi-ai's Context vocabulary.
+ *
+ * @module dsh-llm-pi-ai/context
+ */
+import type { GenerateOptions } from '@stackstackstack/dsh-llm';
+import type { AttachmentStore } from '@stackstackstack/dsh-attachment';
+import type { Context as PiContext } from '@earendil-works/pi-ai';
+/**
+ * Convert text-only harness history to a synchronous pi-ai Context. Tool
+ * result names are recovered from preceding assistant tool calls.
+ * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
+ * @returns the pi-ai context; `tools` is omitted when the request declares none.
+ */
+export declare function toPiContext(options: GenerateOptions): PiContext;
+/**
+ * Convert harness history to a pi-ai Context while resolving durable images.
+ * Tool result names are recovered from preceding assistant tool calls.
+ * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
+ * @param attachments - durable byte resolver for image references.
+ * @returns the asynchronously resolved pi-ai context.
+ */
+export declare function toPiContext(options: GenerateOptions, attachments: AttachmentStore): Promise<PiContext>;
+//# sourceMappingURL=context.d.ts.map

package/lib/types/discovery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Answering "which models can this provider serve?" for the configuration
+ * surface's "fetch available models" action.
+ *
+ * A route the installed pi-ai catalog ships is answered **from that catalog**,
+ * with no network call at all: pi-ai's registry is the authoritative list for
+ * its own providers, and it carries the capacities a listing endpoint would
+ * not disclose. Only a route the catalog does not describe — a gateway, a
+ * self-hosted server — is interrogated over the wire.
+ *
+ * Neither path is a catalog refresh. Nothing here is stored: the request
+ * carries a draft the user is still editing, and the reply is candidate
+ * metadata the surface offers for adoption. `settings.yaml` remains the only
+ * thing that decides what a route serves.
+ *
+ * Only OpenAI-compatible protocols are interrogated. Their listing is the one
+ * shape a gateway, a self-hosted server, and the official endpoints all agree
+ * on, which is the case this action exists for; every other protocol reports
+ * that it cannot be interrogated so the surface falls back to hand-entry
+ * rather than guessing a response shape.
+ *
+ * @module dsh-llm-pi-ai/discovery
+ */
+import type { LlmDiscoveredModel, LlmModelDiscoveryRequest } from '@stackstackstack/dsh-llm';
+/**
+ * Interrogate one draft provider endpoint for the models it advertises.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @param storedApiKey - the credential the named route already stored, asked
+ *   for only when the draft carries none and only on the path that reaches the
+ *   network. A configuration surface never holds a stored secret — it edits a
+ *   redacted descriptor — so without this an already-configured route would be
+ *   interrogated unauthenticated and answer 401.
+ * @returns the advertised models in endpoint order.
+ * @throws LlmError when the protocol has no readable listing, the endpoint
+ *   refuses or fails the request, or the reply is not a model listing.
+ */
+export declare function discoverModels(request: LlmModelDiscoveryRequest, storedApiKey?: () => Promise<string | undefined>): Promise<readonly LlmDiscoveredModel[]>;
+//# sourceMappingURL=discovery.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Generic pi-ai-backed LLM adapter plugin. One plugin instance owns a dict of
+ * provider routes; a route naming an installed pi-ai provider inherits that
+ * provider's endpoint, protocol, and model catalog as defaults, and a route
+ * pi-ai does not ship is declared outright. Profile facts resolve per request
+ * over the optional `llm-pi-ai` user-settings section and the optional
+ * credential seam, so a changed key, endpoint, model, or knob reaches the next
+ * request without a restart; a changed *route set* (or a route's
+ * registration-captured retry policy) re-registers the same adapter instance
+ * in place.
+ *
+ * ```yaml
+ * - id: llm
+ *   name: '@stackstackstack/dsh-llm-pi-ai'
+ *   config:
+ *     providers:
+ *       # Catalog route: everything but the credential comes from pi-ai.
+ *       openai:
+ *         apiKeyEnv: OPENAI_API_KEY
+ *         retryPolicy:
+ *           mode: normal
+ *           maxRetries: 2
+ *       # Catalog route with the catalog narrowed and one capacity corrected.
+ *       anthropic:
+ *         apiKeyEnv: ANTHROPIC_API_KEY
+ *         models:
+ *           - id: claude-sonnet-4-5
+ *             contextWindow: 200000
+ *       # Hand-declared route: pi-ai ships nothing under this key.
+ *       acme-gateway:
+ *         displayName: Acme Gateway
+ *         apiKeyEnv: ACME_GATEWAY_API_KEY
+ *         api: openai-completions
+ *         baseURL: https://gateway.acme.example/v1
+ *         # Reasoning dialect for a URL pi-ai cannot recognize.
+ *         compat:
+ *           thinkingFormat: deepseek
+ *         models:
+ *           - id: acme-large
+ *             name: Acme Large
+ *             contextWindow: 65536
+ *             maxTokens: 4096
+ *           - id: acme-think
+ *             name: Acme Think
+ *             contextWindow: 262144
+ *             maxTokens: 32768
+ *             # key = selectable level, value = wire spelling; only off may
+ *             # leave the value empty (supported, send nothing).
+ *             reasoningEfforts:
+ *               off:
+ *               high: high
+ *               max: ultra
+ * ```
+ *
+ * @module @stackstackstack/dsh-llm-pi-ai
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.ts';
+export { PiAiAdapter } from './adapter.ts';
+export type { PiAiAdapterOptions } from './adapter.ts';
+export { Config } from './config.ts';
+export type { PiAiCompatProfile, PiAiModality, PiAiModelOverride, PiAiModelProfile, PiAiProviderProfile, PiAiReasoningEfforts, PiAiThinkingFormat, ResolvedPiAiProviderProfile, } from './config.ts';
+export { supportedProtocols } from './provider.ts';
+export declare const name = "llm-pi-ai";
+export declare const inject: string[];
+/** Register one generic pi-ai adapter for all configured provider routes. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@stackstackstack/dsh-llm-pi-ai`.
+ * @module @stackstackstack/dsh-llm-pi-ai/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "llm-pi-ai-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/provider.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Construction of the pi-ai `Provider` that one configured route registers into
+ * the adapter's `Models` collection.
+ *
+ * Two constructions, one decision: a route the installed catalog ships, whose
+ * profile does not override the wire protocol, **reuses that catalog provider**
+ * with its models replaced — the catalog provider owns API implementations this
+ * package cannot reconstruct (Bedrock loads its Smithy module through a
+ * separate entry point), so rebuilding it from parts would silently narrow
+ * which providers work. Every other route — one pi-ai has never heard of, or a
+ * catalog route pointed at a different protocol — is built by `createProvider`
+ * over the protocol table below.
+ *
+ * Credentials never reach this module's storage: the harness resolves a route's
+ * key through `ctx.credentials` before the request enters pi-ai and hands it
+ * over as a stream option, which `Models` presents to `resolve()` as the
+ * credential key.
+ *
+ * @module dsh-llm-pi-ai/provider
+ */
+import type { Api, Model, Provider } from '@earendil-works/pi-ai';
+/**
+ * Every wire protocol a configured route may name, most-reached first. The
+ * order is the table's and therefore stable; a configuration surface offering
+ * a choice presents the first as its default, which is why the protocol a
+ * hand-declared gateway most often speaks — and the one endpoint interrogation
+ * can read — leads.
+ * @returns the supported protocol identifiers.
+ */
+export declare function supportedProtocols(): readonly string[];
+/** The resolved route facts provider construction reads. */
+export interface ProviderSpec {
+    /** Provider route key; also the `Models` collection key and each model's `provider`. */
+    provider: string;
+    /** Display name for selectors and status labels. */
+    displayName: string;
+    /** Wire protocol override; absent means each model keeps its catalog protocol. */
+    api?: string;
+    /** Endpoint override already applied to {@link models}; kept for provider-level display. */
+    baseURL?: string;
+    /** The route's materialized models, in configuration order. */
+    models: readonly Model<Api>[];
+    /**
+     * Whether the profile names a credential, which it does through `apiKeyEnv`
+     * alone: configuration carries the reference, never the secret. Only that
+     * decides whether {@link routeAuth} adds the harness's own api-key method to
+     * a catalog provider that offers none; the key itself still arrives per
+     * request, never at construction.
+     */
+    namesCredential: boolean;
+}
+/**
+ * Build the pi-ai provider for one resolved route.
+ * @param spec - the resolved route facts.
+ * @returns the provider to register in the adapter's `Models` collection.
+ * @throws Error when the route names a wire protocol this build cannot serve.
+ */
+export declare function buildProvider(spec: ProviderSpec): Provider;
+//# sourceMappingURL=provider.d.ts.map