@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/provider/selection.d.ts

@@ -0,0 +1,115 @@
+import type { WinterCatalog } from "@yanlinglabs/winter-provider-catalog";
+import type { CredentialStore, ProviderContext, ProviderRegistry, ResolvedModel } from "@yanlinglabs/winter-provider-runtime";
+import { type CredentialRef, type RuntimeConfig } from "@yanlinglabs/winter-agent-sdk";
+import type { Provider } from "../engine.js";
+/**
+ * The reserved namespace that reaches the in-process scripted double (R6-13).
+ *
+ * A NAMESPACE rather than an env var, and the ruling is worth restating because it inverts a P1
+ * carry: "remove `WINTER_TEST_PROVIDER` affordances" is NOT taken as written, because `main.ts` also
+ * uses that name to register in-process test TOOLS in the spawned runtime -- something no loopback
+ * server can do. So production selection is catalog-first, the double is reachable only through this
+ * namespace, and the env var survives ONLY as the harness's alias for it.
+ */
+export declare const WINTER_TEST_NAMESPACE = "winter-test";
+/** R6-9: the resolved identity that rides `system/init`'s Winter-only `winter_provider` extension and the dialect record. */
+export interface WinterProviderIdentity {
+    providerId: string;
+    modelKey: string;
+    adapterId: string;
+    adapterVersion: string;
+    catalogVersion: string;
+    continuationDomain?: string;
+    authRefKind: CredentialRef["kind"];
+}
+/** What a session gets back. The `testProvider` arm is the reserved namespace's -- a scripted double has no catalog identity to report, and pretending otherwise would put a fake row in the init frame. */
+export type SessionProviderSelection = {
+    provider: Provider;
+    identity: WinterProviderIdentity;
+    resolved: ResolvedModel;
+    contextWindow?: number;
+    supportsToolSearch: boolean;
+    familyMetadata: {
+        taskNative?: boolean;
+    };
+    /** R6-9: the fallback candidates, already domain-checked. Empty when none was configured. */
+    fallbackModels: ResolvedModel[];
+} | {
+    testProvider: Provider;
+};
+export interface SelectionDeps {
+    registry: ProviderRegistry;
+    credentials: CredentialStore;
+    env: Record<string, string | undefined>;
+    /** R6-13: the in-process scripted double, resolved by name. Absent -> a `winter-test/<name>` model is a typed refusal rather than a silent miss. */
+    testProviders?: (name: string) => Provider | undefined;
+    /** How a resolved model becomes a `Provider`. Injected so this module never imports the bridge's own construction path in a test. */
+    buildProvider?: (resolved: ResolvedModel) => Provider;
+    /**
+     * WS-13b R6b-7: the resolved `settings.providers` map, as a GETTER.
+     *
+     * A getter and not a value, and that is the whole hot-reload seam. WS-11 §5's "no setting may
+     * require a restart" is a product rule above the SDK boundary -- this package starts no watchers
+     * (production-wiring's own header says so) -- so what it owes instead is a read that happens AT
+     * RESOLUTION TIME rather than a snapshot taken when the deps object was built. A host that
+     * re-resolves its settings sees the new value at the session's next resolution and at every
+     * `set_model`, with nothing rebuilt.
+     *
+     * Absent, or an id absent from the map, means ENABLED. Silence is never a disablement.
+     */
+    providerSettings?: () => Record<string, {
+        enabled: boolean;
+    }> | undefined;
+}
+/**
+ * Resolves the session's provider and model.
+ *
+ * Order, and each step exists because the one before it cannot answer:
+ *   1. the reserved `winter-test/<name>` namespace -- checked FIRST so a test double can never be
+ *      shadowed by a catalog row, and so the check is independent of every credential question;
+ *   2. a QUALIFIED `<providerId>/<model>` key -> the catalog, verbatim;
+ *   3. a pinned Anthropic ALIAS -> the `anthropic` provider, but only with a credential ref for it;
+ *   4. a BARE id -> `config.provider.providerId`;
+ *   5. no model and no provider -> a typed refusal.
+ */
+export declare function resolveSessionProvider(config: RuntimeConfig, deps: SelectionDeps): SessionProviderSelection;
+/**
+ * Redacts a `CredentialRef` for a frame, a log line or an error message.
+ *
+ * `inline` is the case this exists for: R6-10 makes it a HOST responsibility that the SDK never
+ * persists, and its value is a live secret sitting in the session's own config -- so anything that
+ * renders a ref renders it through here. The others carry only locators, and those are reproduced
+ * because a locator is what makes a credential problem diagnosable.
+ */
+export declare function redactCredentialRef(ref: CredentialRef): string;
+/**
+ * R6-6: how the session's stall timeout reaches an adapter.
+ *
+ * THROUGH `ProviderContext`, not `ProviderRequest`, and the placement is the design. A stall watchdog
+ * is a property of the CONNECTION -- an adapter arms it around its own `boundedFetch`/`parseSse`,
+ * once, for every call it makes -- not of one turn's payload. Putting it on the request would invite
+ * a per-turn override that no ruling asks for and that an adapter would have to re-arm mid-stream.
+ *
+ * One resolution site, so the disclosed default cannot be applied differently by two callers.
+ */
+export declare function resolveStallTimeoutMs(config: RuntimeConfig): number;
+/**
+ * Assembles the `ProviderContext` an adapter runs under.
+ *
+ * THE PRODUCTION CALLER OF `resolveStallTimeoutMs`, and the reason this function exists rather than
+ * leaving five separate decisions to whoever wires a session (review round 1, M1). The stall timeout
+ * is the one that shows why: `sse.ts` reads `ctx.stallTimeoutMs` on every chunk, so a caller that
+ * assembled a context without it would silently disable R6-6's watchdog on every stream — a disclosed
+ * option that quietly did nothing.
+ *
+ * `log` defaults to a NO-OP rather than to a console writer: `ProviderContext.log`'s own contract is
+ * provider/model identifiers and byte COUNTS only, and a default that wrote anywhere would be a
+ * default that a careless adapter could turn into a content leak.
+ */
+export declare function createProviderContext(config: RuntimeConfig, deps: {
+    providerId: string;
+    credentials: CredentialStore;
+    log?: ProviderContext["log"];
+}): ProviderContext;
+/** Convenience for a caller that has a catalog rather than a registry. One construction site, so a registry is never built twice for one session. */
+export declare function createSelectionRegistry(catalog: WinterCatalog): ProviderRegistry;

