@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/provider/classifier/prompt.d.ts

@@ -0,0 +1,62 @@
+import type { ActionEnvelope } from "../../permissions/auto/envelope.js";
+import type { ClassifierContext } from "../../permissions/auto/engine.js";
+/**
+ * P2 carry, WS-07 §10.4 ("a bounded portion of..."): the ceiling on the app-owned
+ * `accumulatedClassifierContext` a single review may carry.
+ *
+ * 8000 characters is roughly a couple of thousand tokens — enough for a real PostToolUse
+ * accumulation, far short of anything that would push a review request into a context-length failure
+ * (which §10.5 treats as its own no-verdict class, i.e. as a DENIAL). The bound exists so an
+ * accumulator that grows across a long session degrades by dropping its oldest entries rather than
+ * by silently failing every permission decision in the session.
+ */
+export declare const DEFAULT_MAX_CONTEXT_CHARS = 8000;
+/**
+ * The system prompt.
+ *
+ * A CONSTANT, not a template: nothing about the pending action, the session, the rules or the
+ * context appears here. That separation is the point — this half is trusted text Winter wrote, and
+ * everything the reviewer could be attacked through arrives in the other half, fenced and labelled.
+ *
+ * What it states, and why each line is here rather than implied:
+ *   - the role and the single output channel (§10.6-3: "the classifier receives strict data blocks
+ *     and no tools" — one tool, and it is the answer channel, not an action);
+ *   - that data is data (§10.4);
+ *   - the three-value vocabulary and, crucially, that `no_verdict` is a real answer rather than a
+ *     failure to answer (§10.6-5: insufficient information must not be guessed into an allow — the
+ *     engine fails closed on it, so honest abstention costs the user a prompt, not a compromise);
+ *   - that the rules block is authoritative over the reviewer's own opinion (§10.2's tier semantics
+ *     are enforced deterministically OUTSIDE the model too — `resolveAutoTier`'s backstop can only
+ *     make an outcome stricter — but a reviewer that argues with the configured policy produces
+ *     verdicts a user cannot reason about).
+ */
+export declare const CLASSIFIER_SYSTEM_PROMPT: string;
+export interface ClassifierPromptOptions {
+    /** P2 carry: the ceiling on the app-owned accumulated context. Oldest entries are dropped first. */
+    maxContextChars?: number;
+    /** Test seam ONLY: forces the fence token, so a fixture can drive a payload that contains it. Production never passes this. */
+    nonce?: string;
+    /**
+     * P7a fix wave (item 5, M-1): the running brand's instructions file, named in the prompt sent to
+     * the CLASSIFIER MODEL. A rebranded session labelled its own `ACME.md` block "The project's loaded
+     * WINTER.md guidance", which is a false statement about the operator's own file in a prompt whose
+     * job is to judge a permission decision. Defaults to Winter's, so every fixture is byte-identical.
+     */
+    instructionsFile?: string;
+}
+export interface ClassifierPromptResult {
+    text: string;
+    /** The one-time fence token this call used. Returned so a fixture can assert what is inside the fences without re-deriving it. */
+    fence: string;
+    /** Bounding evidence (P2 carry): how much app-owned context survived, and how much was dropped. */
+    contextIncluded: number;
+    contextDropped: number;
+}
+/**
+ * Assembles the review request.
+ *
+ * The block ORDER is deliberate: rules first, then the action, then the softer context. A reviewer
+ * that reads the policy before the action is being asked "does this action fit these rules"; one
+ * that reads the action first is being invited to form an opinion and then look for support.
+ */
+export declare function buildClassifierPrompt(envelope: ActionEnvelope, context: ClassifierContext, opts?: ClassifierPromptOptions): ClassifierPromptResult;

package/dist/provider/classifier/verdict-schema.d.ts