package/dist/provider/session-provider.d.ts

@@ -0,0 +1,426 @@
+import type { WinterCatalog, WinterProviderDescriptor } from "@yanlinglabs/winter-provider-catalog";
+import type { CredentialRef, ProviderConnectionConfig, RuntimeConfig } from "@yanlinglabs/winter-agent-sdk";
+import type { CredentialStore, ModelInfo, ProviderContext, ProviderRegistry, ResolvedModel } from "@yanlinglabs/winter-provider-runtime";
+import { WinterProviderResolutionError, DECORATION_CHAR_BUDGET, MAX_DECORATION_CHARS } from "@yanlinglabs/winter-provider-runtime";
+import { type KeychainSecretReader } from "./keychain-store.js";
+import { type ToolSecretResolver } from "./tool-secret.js";
+import { type WinterProviderIdentity } from "./selection.js";
+import { type ClassifierRoute } from "./classifier/model-classifier.js";
+import type { ClassifierInterface } from "../permissions/auto/engine.js";
+import { type ContinuationChain, type ProviderStateRecord, type ProviderStateRecordInput } from "../store/provider-state.js";
+import type { PricedUsage, Provider, ProviderUsage, ResolveModelSwitch, UsageRowFacts } from "../engine.js";
+import { type SlotProviderResolution } from "./slots.js";
+/**
+ * The pinned `ApiKeySource` vocabulary (`sdk.d.ts:127`), of which the JSDoc marks five members
+ * legacy — the live set is these four.
+ *
+ * WINTER'S MAPPING, and it is a DISCLOSED gap-fill rather than a translation. The union has exactly
+ * one spelling for "an API key", and it names an environment variable: `'ANTHROPIC_API_KEY'`. It has
+ * no spelling for "a key from the Keychain", "a key from a file" or "a key the host passed inline" —
+ * every credential shape R6-10 adds. So Winter reports `'ANTHROPIC_API_KEY'` for exactly that env
+ * name and `'none'` for everything else, on the pin's own gloss that `'none'` means "not via an API
+ * key" and is what the pinned runtime itself reports for OAuth, bearer and third-party-cloud auth.
+ *
+ * The REAL fact is never lost: it rides `winter_provider.authRefKind` on the same frame, which is
+ * where a consumer that cares about Winter's credential model is supposed to look. Inventing a fifth
+ * member of a closed pinned union would be the divergence; reporting the pin's own catch-all is not.
+ */
+export type ApiKeySource = "ANTHROPIC_API_KEY" | "apiKeyHelper" | "/login managed key" | "none";
+export declare function apiKeySourceFor(ref: CredentialRef | undefined): ApiKeySource;
+/** The `AccountInfo` shape the pin declares (`sdk.d.ts:23-33`) — every field optional, an empty object valid. */
+export interface AccountInfo {
+    email?: string;
+    organization?: string;
+    subscriptionType?: string;
+    tokenSource?: string;
+    apiKeySource?: string;
+    apiProvider?: "firstParty" | "bedrock" | "vertex" | "foundry" | "anthropicAws" | "anthropicGoogleCloud" | "mantle" | "gateway";
+}
+/** The one read of the table above (exported for its own unit test, exactly as `apiKeySourceFor` is). `undefined` = this provider has no member of its own and reports nothing. */
+export declare function apiProviderFor(providerId: string | undefined): AccountInfo["apiProvider"] | undefined;
+export interface SessionProviderOptions {
+    /** The session's EFFECTIVE config. */
+    config: RuntimeConfig;
+    /** The environment governing R6-13's harness alias and the `env` credential store. Explicit at every entrypoint. */
+    env: Record<string, string | undefined>;
+    /** Injected in tests so a fixture owns its own rows. Production: the catalog compiled into this build. */
+    catalog?: WinterCatalog;
+    /** Injected in tests (an in-memory store). Production: keychain + env + file + inline, composed below. */
+    credentials?: CredentialStore;
+    /**
+     * R6-13: the reserved `winter-test/<name>` namespace's in-process double.
+     *
+     * DEFAULTS TO `testProviderForNamespace` (`provider/mock.ts`) — the namespace is a DISCLOSED test
+     * affordance that exists in production by ruling, not an injection point a caller has to remember,
+     * and a default that refused it would make the namespace work on one leg and not another. A caller
+     * overrides it only to supply something the shared table cannot: `main.ts` wraps it to register the
+     * `bgtask` fixture's paired TOOL, and `testing.ts` replaces it with the live JS provider its caller
+     * handed the leg — the one thing a spawned process can never be given.
+     */
+    testProviders?: (name: string) => Provider | undefined;
+    /**
+     * R6-7: the resumed continuation chain, as a GETTER.
+     *
+     * A getter rather than a value because the chain is re-attached asynchronously at the start of the
+     * run (`attachContinuationChain`), after this wiring is built — a captured snapshot would always
+     * be the empty one.
+     */
+    chain?: () => ContinuationChain;
+    /**
+     * Review r1, M-1: where the renderer's sticky decoration decisions persist (the session's own
+     * provider-state sidecar, `SessionPersistence.recordProviderState`). Absent: they hold for this run only.
+     */
+    recordProviderState?: (record: ProviderStateRecordInput) => void | Promise<void>;
+    /** `ProviderContext.log` — provider/model identifiers and BYTE COUNTS only, never content. Defaults to a no-op. */
+    log?: ProviderContext["log"];
+    /**
+     * The OS home the `file` credential store resolves `~/.aws/credentials` under.
+     *
+     * Explicit at every entrypoint and NEVER defaulted to `os.homedir()` here: a default would make
+     * every test that forgot to set it read the developer's real credentials file, which is precisely
+     * the hazard the Global Constraints forbid. `env.HOME` is the caller's usual answer.
+     */
+    home?: string;
+    /**
+     * WS-13b R6b-7: the resolved `settings.providers` map, as a GETTER (see `SelectionDeps`' own
+     * field for why a getter is the hot-reload seam).
+     *
+     * Threaded into selection AND read again at the `set_model` seam: R6-K put resolution under the
+     * session provider precisely so a switch cannot walk around a rule the session start applied, and
+     * a disable that held only at start would be exactly such a walk-around.
+     */
+    providerSettings?: () => Record<string, {
+        enabled: boolean;
+    }> | undefined;
+    /**
+     * WS-13c §4 step 6 (P6.6): the slot resolver, so `set_model` accepts a SLOT NAME.
+     *
+     * Consulted only for a BARE name — a qualified `<providerId>/<model>` key is already an
+     * unambiguous statement and goes straight to R6-K's own rules, unchanged. A refusal is returned as
+     * the seam's typed refusal and becomes the control response, exactly like `provider-mismatch`:
+     * never a parked switch, never a substitution.
+     *
+     * ABSENT -> `set_model` keeps its pre-P6.6 shape verbatim (every scripted double, every pre-P6.6
+     * fixture, and the reserved `winter-test/<name>` namespace, for which the wiring withholds it).
+     */
+    resolveSlot?: (requested: string, currentModelKey: string | undefined) => SlotProviderResolution;
+    /**
+     * P7a LANE B (D30): `settings.advisor.model`, as a GETTER over the same live settings view
+     * `providerSettings` reads.
+     *
+     * A GETTER for the reason every other settings seam in this file is one: the value is HOT (a
+     * Global Constraint of this phase -- "takes effect at the next quiescent boundary through the live
+     * settings getter, no restart"), and a string captured at construction could only ever be the
+     * value the session started with.
+     *
+     * ABSENT -> no setting is in play and the precedence falls to `Options.advisor.model` and then to
+     * D30's per-family default, which is exactly what a host that resolves no settings should get.
+     */
+    advisorModelSetting?: () => string | undefined;
+    /**
+     * P7a LANE B, fix r1 (review M-1): a monotonic number the wiring bumps whenever it LEARNS something
+     * about a provider's credential, so a memo taken on a cold view cannot outlive that view.
+     *
+     * WHY IT HAS TO EXIST. `production-wiring.ts`'s `credentialPresent` is a synchronous answer over an
+     * asynchronous fact: the session's own provider is `"present"` by construction, every other
+     * provider is `"unknown"` until a background probe lands, and nothing awaits those probes. The very
+     * first consumer is `reviewerResolves()` computing `init.tools`, which is what FIRES the prewarm --
+     * so the advisor's first resolution is necessarily cold, and a memo without this term pins that
+     * cold answer for the session's whole life.
+     *
+     * A VERSION rather than the credential view itself, for the same reason `settingsVersion` is a
+     * number: the memo compares it, and comparing a view by value would mean re-deriving the whole
+     * presence map on every capability check.
+     *
+     * ABSENT -> `0`, i.e. "nothing here ever learns anything", which is the truth for a caller that
+     * builds a wiring directly with a fixed credential store.
+     */
+    credentialEpoch?: () => number;
+    /**
+     * The keychain's RAW reader, for `resolveToolSecret` (a tool's key may be a bare string, which the
+     * credential store rightly refuses -- see `tool-secret.ts`).
+     *
+     * DEFAULTS TO THE REAL ONE ONLY WHEN `credentials` IS ALSO DEFAULTED. A caller that injects a
+     * credential store (every test) has said "this is the only source", and quietly reading the real
+     * keychain beside it would be exactly the test-touches-the-login-keychain hazard the store's own
+     * injection exists to prevent. Such a caller passes a reader over a fake backend, or none at all.
+     */
+    readKeychainSecret?: KeychainSecretReader;
+}
+/**
+ * What `resolveAuxiliaryModel` answers: a BUILT, non-streaming provider for the tag, or a typed
+ * refusal. A VALUE in both arms -- the consumer is a tool executor, which must never throw.
+ */
+export type AuxiliaryModelResolution = {
+    ok: true;
+    provider: Provider;
+    modelKey: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export interface SessionProviderWiring {
+    /** What `runEngine` is handed. Either the catalog-resolved adapter chain or the reserved namespace's scripted double. */
+    provider: Provider;
+    registry: ProviderRegistry;
+    credentials: CredentialStore;
+    catalog: WinterCatalog;
+    /** ABSENT for a `winter-test/<name>` session: a scripted double has no catalog identity, and putting a fake row in the init frame would be worse than omitting it. */
+    identity?: WinterProviderIdentity;
+    resolved?: ResolvedModel;
+    /**
+     * PRESENT when selection REFUSED, in which case this wiring's `provider` is the one that rethrows
+     * the refusal on its first generation (see `buildSessionProvider`'s own header for the ruling).
+     *
+     * Exposed rather than swallowed so an entrypoint can also report the reason on stderr: the frame
+     * stream is the host's channel, stderr is the operator's, and a refusal deserves both.
+     */
+    resolutionError?: WinterProviderResolutionError;
+    /** R6-9: the pinned `system/init.apiKeySource`. Always present — the pin makes the field REQUIRED. */
+    apiKeySource: ApiKeySource;
+    /** P4 carry: `toolCalling === "native"`, from the descriptor's own evidence. Absent when nothing is known. */
+    providerSupportsToolSearch?: boolean;
+    /** The descriptor's context window, unless the host set `contextWindowTokens` explicitly. */
+    contextWindowTokens?: number;
+    /** R6-14: which classifier this session got, and why. Recorded so `fallback_state` can name the reason. */
+    classifierRoute: ClassifierRoute;
+    /** ABSENT unless the route produced a real one — `createAutoEngine`'s own default (always `no_verdict`) is what a manual fallback means. */
+    classifier?: ClassifierInterface;
+    /**
+     * P7a LANE B (D29/D30) — THE ADVISOR'S REVIEWER, resolved on demand.
+     *
+     * REPLACES the P2-carry `advisorProvider`, which was a single provider built once from
+     * `config.advisor.model` and nothing else. Three things forced a function:
+     *
+     *   - the reviewer's model can come from `settings.advisor.model`, which is HOT (a Global
+     *     Constraint of this phase): a value captured at session start could never see an edit;
+     *   - its DEFAULT depends on the session's family (D30), and the session's family changes with
+     *     `set_model` -- so the answer depends on the LIVE model key, which is the argument;
+     *   - the advisor tool's own contract is "a reviewer is resolvable RIGHT NOW" (its
+     *     `winter.reviewer-model` capability gate), which is a question, not a stored object.
+     *
+     * PINNED AT FIRST USE (WS-13 R6-G): the built provider is memoised on the inputs that chose it
+     * (the option, the live setting, the session's model key), so repeated calls within one settings
+     * version return the SAME provider instance -- and a settings edit re-pins at the next call, which
+     * is the next quiescent boundary. No cache is shared with the classifier (R6-G's own rule); this
+     * memo holds one entry and its key is the route's own inputs.
+     *
+     * ABSENT for a session with no catalog identity (the reserved `winter-test/<name>` namespace and a
+     * session whose own model failed to resolve): there is no family to default from and no row to
+     * resolve against, and a fabricated answer would be worse than the honest "no reviewer".
+     */
+    resolveReviewer?: (currentModelKey?: string) => {
+        provider: Provider;
+        model: string;
+    } | undefined;
+    /**
+     * A TOOL'S OWN INNER MODEL, by tag -- `WebFetch`'s page-digest model is the first consumer.
+     *
+     * `tag` is a provider-qualified key or a slot name and goes through the SAME slot resolver
+     * `set_model`, a child spawn and the advisor use, then `registry.resolve`, then `buildProvider`
+     * under Ruling E-1: `opts.authRef` is the ROUTE's own credential (step 1); without it a target on
+     * the session's provider uses the session's material and a target on ANOTHER provider gets its own
+     * `<providerId>:default` record, verified at its first generation with a typed
+     * `no-credential-for-provider`. The session's key is never sent to another provider.
+     *
+     * The provider is wrapped `withoutStreaming` (R6-G: an auxiliary generation emits no
+     * `stream_event`s) and MEMOISED per `(tag, authRef, session model key, credential epoch)`, so the
+     * capability check that asks "does the digest model resolve" on every tool-list read costs one
+     * resolution per credential/settings view, and a repeated call reuses one provider object.
+     *
+     * It answers with a REFUSAL VALUE, unlike `resolveReviewer` (whose throw is a documented
+     * workaround for a pinned return type). "The session's own model" is NOT a tag and never comes
+     * here: the engine already holds that provider, live, and re-resolving it would be a second
+     * opinion about a decision `set_model` and the fallback already made.
+     *
+     * ABSENT on the two arms with no catalog identity (the reserved test namespace, a refused
+     * session): a stated tag is then simply unresolvable, and the consumer says so.
+     */
+    resolveAuxiliaryModel?: (tag: string, opts?: {
+        authRef?: CredentialRef;
+        currentModelKey?: string;
+    }) => AuxiliaryModelResolution;
+    /**
+     * Resolves a TOOL's secret from an arbitrary ref -- see `tool-secret.ts`. Present on EVERY arm: it
+     * depends on the credential store, not on the session having a model.
+     */
+    resolveToolSecret: ToolSecretResolver;
+    /**
+     * Builds a `Provider` for any resolved model against THAT TARGET's material (Ruling E-1), the
+     * session's renderer and the session's chain.
+     *
+     * Exposed because R6-17's per-child provider needs the identical construction — a child built
+     * through a second construction path would get a different context (and, per
+     * `createProviderContext`'s own header, could silently lose the stall watchdog).
+     */
+    buildProvider(resolved: ResolvedModel, opts?: BuildProviderOptions): Provider;
+    /** Ruling E-1: WHICH credential and connection `buildProvider` would use for this target, and why. Pure -- no store is consulted. */
+    describeTargetMaterial(resolved: ResolvedModel, opts?: BuildProviderOptions): TargetMaterial;
+    /** The provider this session is configured for (`config.provider.providerId`, else the resolved model's). Undefined only for a session with neither. */
+    sessionProviderId(): string | undefined;
+    /**
+     * P6 fix wave (Ruling E-2): THE SWITCH SEAM -- `EngineOptions.resolveModelSwitch`. R6-K resolution
+     * under the session provider, `buildProvider` under Ruling E-1, the resolved identity, and the two
+     * continuity endpoints `classifySwitch` compares. Present on every arm: a session that started
+     * unresolvable can be handed a model that resolves and recover.
+     */
+    resolveModelSwitch: ResolveModelSwitch;
+    /** P6 fix wave (Ruling E-3): `fallbackModel`'s candidates as catalog keys, in order, domain-checked at init. Empty for the reserved namespace and for a refused session. */
+    fallbackModelKeys: string[];
+    /** P6 fix wave (Ruling E-4, R6-H): prices one generation for the model it ran on, from the catalog's `pricing` evidence. `undefined` for an unpriced row. */
+    priceUsage(modelKey: string, usage: ProviderUsage): PricedUsage | undefined;
+    /** The catalog facts for a `modelUsage` row of ANY resolvable model, priced or not (dist-session fixes C1). `undefined` for a key the catalog cannot resolve. */
+    usageRowFacts(modelKey: string): UsageRowFacts | undefined;
+    /** P6 fix wave (Ruling E-5, R6-14): the resolved classifier model's key, for the session pin. Present exactly when `classifier` is. */
+    classifierIdentity?: {
+        modelKey: string;
+    };
+    /** R6-I: the `supportedModels()` rows for this session. */
+    supportedModels(): ModelInfo[];
+    /** R6-I / capture (d): the initialize-response account surface. Never `system/init` — the pin has no account field there. */
+    accountInfo(): AccountInfo;
+}
+/** What a caller may pass to `buildProvider`. `authRef` is the target ROUTE's own credential (a classifier's `autoClassifier.authRef`, an advisor's `advisor.authRef`). */
+export interface BuildProviderOptions {
+    authRef?: CredentialRef;
+}
+/**
+ * Ruling E-1: the credential and connection a provider built for `resolved` is given.
+ *
+ * `source` records which step of the rule answered:
+ *   - `route`            an explicit `authRef` on the target's own route;
+ *   - `session`          the target IS the session's provider, so the session's own material;
+ *   - `provider-record`  the target provider's OWN keychain record (`<providerId>:default`, R6-10's
+ *                        one-record-per-provider/account), whose existence the built provider
+ *                        verifies on its first generation and refuses (typed) when absent.
+ *
+ * `crossProvider` is the fact every consumer keys on: a cross-provider target's `connection` is its
+ * own generated endpoint -- never the session's user `baseUrl`/headers.
+ */
+export interface TargetMaterial {
+    authRef: CredentialRef;
+    connection?: ProviderConnectionConfig;
+    source: "route" | "session" | "provider-record";
+    crossProvider: boolean;
+}
+/** The account id a target provider's OWN keychain record is looked up under when a route names no ref (Ruling E-1 step 2). Disclosed in WS-13 §6. */
+export declare const DEFAULT_PROVIDER_ACCOUNT_ID = "default";
+/**
+ * The production credential store: Keychain, then env, then file, then inline.
+ *
+ * COMPOSED, not chosen: a `CredentialRef` names its own kind, every member answers `null` (or a
+ * typed `unsupported` the composite skips) for a ref it does not own, so the order is about which
+ * member gets asked first and not about precedence between competing answers.
+ *
+ * The Keychain member is FIRST and is constructed unconditionally, which is safe because
+ * `keychain-store.ts` resolves `Bun.secrets` LAZILY — a session with no keychain ref never touches
+ * it, and a runtime without it reports a typed failure at the point of use rather than at import.
+ */
+export declare function createProductionCredentialStore(config: RuntimeConfig, env: Record<string, string | undefined>, home: string): CredentialStore;
+/**
+ * The connection profile for one resolved provider.
+ *
+ * THE RULE, and the fixture `production-wiring.test.ts` pins it in both directions:
+ *
+ *   - The operator's own `connection.baseUrl` always wins, verbatim, and is a USER endpoint.
+ *   - Otherwise the catalog's `defaultEndpoints.api` is copied in ONLY when the adapter has no
+ *     vendor default of its own to fall back to — which is exactly the adapters that serve MORE THAN
+ *     ONE provider (`winter.local-openai`'s twelve local runners, `winter.openai-chat-completions`'s
+ *     deepseek and openrouter). One adapter, many vendors, no single default.
+ *   - Otherwise nothing is set, so the adapter uses its own reviewed endpoint and
+ *     `applyPrivilegedHeaders` still has something to gate.
+ *
+ * "Serves more than one provider" is deliberately computed from the catalog rather than hard-coded,
+ * and the fixture asserts BOTH directions (`google`/`bedrock` get no baseUrl; `deepseek` and a
+ * local runner do). `anthropic` (P6.5) and `openai` (WS-23, when `xai` joined it on
+ * `winter.openai-responses`) each crossed from the first group to the second, and the fixture failed
+ * loudly both times; since P7a the copy is stamped `"reviewed"`, so crossing no longer demotes the
+ * endpoint (it pins that too).
+ *
+ * P7a (WS-13b §10, closing the M-1 partial): every profile this function returns with a `baseUrl`
+ * now says WHERE that URL came from. The copy is `"reviewed"`; anything the operator supplied is
+ * `"user"`. Until the marker existed, the two were byte-identical strings and every adapter had to
+ * read the copy as a user endpoint — which silently took 156 rows off the privileged-header path
+ * in production while adapter fixtures, passing a generated base URL directly, kept passing.
+ */
+export declare function connectionForProvider(config: RuntimeConfig, catalog: WinterCatalog, provider: WinterProviderDescriptor): ProviderConnectionConfig | undefined;
+/**
+ * Ruling E-1: a CROSS-PROVIDER target's connection. The session's user `connection` is NOT consulted
+ * -- a user `baseUrl` and its headers belong to the session's own provider -- so the target reaches
+ * its own generated endpoint (copied into the profile for a multi-provider adapter, per the rule
+ * above; left to the adapter's reviewed default otherwise).
+ *
+ * P7a: for a `requiresUserEndpoint` provider this ALWAYS refuses. Such a target has no endpoint of
+ * its own and, by this function's own rule, may not borrow the session's -- so there is nothing to
+ * reach and the refusal is the honest answer, not an omission. A classifier, advisor or R6-17 child
+ * on `azure-ai` is exactly that shape.
+ */
+export declare function generatedConnectionForProvider(catalog: WinterCatalog, provider: WinterProviderDescriptor): ProviderConnectionConfig | undefined;
+/**
+ * Builds the session's provider, identity, classifier and account surface.
+ *
+ * NEVER THROWS for an unresolvable session model (R6-9, as reversed in review round 1): the refusal
+ * is DEFERRED -- this returns a wiring whose `provider.generate()` rethrows the typed
+ * `WinterProviderResolutionError`, so the session still starts, `system/init` is emitted (with no
+ * `winter_provider`), and the first generation lands on R6-F's pinned result shape before `query()`
+ * throws. `resolutionError` carries the reason so an entrypoint can also report it on stderr.
+ */
+/**
+ * P7a (D19 / R-7a-8) -- THE KEYCHAIN BLOCK'S SINGLE SOURCE.
+ *
+ * A FUNCTION, and exported, because the answer is needed in two places -- the credential store this
+ * session opens (`buildCredentialStore`) and the `service` a cross-provider record's `authRef`
+ * carries (`describeTargetMaterial`) -- and the two naming different services would write a
+ * credential where nothing will look for it.
+ *
+ * `brand.keychainService` is the source. `config.keychainService` is the DEPRECATED standalone
+ * alias, and the wrapper emits it only when the session actually chose a service (branded, or the
+ * option set) -- so a branded host that set `brand.keychainService` and nothing else leaves the
+ * top-level key ABSENT, and a reader of that key alone silently opened WINTER's own service for a
+ * reuser whose whole profile said otherwise. The two surfaces AGREE by construction whenever both
+ * are present (`query()` folds the deprecated option INTO the profile before resolving), so
+ * preferring the profile can never contradict a host that used the old field.
+ *
+ * `undefined` means "the session chose none" -- `createKeychainCredentialStore`'s own default
+ * applies, and the `authRef` carries no `service` key at all (which is what keeps an unbranded
+ * session's `authRef` byte-identical to before P7a).
+ */
+export declare function resolveSessionKeychainService(config: RuntimeConfig): string | undefined;
+/** WS-23 (reasoning-state): the cross-family decoration caps -- declared beside the fit estimate that accounts for them (provider-runtime `continuity/fit.ts`, where the rationale is). */
+export { DECORATION_CHAR_BUDGET, MAX_DECORATION_CHARS };
+export declare function buildSessionProvider(opts: SessionProviderOptions): SessionProviderWiring;
+/**
+ * R6-7 / Lane C wiring item 2: the RESUMED continuation chain, loaded once before the run starts.
+ *
+ * WHY IT IS LOADED HERE AND NOT INSIDE THE ENGINE. `attachContinuationChain` (engine.ts) folds each
+ * record's `origin` onto the in-memory message it belongs to, which is what the domain check reads —
+ * but the renderer's OTHER input is the chain itself, and that is where the `summary` records live.
+ * R6-8 forbids a foreign summary from ever entering `assistant.message.content`, so the sidecar is
+ * its only home; a renderer handed an empty chain therefore renders a resumed cross-family history
+ * with no decoration at all, which is indistinguishable from a session that had nothing to carry.
+ *
+ * `entryUuids` is the set of assistant entries that ACTUALLY EXIST in the rebuilt history —
+ * `buildContinuationChain`'s own rule is that a record without its entry is ignored (and
+ * garbage-collectable), so passing the record's own anchors back in would defeat the check.
+ *
+ * An unreadable sidecar yields an EMPTY chain rather than a throw: `attachContinuationChain` already
+ * emits the `sidecar_unreadable` continuity warning for exactly this case, and a session must not
+ * fail to start because its optional continuation state could not be read.
+ */
+export declare function loadResumedChain(store: {
+    loadProviderState?(): Promise<ProviderStateRecord[]>;
+} | undefined, messages: ReadonlyArray<{
+    uuid?: string;
+}>): Promise<ContinuationChain>;
+/**
+ * A `Provider` that never streams, for the auxiliary generations R6-G names.
+ *
+ * `ProviderRequest.sink` is what makes a generation's `stream_event`s reach the host, and capture (F)
+ * found the pinned runtime forwarding events for only the FORWARDED generations — the compaction
+ * summariser, the classifier, the advisor and `countTokens` are all suppressed. The engine already
+ * builds those requests without a sink; this wrapper is the belt-and-braces half for a provider
+ * handed to one of them directly (the advisor backend below), so a future caller that copies a
+ * request wholesale cannot accidentally re-enable streaming for an auxiliary call.
+ */
+export declare function withoutStreaming(provider: Provider): Provider;

package/dist/provider/slots.d.ts

@@ -0,0 +1,120 @@
+import type { WinterCatalog } from "@yanlinglabs/winter-provider-catalog";
+import type { ActiveSlotSet, ModelSlotSetting } from "@yanlinglabs/winter-agent-sdk";
+/**
+ * The marker the Agent descriptor's static description carries, and the block it lives in.
+ *
+ * DECLARED HERE rather than in `tools/descriptors/agent.ts` on purpose: the engine has to strip the
+ * block when no active slot set is wired, and importing the descriptor module for a string would
+ * run its `stub(...)` registration as a side effect of loading the engine. This module has no side
+ * effects at all, so both ends can name the same constant.
+ */
+export declare const AGENT_MODEL_SLOTS_MARKER = "{{MODEL_SLOTS}}";
+export declare const AGENT_MODEL_SLOTS_BLOCK = "\n\nModel options for this session:\n{{MODEL_SLOTS}}";
+/**
+ * The WS-06 canonical name of the one tool whose schema is rendered per family.
+ *
+ * Declared beside the marker for the same reason: the engine needs to recognise the descriptor and
+ * cannot import the descriptor (or the executor) module for a string without taking its
+ * registration side effects. `descriptors/agent.ts` and `tools/impl/agent.ts` both read it from
+ * here, so the name has one producer rather than three spellings that could drift.
+ */
+export declare const AGENT_TOOL_CANONICAL_NAME = "Agent";
+export interface ActiveSlotSetInput {
+    catalog: WinterCatalog;
+    currentModelKey: string | undefined;
+    customSlots: readonly ModelSlotSetting[] | undefined;
+}
+/**
+ * The slots this session offers (WS-13c §3).
+ *
+ * TOTAL BY CONSTRUCTION — it never throws. It is called on every turn to render the Agent tool, and
+ * a session whose model failed to resolve (or one running a scripted double, or one on an
+ * `allowUnlisted` pass-through with no catalog row) still renders tools. An exception here would
+ * take down the tool advertisement itself, which is a strictly worse answer than an honest
+ * `own-model` set naming the model the session is actually on.
+ */
+export declare function computeActiveSlotSet(input: ActiveSlotSetInput): ActiveSlotSet;
+/**
+ * The two things the Agent tool renders from the active set (WS-13c §3): the `model` property's
+ * `enum` (slot names in order) and one description line per slot, appended to the tool description
+ * as `<name> — <canonicalModelId>: <description> (<reason>)`.
+ *
+ * The tool SHAPE never changes — only these two.
+ */
+export declare function renderAgentModelSchema(active: ActiveSlotSet): {
+    enum: string[];
+    descriptionLines: string[];
+};
+/**
+ * WS-13c §4 step 2, as three states rather than two (R-6c-27).
+ *
+ * `CredentialStore.get` is asynchronous (a Keychain read) while this whole resolver is synchronous,
+ * so a caller genuinely cannot always answer. Collapsing that to `true` made a COLD subscription row
+ * win §4 step 3-i over a WARM token row the user actually has — an openai-API-key-only session's
+ * first `Agent(model: "astra")` chose `codex-oauth`, and `set_model` reported success and only failed
+ * at the next generation. Collapsing it to `false` is worse: it writes "no credential configured"
+ * into a `wouldServe` line about a provider that may well be configured, which is a false statement
+ * about the user's setup rather than a missing one.
+ *
+ * So: `absent` filters the row out and names the reason; `unknown` keeps it, but orders it AFTER
+ * every `present` row in the same §4 tier.
+ */
+export type CredentialPresence = "present" | "absent" | "unknown";
+export interface SlotProviderResolutionInput {
+    catalog: WinterCatalog;
+    active: ActiveSlotSet;
+    requested: string;
+    hasCredential: (providerId: string) => CredentialPresence;
+    providerEnabled: (providerId: string) => boolean;
+    preferredProviders: readonly string[];
+    /**
+     * LANE A ADDITION to the spine's pinned input (optional, so every pinned call site still compiles).
+     *
+     * `ActiveSlotSet`/`SlotView` are the PUBLIC, host-facing shapes and carry no `provider` field, so a
+     * custom slot's pin (`modelSlots[].provider`, WS-13c §4 step 4) has nowhere to ride into this
+     * function. Without it a pinned slot would resolve to whatever step 3 ordered first — a silent
+     * substitution of one provider for another, which is the single thing §4 step 4 exists to prevent.
+     * Matched BY NAME (a validated set has unique names), never by index.
+     */
+    customSlots?: readonly ModelSlotSetting[];
+}
+export type SlotProviderResolution = {
+    ok: true;
+    modelKey: string;
+    providerId: string;
+    canonicalModelId: string;
+    slot: {
+        family: string;
+        name: string;
+        source: ActiveSlotSet["source"];
+    };
+    /**
+     * LANE A ADDITION: TRUE when `requested` was a slot NAME.
+     *
+     * A full catalog key or a canonical id passes through (§3: "`AgentInput.model` is slot names
+     * only" governs what the MODEL is offered; a host-side `AgentDefinition.model`,
+     * `WINTER_SUBAGENT_MODEL` and the inherited `config.model` are full identifiers and reach the
+     * same resolver). `slot` still carries the active family/source so the pinned shape stays
+     * total, so a consumer that RECORDS the slot on a child must gate on this flag — otherwise
+     * every pre-P6.6 spawn, whose model is the parent's own `config.model`, grows a `slot` record
+     * naming a slot nobody asked for (WS-13c §3: "the slot the request named, IF it named one").
+     */
+    viaSlotName: boolean;
+} | {
+    ok: false;
+    code: "slot-unservable" | "ambiguous-slot-name" | "unknown-slot";
+    message: string;
+    wouldServe: Array<{
+        key: string;
+        providerId: string;
+        why: string;
+    }>;
+};
+/**
+ * Slot name -> provider + model key (WS-13c §4).
+ *
+ * NEVER A SUBSTITUTION (WS-13 §9): a failure is typed and carries `wouldServe` — the rows that would
+ * have served it and why each did not (no credential / disabled / pinned provider absent) — because
+ * "it did not work" and "you have no OpenAI key" are different problems for the user.
+ */
+export declare function resolveSlotToProvider(input: SlotProviderResolutionInput): SlotProviderResolution;