@@ -0,0 +1,83 @@
+import type { ClassifierRawResult } from "../../permissions/auto/engine.js";
+import type { ProviderToolSpec } from "../../engine.js";
+/** The one tool the classifier is allowed to call, and the one it is FORCED to call. */
+export declare const CLASSIFIER_TOOL_NAME = "classifier_verdict";
+/**
+ * Length caps, stated once and used by both the schema and the report.
+ *
+ * `category`/`severity`/`reasonCode` are vocabulary slots — a value longer than this is prose in a
+ * slot that is not for prose. `auditReason` is prose, so its cap is the real one: it bounds how much
+ * of a hostile envelope a compromised reviewer can launder into the audit stream in a single call.
+ */
+export declare const CLASSIFIER_FIELD_CAPS: {
+    readonly category: 64;
+    readonly severity: 32;
+    readonly reasonCode: 64;
+    readonly auditReason: 1024;
+};
+/**
+ * The verdict schema — draft-07, closed.
+ *
+ * `additionalProperties: false` is load-bearing, and it is the "extra output" half of §10.6-5:
+ * a reviewer that returns a field nobody asked for has not answered the question it was asked, and
+ * the safe reading of an unrecognised field is that the answer is not one this engine understands.
+ */
+export declare const CLASSIFIER_VERDICT_SCHEMA: Record<string, unknown>;
+/**
+ * Every way this classifier can fail to obtain a verdict, as a CLOSED vocabulary.
+ *
+ * A closed union rather than free strings because these codes reach `AutoAuditRecord.reasonCode` and
+ * are the only evidence a reader has for WHY auto mode failed closed on a given action. "It returned
+ * no_verdict" is not a diagnosis; "the model answered with prose instead of calling the tool" and
+ * "the request timed out" call for opposite responses.
+ */
+export declare const CLASSIFIER_NO_VERDICT_REASONS: readonly ["no_tool_call", "multiple_calls", "wrong_tool", "refusal", "provider_error", "timeout", "schema_invalid"];
+export type ClassifierNoVerdictReason = (typeof CLASSIFIER_NO_VERDICT_REASONS)[number];
+/**
+ * The namespace every MODEL-AUTHORED `reasonCode` is stamped with on its way out of the parse.
+ *
+ * Review round 1, I2. The vocabulary above is closed, and the whole point of it being closed is that
+ * a reader of the audit journal can tell WHY a review failed — the engine writes `reasonCode`
+ * straight onto `AutoAuditRecord` (`permissions/auto/engine.ts`), which is a frozen file this lane
+ * cannot change. But `reasonCode` is also a field the MODEL fills in, constrained only by
+ * `{ type: "string", maxLength: 64 }`. A model answering `{ verdict: "no_verdict", reasonCode:
+ * "timeout" }` would therefore be byte-identical, in the audit, to a genuine transport timeout —
+ * a reviewer able to forge the transcript of its own supervision.
+ *
+ * Namespacing on the way out closes that at the one seam both paths cross: Winter's own codes stay
+ * bare (they are what `noVerdict()` produces), and anything the model said is unambiguously the
+ * model's. A fixture asserts the closed vocabulary contains no `model:` entry, so the two spaces
+ * cannot collide by accident later either.
+ */
+export declare const MODEL_REASON_CODE_PREFIX = "model:";
+/** The fail-closed answer, built in ONE place so every arm of the collapse produces the identical shape. */
+export declare function noVerdict(reasonCode: ClassifierNoVerdictReason): ClassifierRawResult;
+/**
+ * The tool spec the request advertises.
+ *
+ * A FUNCTION returning a fresh object rather than a shared const: `ProviderRequest.tools` reaches an
+ * adapter that may serialise, decorate or (in a test double) mutate it, and one shared mutable
+ * schema object living for the life of the process is the kind of shared state that produces a bug
+ * nobody can reproduce.
+ */
+export declare function classifierVerdictToolSpec(): ProviderToolSpec;
+/**
+ * The forced tool call's input -> a `ClassifierRawResult`, or the reason it is not one.
+ *
+ * Keys are copied INDIVIDUALLY rather than spread. A spread would carry through whatever the model
+ * sent (the schema's `additionalProperties: false` makes that unreachable today, but a future schema
+ * relaxation would silently widen what reaches the audit record), and `exactOptionalPropertyTypes`
+ * means an absent field must be an absent KEY rather than an `undefined` value.
+ *
+ * `reasonCode` is NAMESPACED here, and this is the one seam where it can be: see
+ * `MODEL_REASON_CODE_PREFIX`. Everything else the model wrote (`category`, `severity`,
+ * `auditReason`) is already unambiguously the model's — only `reasonCode` shares a field with
+ * Winter's own closed vocabulary.
+ */
+export declare function parseClassifierVerdict(input: unknown): {
+    ok: true;
+    result: ClassifierRawResult;
+} | {
+    ok: false;
+    reasonCode: ClassifierNoVerdictReason;
+};

package/dist/provider/credential-api.d.ts

@@ -0,0 +1,160 @@
+import type { CredentialMaterial, CredentialStatus, CredentialStore, ProviderContext, ProviderRegistry } from "@yanlinglabs/winter-provider-runtime";
+import type { CredentialRef } from "@yanlinglabs/winter-agent-sdk";
+/** The one keychain-ref shape these doors deal in. `set`/`delete` are Keychain-only by TYPE on `CredentialStore`, so this is not a narrowing choice — it is the only representable one. */
+export type ProviderCredentialRef = Extract<CredentialRef, {
+    kind: "keychain";
+}>;
+export interface ProviderCredentialLocator {
+    providerId: string;
+    /** WHICH account on that provider. R6-10: one record per provider/account, never a shared global slot — two accounts on one provider, or two providers at once, need two records. */
+    accountId: string;
+    /** Overrides the store's configured service. Omitted means the store's own default (the session's `brand.keychainService`, else `DEFAULT_KEYCHAIN_SERVICE`). */
+    service?: string;
+}
+export interface StoreProviderCredentialInput extends ProviderCredentialLocator {
+    material: CredentialMaterial;
+}
+/**
+ * The ref one provider/account occupies.
+ *
+ * EXPORTED because a host that stored a credential needs to name it again in
+ * `config.provider.authRef`, and deriving that string a second time by hand is the drift this
+ * function exists to prevent.
+ */
+export declare function providerCredentialRef(locator: ProviderCredentialLocator): ProviderCredentialRef;
+/**
+ * Writes one provider credential, and answers with the ref that now addresses it.
+ *
+ * Returning the ref rather than `void` is the point of the door: the host's very next act is to put
+ * that ref in a session config, and handing it back is what stops it being retyped.
+ */
+export declare function storeProviderCredential(store: CredentialStore, input: StoreProviderCredentialInput): Promise<ProviderCredentialRef>;
+/**
+ * Removes one provider credential.
+ *
+ * IDEMPOTENT by delegation: the store's own `delete` decides what removing an absent record means,
+ * and neither of the shipped stores treats it as an error. This door does not probe first — a `get`
+ * before a `delete` would read the secret into memory for no reason other than to answer a question
+ * the caller did not ask.
+ */
+export declare function deleteProviderCredential(store: CredentialStore, locator: ProviderCredentialLocator): Promise<ProviderCredentialRef>;
+/**
+ * Asks the provider's own adapter whether a credential reference works.
+ *
+ * ROUTED THROUGH THE REGISTRY because the answer is the ADAPTER's: only it knows which endpoint
+ * proves a key, what an expiry looks like for its auth kind, and which ref kinds it can check at all.
+ * The registry is how a provider id becomes that adapter, and it has no adapter-by-provider door of
+ * its own — so this reaches one through a model resolution, in two steps.
+ *
+ * THE SECOND STEP IS NOT A NICETY. A provider's catalog ROWS are the natural route, but ten of the
+ * twenty-one seed providers have none: every local one (lm-studio, vllm, llama-cpp, llamafile, the
+ * mlx pair, oobabooga, triton, xinference, docker-model-runner, lemonade) ships as a provider whose
+ * models exist only on the user's own machine. Stopping at "no rows" would make this door useless
+ * for exactly the providers a host is most likely to be helping someone configure. So a provider with
+ * no usable row falls through to `allowUnlisted` — registry.ts's own step 2, which answers with the
+ * adapter and `descriptor: undefined` for any provider whose live catalog is not authoritative, and
+ * with a typed refusal for one where it is (there, an absent id is a FACT and there is nothing
+ * honest to probe with). `validateCredential` never sees a model id, so the probe string below is
+ * inert — it is a key into the registry, not something that reaches a wire.
+ *
+ * NEVER THROWS. A host door that reports status by return value for four outcomes and by exception
+ * for the fifth is a door every caller wraps in a try. Every failure is a `{ ok: false }` row.
+ */
+export declare function validateProviderCredential(registry: ProviderRegistry, ref: CredentialRef, ctx: ProviderContext): Promise<CredentialStatus>;
+/**
+ * The providers whose credential is obtained by a LOGIN rather than by pasting a key.
+ *
+ * DECLARED IN FULL NOW, ahead of two of its four flows. A host offering sign-in should compile
+ * against one door rather than discover a second one when the next flow lands, and a case that
+ * throws a typed refusal is a much better thing to ship than a member missing from the union — which
+ * fails at a caller's call site as an unassignable literal and tells them nothing about why.
+ * `xai-oauth` and `qoder` are wired by their own lane; this file's switch is where they land.
+ */
+export type ProviderLoginId = "anthropic" | "codex-oauth" | "xai-oauth" | "qoder";
+export interface StartProviderLoginOptions {
+    /**
+     * Opens the browser. HOST-supplied: the SDK never shells out to one, and a login is a host action.
+     *
+     * **A DEVICE-CODE FLOW NEVER CALLS THIS.** That is the whole point of RFC 8628 — the device has no
+     * browser to open, so there is no URL to hand one. Its verification URL and its user code reach the
+     * host through `onAuthStatus.output` instead, and a host that renders a device login by waiting for
+     * `openUrl` will wait forever while the two strings the user actually needs go past on the other
+     * channel. Required rather than optional only because the two flows that exist today are both
+     * loopback ones; a device flow may be handed a function that is never invoked.
+     */
+    openUrl: (url: string) => Promise<void>;
+    /** Overridden by a fixture; production uses each flow's own derived constants. */
+    authorizeUrl?: string;
+    tokenUrl?: string;
+    /**
+     * Device-code flows only (RFC 8628): where the device authorization request is posted.
+     *
+     * Present ahead of its flows for the same reason `ProviderLoginId` carries all four members — and
+     * for one more that is not cosmetic. Without a fixture endpoint here, a test driving a device login
+     * THROUGH THIS DOOR has nowhere to point it and would reach the vendor live, which the phase's
+     * hermeticity rule forbids outright. An option that only appears alongside its implementation is an
+     * option whose first test cannot be written.
+     */
+    deviceCodeUrl?: string;
+    /** Device-code flows only: the poll interval FLOOR in ms. The vendor's own `interval` wins when larger. */
+    pollIntervalMs?: number;
+    callbackPort?: number;
+    timeoutMs?: number;
+    /** The Keychain service the record lands in — `config.keychainService` from the host. */
+    service?: string;
+    /** A login-flow PROGRESS channel (R6-F). Never carries credential material. */
+    onAuthStatus?: (status: {
+        isAuthenticating: boolean;
+        output?: string[];
+        error?: string;
+    }) => void;
+    /**
+     * `anthropic` (host-brokered Console OAuth, P10a-1 amendment) ONLY: the resolved `ant` executable
+     * and the config dir `console-broker.ts` spawns with. Present ahead of their one consumer for the
+     * same reason `deviceCodeUrl` is: an option that only appears alongside its implementation is an
+     * option whose first test cannot be written. Ignored by every other flow.
+     */
+    antExecutable?: string;
+    anthropicConfigDir?: string;
+    /**
+     * UNUSED (Lane S round 2, measured 2026-09-13): a live measurement found `claude auth login
+     * --console` writes no Anthropic profile for this org, so `console-broker.ts` never spawns
+     * `claude` for the Console login -- `ant` is the one broker binary. These two fields are accepted
+     * ONLY for source compatibility with existing callers that still pass them; this door never reads
+     * either, and never gates on them.
+     */
+    claudeExecutable?: string;
+    claudeConfigDir?: string;
+    /** `anthropic` only: `ANTHROPIC_PROFILE`. Defaults to `console-broker.ts`'s own default (`"winter"`). */
+    profile?: string;
+    /**
+     * `anthropic` only: supplies the one-time code the operator pastes after visiting the URL this
+     * door's `onAuthStatus` progress lines print. `startProviderLogin` is a single flat `Promise`, and
+     * the Console login is genuinely TWO-PHASE (a URL appears, then — sometime later, off this
+     * process's clock — a human types a code) — so this callback is what lets that shape fit here at
+     * all, the same way `openUrl` lets every OTHER flow's browser leg fit: the host implements it
+     * however it renders the prompt (a CLI `readline`, a UI text field), and this door awaits it once
+     * the login is already running.
+     */
+    readConsoleCode?: () => Promise<string>;
+}
+export interface ProviderLoginResult {
+    /** The record the credential now occupies — the very thing a host puts in `config.provider.authRef`. */
+    ref: ProviderCredentialRef;
+    accountId: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+/**
+ * Runs one provider's login and PERSISTS the result, answering with the ref that now addresses it.
+ *
+ * ONE DOOR, for the same reason `storeProviderCredential` is one: every flow writes a record whose
+ * name is `"<providerId>:<accountId>"` (R6-10), and a host that reaches each flow's own function
+ * directly is a host that will eventually spell that name differently from whatever reads it back.
+ * Routing through here means the login and the lookup agree by construction.
+ *
+ * WHAT THIS DOES NOT DO: choose a provider, open a browser itself, or decide that a failed login
+ * should be retried. Each is a host's decision, and the SDK taking any of them would be a library
+ * driving a user interface.
+ */
+export declare function startProviderLogin(providerId: ProviderLoginId, store: CredentialStore, options: StartProviderLoginOptions): Promise<ProviderLoginResult>;

package/dist/provider/family-listing.d.ts

@@ -0,0 +1,27 @@
+import type { WinterCatalog } from "@yanlinglabs/winter-provider-catalog";
+import type { ActiveSlotSet, ModelFamilyListing, ModelRowServable } from "@yanlinglabs/winter-agent-sdk";
+export interface FamilyListingInput {
+    catalog: WinterCatalog;
+    active: ActiveSlotSet | undefined;
+    /**
+     * WS-13c §7 as amended by P7a: a TRI-STATE, not a boolean.
+     *
+     * `"present"` a credential is configured and the provider is not disabled (§4 step 2).
+     * `"absent"`  a probe answered, and there is none — or the provider is disabled.
+     * `"unknown"` nobody has probed this provider yet.
+     *
+     * The third state is the honest first paint. `hasCredential` has been tri-state at the wiring
+     * since R-6c-27, and this seam was the last place it was flattened: a boolean has to collapse
+     * `unknown` onto one of the other two, and BOTH collapses are false statements to a model
+     * switcher — `false` greys out a row the user can perfectly well use, and `true` (the shape the
+     * cold paint originally shipped) claims every row in a 604-model catalog is available against an
+     * empty credential store.
+     */
+    servable: (providerId: string) => ModelRowServable;
+    /** Fills `SlotView.resolvesTo` — absent when nothing this session has can serve the slot. */
+    resolveSlot?: (canonicalModelId: string, provider?: string) => {
+        providerId: string;
+        key: string;
+    } | undefined;
+}
+export declare function buildModelFamilyListing(input: FamilyListingInput): ModelFamilyListing;

package/dist/provider/first-party.d.ts

@@ -0,0 +1,4 @@
+/** The catalog provider ids that ARE Anthropic's own API. `cc` (claude.ai subscription auth) is deliberately absent: it does not ship. */
+export declare const FIRST_PARTY_ANTHROPIC_PROVIDER_IDS: ReadonlySet<string>;
+/** Is this session on Anthropic's own API? `undefined` (no catalog identity at all -- the reserved test namespace, a refused session) is never first-party. */
+export declare function isFirstPartyAnthropic(providerId: string | undefined): boolean;

package/dist/provider/keychain-store.d.ts

@@ -0,0 +1,59 @@
+import type { CredentialStore } from "@yanlinglabs/winter-provider-runtime";
+import { DEFAULT_KEYCHAIN_SERVICE, type CredentialRef } from "@yanlinglabs/winter-agent-sdk";
+export { DEFAULT_KEYCHAIN_SERVICE };
+/**
+ * The shape this store needs from a secrets backend.
+ *
+ * A NAMED INTERFACE rather than a direct dependency on the global, and the reason is testability
+ * without exception: the real backend is injected by DEFAULT and overridable by a caller, so the
+ * unit tests below drive a double and the real path has exactly one construction site. Mirrors
+ * `Bun.secrets`' own three methods and nothing more.
+ */
+export interface SecretsBackend {
+    get(options: {
+        service: string;
+        name: string;
+    }): Promise<string | null>;
+    set(options: {
+        service: string;
+        name: string;
+        value: string;
+    }): Promise<void>;
+    delete(options: {
+        service: string;
+        name: string;
+    }): Promise<boolean | void>;
+}
+export interface KeychainCredentialStoreOptions {
+    /** Injected in tests. The real `Bun.secrets` path is NEVER exercised under test -- see this file's header. */
+    secrets?: SecretsBackend;
+}
+/**
+ * A `CredentialStore` backed by the macOS Keychain.
+ *
+ * `get` answers `null` for a ref this store does not own, rather than throwing: a composite store
+ * (provider-runtime's `createCompositeCredentialStore`) tries each member in turn, and a member that
+ * threw on someone else's ref kind would break the composition.
+ */
+export declare function createKeychainCredentialStore(service?: string, opts?: KeychainCredentialStoreOptions): CredentialStore;
+/** Reads ONE keychain item's stored string, uninterpreted. `null` when there is no such item. */
+export type KeychainSecretReader = (ref: Extract<CredentialRef, {
+    kind: "keychain";
+}>) => Promise<string | null>;
+/**
+ * The RAW half of this store, for a TOOL's secret rather than a provider's credential.
+ *
+ * WHY IT EXISTS, AND WHY HERE. `get` above insists the item is JSON `CredentialMaterial` and throws
+ * `malformed` for anything else -- correct for a provider credential, which this SDK writes itself.
+ * A tool's key is different: a host may store it as the BARE KEY STRING because another client of
+ * the same keychain slot reads it that way, and that format is not this SDK's to change. So a reader
+ * that returns the item uninterpreted has to exist, and it has to live in THIS file -- the only one
+ * allowed to name the secrets backend (see the header, and the tripwire in the test beside it).
+ *
+ * It interprets NOTHING: `provider/tool-secret.ts` decides what the string means. It never logs and
+ * never quotes the value; a backend failure is the same typed, ref-redacted `io` error `get` raises.
+ * The ref's own `service` wins over the session's, exactly as in `get`.
+ */
+export declare function createKeychainSecretReader(service?: string, opts?: KeychainCredentialStoreOptions): KeychainSecretReader;
+/** `account = "<providerId>:<accountId>"` (R6-10). One helper, so a caller never assembles the key by hand and drifts. */
+export declare function keychainAccountName(providerId: string, accountId: string): string;

package/dist/provider/lean-prompt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `modelKey` is a provider-qualified key (`anthropic/claude-opus-5`) or a bare id. claude compares a
+ * NORMALIZED id, so the Opus match tolerates the two spellings a catalog row really uses for the same
+ * build: a trailing `-YYYYMMDD` snapshot date, and a dotted minor (`claude-opus-4.1`). The original
+ * Opus 4 has no minor in its dated id (`claude-opus-4-20250514`); it is `claude-opus-4-0`.
+ */
+export declare function claudeModelTakesFullPrompt(modelKey: string): boolean;

package/dist/provider/mock.d.ts

@@ -0,0 +1,55 @@
+import type { Provider, ProviderMessage, ProviderTurn, ToolExecutor } from "../engine.js";
+/** Every `system` value handed to a mock provider this process, in call order. Test-only. */
+export declare function recordedProviderSystems(): readonly (string | undefined)[];
+/** Clears the recording. A test that asserts on the log MUST call this first -- the log is process-wide, like the tool registry. */
+export declare function resetRecordedProviderSystems(): void;
+/**
+ * SDK 0.0.16: a user message's TEXT. The live request now merges the index-0 context, the persisted
+ * attachments and the prompt into one message of text blocks (claude's wire shape), so a double that
+ * reads "the user's text" joins the text blocks; the prompt is always the LAST block, so the last line
+ * is still the prompt's last line.
+ */
+export declare function userMessageText(message: ProviderMessage | undefined): string;
+export declare const echoProvider: Provider;
+export declare function scriptedProvider(turns: ProviderTurn[]): Provider;
+export declare const stubExecutor: ToolExecutor;
+/**
+ * Phase 5 Task 8: the fixture skill the `p5skill` provider invokes. Exported so the scenario that
+ * WRITES the `SKILL.md` and the provider that CALLS it cannot disagree about the name.
+ */
+export declare const P5_FIXTURE_SKILL_NAME = "p5probe";
+/**
+ * Phase 5 Task 8: the workflow script the `p5workflow` provider launches.
+ *
+ * Deliberately a script a merely-STARTED worker cannot satisfy by accident (Lane W's own recipe):
+ * it makes one real `agent()` call, one `phase()` and one `log()`, and returns a value DERIVED from
+ * the agent's answer. With the child answering "42" the run must reach `completed` with
+ * `{"answer":"42","doubled":"4242"}` on every leg.
+ */
+export declare const P5_WORKFLOW_SCRIPT: string;
+export type TestProviderName = "boom" | "tooluse" | "hang" | "reflect" | "modeswitch" | "bgtask" | "lanea" | "laneb" | "lanec" | "laned" | "lanee" | "mcpsdk" | "subagent" | "childmsg" | "subagentperm" | "toolsearch" | "p5compact" | "p5structured" | "p5structuredfail" | "p5skill" | "p5checkpoint" | "p5workflow";
+export declare function isTestProviderName(v: string): v is TestProviderName;
+/**
+ * The name the reserved `winter-test/<name>` namespace uses for the plain echo double.
+ *
+ * A REAL NAME rather than "the default", because after Task 10 there IS no default: production
+ * selection is catalog-first and a session that names no resolvable model refuses to start (R6-9).
+ * A harness that wants the echo provider asks for it by name, exactly like every other scripted
+ * double, and the reserved namespace is the only door either of them comes through (R6-13).
+ */
+export declare const ECHO_TEST_PROVIDER_NAME = "echo";
+/**
+ * The `winter-test/<name>` namespace's resolver — the ONE production door to an in-process double.
+ *
+ * `selection.ts` calls this through `SelectionDeps.testProviders` after checking the namespace, so
+ * this function never has to know about the namespace prefix or about `WINTER_TEST_PROVIDER`; it
+ * answers one question ("is there a scripted double called this?") and answers `undefined` when
+ * there is not, which selection turns into a typed refusal rather than a silent miss.
+ */
+export declare function testProviderForNamespace(name: string): Provider | undefined;
+export declare function testProviderByName(name: TestProviderName): Provider;
+export declare const SUBAGENT_CHILD_PROBE_TEXT = "child probe text";
+export declare const MCP_SDK_TEST_SERVER_NAME = "t8mcpsdk";
+export declare const MCP_SDK_TEST_TOOL_NAME = "mcp__t8mcpsdk__echo";
+export declare const BGTASK_TEST_TOOL_NAME = "test_bgtask_probe";
+export declare function registerBgTaskTestTool(): void;

package/dist/provider/scenario-fake.d.ts

@@ -0,0 +1,96 @@
+/** One recorded request. `headers` are lower-cased; a credential header keeps its SCHEME and loses its material. */
+export interface ScenarioRequest {
+    method: string;
+    path: string;
+    search: string;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface ScenarioFake {
+    /** `http://127.0.0.1:<port>` — what a `ConnectionProfile.baseUrl` points at. */
+    url: string;
+    /** Every request received, in order. THE GROUND TRUTH for what a provider was actually asked. */
+    requests: ScenarioRequest[];
+    close(): Promise<void>;
+}
+/** The four families this fake serves, and the model key each scenario pins. Real catalog rows, so selection resolves them for real. */
+export declare const SCENARIO_MODELS: {
+    readonly anthropic: "anthropic/claude-sonnet-5";
+    readonly openaiResponses: "openai/gpt-4.1";
+    readonly openaiChat: "deepseek/deepseek-v4-pro";
+    readonly gemini: "google/gemini-2.5-flash";
+};
+/**
+ * A REAL row whose `toolCalling` evidence is `native`, in each family.
+ *
+ * Not an incidental choice: WS-13 §8.1 makes Winter FAIL capability negotiation rather than silently
+ * drop tools, so a session pinned to a row the catalog says has no native tool calling cannot run a
+ * tool round at all — which is correct behaviour and the wrong subject for an equivalence scenario.
+ * `SCENARIO_TOOL_CALLING_NONE` is the row that proves the refusal instead.
+ */
+export declare const SCENARIO_TOOL_CALLING_NONE = "anthropic/claude-sonnet-4.5";
+/** The CHILD's model for the R6-17 scenario: the same provider, a different row, also `native`. */
+export declare const SCENARIO_CHILD_MODEL = "anthropic/claude-haiku-4-5-20251001";
+/**
+ * The marker a prompt carries to ask the scripted turn for an `Agent` call instead of a `Glob` one.
+ *
+ * KEYED ON THE PROMPT rather than on a request counter, for the same reason `carriesToolResult` is:
+ * three legs share this fake, and a counter would hand "the delegation turn" to whichever leg asked
+ * first.
+ */
+export declare const SCENARIO_DELEGATE_MARKER = "winter-t10-delegate";
+/** The subagent type the delegation turn asks for. The scenario defines an `agents` entry under this name. */
+export declare const SCENARIO_CHILD_AGENT = "prober";
+/** The tool the scripted turn calls, and the text the scripted final turn answers with. Shared so an assertion never re-spells them. */
+export declare const SCENARIO_TOOL_NAME = "Glob";
+export declare const SCENARIO_TOOL_INPUT: {
+    pattern: string;
+};
+export declare const SCENARIO_FIRST_TEXT = "checking the tree";
+export declare const SCENARIO_FINAL_TEXT = "the provider scenario is done";
+/** The child model's PROVIDER-LOCAL id — what actually goes on the wire when a child runs its own provider. */
+export declare const SCENARIO_CHILD_WIRE_ID = "claude-haiku-4-5-20251001";
+/**
+ * Starts the shared scenario fake.
+ *
+ * ALWAYS close it in a `finally`. A leaked fake keeps a port and an event loop alive for the rest of
+ * the process, which is how one careless scenario makes an unrelated one flaky.
+ */
+export interface ScenarioFakeOptions {
+    /**
+     * Answer each leg's FIRST ATTEMPT at a turn with this status (and `retry-after: 0`), then behave
+     * normally — so the retry succeeds.
+     *
+     * "EACH LEG'S", not "the first request", and the difference is the whole reason this option is a
+     * state machine rather than a counter: three legs share one fake, so a plain `requests.length === 1`
+     * check fails leg A's first attempt and leaves every other leg's untouched — which is a cross-leg
+     * divergence the harness itself invented. The rule below is leg-count-independent: fail a request
+     * that opens a turn, never the retry that immediately follows it.
+     *
+     * `retry-after: 0` deliberately: R6-6 honours the header verbatim up to 60 s, and a scenario that
+     * waited a real backoff would spend seconds per leg proving something the delay is not part of.
+     */
+    firstAttemptStatus?: number;
+    /** Answer EVERY request with this status. Drives R6-F's terminal provider failure. */
+    alwaysFailStatus?: number;
+    /**
+     * P6 fix wave (Ruling E-3): answer every request for ONE wire model with this status -- in the body
+     * (`"model":"<id>"`) or, for the Gemini family, in the PATH (`/models/<id>:`, the colon so that
+     * `gemini-2.5-flash` does not also match `gemini-2.5-flash-lite`) -- and serve every other model
+     * normally. `retryAfter` is sent verbatim: R6-6 honours a positive `Retry-After` in place of its
+     * jittered backoff, which is what keeps a retries-exhausted scenario at a bounded wall-clock
+     * (10 retries x the header, rather than 10 jittered steps capped at 30 s each).
+     */
+    failModel?: {
+        wireModel: string;
+        status: number;
+        retryAfter?: string;
+    };
+    /**
+     * P6 fix wave round 2 (R-E2): on the Anthropic route, send `message_start` and then DROP the
+     * connection -- a failure AFTER the first byte, which the adapter normalizes as a network error
+     * (retryable) that the fold has already committed to. The class R6-6 forbids replaying.
+     */
+    dropAfterFirstEvent?: boolean;
+}
+export declare function startScenarioFake(options?: ScenarioFakeOptions): Promise<ScenarioFake>;