@yanlinglabs/winter-runtime-sdk 0.0.1 → 0.0.3

package/dist/messaging/index.d.ts

@@ -2,7 +2,7 @@ export { createRuntimeDirectory } from "../directory/directory.js";
 export type { DirectorySnapshot, RuntimeDirectoryHandle, RuntimeDirectoryOptions } from "../directory/directory.js";
 export type { RuntimeDirectoryRecoveryHooks, RuntimeDirectoryRetention } from "../directory/recovery.js";
 export { entryToChildLike, entryToListedRuntimeObject, entryToListedRuntimeObjectList, isListableFrom, isLiveStatus, isResolvableFrom, mergeAdapterOwnedFields, owningSessionIdOf, parentAddressOf, sessionAddressOf } from "../directory/entries.js";
-export { createGlobalMessaging, callerAddressOf, deriveMessageId } from "./router.js";
+export { createGlobalMessaging, deriveMessageId } from "./router.js";
 export type { GlobalMessagingContext, GlobalMessagingHandle, GlobalMessagingOptions, ReplyRequest } from "./router.js";
 export { createWinterMessagingAdapter } from "./winter-adapter.js";
 export type { WinterMessagingAdapter, WinterMessagingAdapterDeps } from "./winter-adapter.js";
@@ -15,8 +15,6 @@ export type { InboundPolicy, InboundPolicyDeps, InboundPolicyHooks, InboundVerdi
 export { createAttachedSessionRegistry } from "./sessions.js";
 export type { AttachedOfficialSession, AttachedSession, AttachedSessionRegistry, AttachedWinterSession, LiveSessionStatus } from "./sessions.js";
 export { renderAttributedTurn, renderOwnerQualifiedTurn, UnattributableSenderError } from "./attribution.js";
-export { createMessagingToolHandlers, toolUseIdFromExtra, VENDOR_TOOL_USE_ID_META_KEY } from "./handlers.js";
-export type { MessagingToolCaller, MessagingToolHandler, MessagingToolHandlers, MessagingToolResult } from "./handlers.js";
 import { type RuntimeDirectoryHandle, type RuntimeDirectoryOptions } from "../directory/directory.js";
 import type { SeamContext } from "../seams/context.js";
 import { type GlobalMessagingHandle, type GlobalMessagingOptions } from "./router.js";

package/dist/messaging/router.d.ts

@@ -2,7 +2,7 @@ import type { NotificationRecord, SendMessageResult } from "@yanlinglabs/winter-
 import type { RuntimeDirectoryHandle } from "../directory/directory.js";
 import type { SeamContext } from "../seams/context.js";
 import type { GlobalMessaging, SendMessageRequest } from "../seams/global-messaging.js";
-import type { DeliveryOutcome, GlobalAgentMessage, RuntimeAddress, SerializedRuntimeAddress } from "../seams/messaging-contract.js";
+import type { DeliveryOutcome, GlobalAgentMessage, SerializedRuntimeAddress } from "../seams/messaging-contract.js";
 import { type InboundPolicyHooks } from "./inbound.js";
 import { type OfficialMessagingAdapter, type OfficialMessagingAdapterDeps } from "./official-adapter.js";
 import { type AttachedOfficialSession, type AttachedWinterSession } from "./sessions.js";
@@ -88,14 +88,3 @@ export interface GlobalMessagingHandle extends GlobalMessaging {
  */
 export declare function deriveMessageId(senderSessionId: string, toolUseId: string): string;
 export declare function createGlobalMessaging(context: GlobalMessagingContext, options?: GlobalMessagingOptions): GlobalMessagingHandle;
-/**
- * The canonical address a `SendMessage`/`ListAgents` handler runs AS (see `handlers.ts`).
- *
- * The subpath's own `callerAddress` builds `agent:<parent>:<child>` for a child caller and
- * `session:<id>` for a top-level one — the same rule the resolution fence reads, so the handler and
- * the router can never disagree about who is asking.
- */
-export declare function callerAddressOf(caller: {
-    sessionId: string;
-    agentId?: string;
-}): RuntimeAddress;

package/dist/official/aliases.d.ts

@@ -6,14 +6,18 @@ export declare const ALIASED_BUILTINS: readonly [{
 }, {
     readonly builtin: "ListAgents";
     readonly tool: "list_agents";
+}, {
+    readonly builtin: "ReadNotifications";
+    readonly tool: "read_notifications";
+}, {
+    readonly builtin: "advisor";
+    readonly tool: "advisor";
 }];
 export type AliasedBuiltin = (typeof ALIASED_BUILTINS)[number]["builtin"];
 /** §2's `toolAliases` value: `{ SendMessage: "mcp__<server>__send_message", … }`. */
 export declare function officialToolAliases(brand: Pick<BrandProfile, "mcpServerName">): Record<string, string>;
 /** The canonical name one aliased built-in resolves to (single hop — never a chain). */
 export declare function aliasTargetFor(builtin: AliasedBuiltin, brand: Pick<BrandProfile, "mcpServerName">): string;
-export { LIST_AGENTS_FIELD_MAX, NATIVE_LIST_AGENTS_OUTPUT_SCHEMA, NATIVE_LIST_AGENTS_SCHEMA, NATIVE_SEND_MESSAGE_SCHEMA, SEND_MESSAGE_SUMMARY_MAX, SEND_MESSAGE_TO_MAX, acceptNativeListAgentsArgs, acceptNativeSendMessageArgs, } from "../native-args.js";
-export type { NativeArgsResult, NativeListAgentsArgs, NativeSendMessageArgs } from "../native-args.js";
 /**
  * How the canonical duplicates are exposed (§7's "SHOULD be deferred/hidden").
  *

package/dist/official/index.d.ts

@@ -17,8 +17,8 @@ export { EXECUTION_INDIRECTION_ENV_NAMES, EXECUTION_INDIRECTION_ENV_PREFIXES, is
 export type { EnvAllowlistSnapshot, OfficialEnvInput, OfficialEnvPolicy } from "./env-allowlist.js";
 export { OFFICIAL_ERROR_CODES, OfficialStdoutUnterminatedError, OfficialAgentResultError, OfficialApiError, OfficialBranchError, OfficialConfigurationError, OfficialConnectionError, OfficialExecutableNotFoundError, OfficialInterruptedError, OfficialInvalidResumeError, OfficialKilledError, OfficialMcpError, OfficialNonzeroExitError, OfficialPermissionDeniedError, OfficialProtocolError, OfficialSessionNotFoundError, OfficialSessionStoreError, OfficialToolError, isOfficialBranchError, } from "./errors.js";
 export type { OfficialCrashClass, OfficialErrorCode, WinterErrorClassName } from "./errors.js";
-export { OFFICIAL_MATERIALIZATION_DROPS, assertNoAdvisor, canonicalToolNames, materializeOfficialMcpServer, messagingToolDescriptors, officialMcpServers, winterMcpServerDescriptor } from "./mcp-descriptors.js";
-export type { InputShapeFactory, JsonSchemaObject, MessagingHandlers, OfficialMcpModule, WinterMcpHandler, WinterMcpServerDescriptor, WinterMcpToolDescriptor, WinterMcpToolResult } from "./mcp-descriptors.js";
+export { OFFICIAL_MATERIALIZATION_DROPS, canonicalToolNames, materializeOfficialMcpServer, officialMcpServers, winterMcpServerDescriptor } from "./mcp-descriptors.js";
+export type { InputShapeFactory, JsonSchemaObject, OfficialMcpModule, WinterMcpHandler, WinterMcpServerDescriptor, WinterMcpToolDescriptor, WinterMcpToolResult } from "./mcp-descriptors.js";
 export { AUTO_MEMORY_LOAD_CAP, DEFAULT_EXCLUDE_DYNAMIC_SECTIONS, PINNED_SYSTEM_PROMPT_PRESET, assertOptionsInvariants, brandedFlagSettings, buildOfficialOptions, captureOptions, mergeHooks } from "./options-template.js";
 export type { OptionsTemplatePolicy } from "./options-template.js";
 export { SPOOL_SEGMENTS, classifyLocalWriteRoot, officialSpoolRoot, validateObservedConfigDir, vendorTempRootReport } from "./spool.js";

package/dist/official/mcp-descriptors.d.ts

@@ -1,10 +1,15 @@
-import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
-/** A JSON-Schema object, in the subset the descriptors use. */
-export interface JsonSchemaObject {
-    type: "object";
-    properties: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
-    required?: readonly string[];
-}
+import { type BrandProfile, type McpSdkServerConfigWithInstance } from "@yanlinglabs/winter-agent-sdk";
+import { type AdvisorToolDeps, type JsonSchemaObject, type MessagingToolPort, type WinterToolCaller } from "@yanlinglabs/winter-agent-sdk/tools";
+import { RuntimeLaunchInputError } from "../errors.js";
+/**
+ * ONE `JsonSchemaObject`, AND IT IS THE SDK'S (interim review I-3).
+ *
+ * The router used to declare its own — `properties` required, no `additionalProperties` — and every
+ * composition of an SDK schema into a descriptor went through `as unknown as JsonSchemaObject`. Two
+ * types for one contract is how the two copies of the native schemas drifted in the first place
+ * (barrel-exports.test.ts's own header), so the type travels with the definitions it describes.
+ */
+export type { JsonSchemaObject };
 /** What a handler answers with — the MCP content shape, identical on both branches. */
 export interface WinterMcpToolResult {
     content: Array<{
@@ -16,20 +21,20 @@ export interface WinterMcpToolResult {
 /**
  * A tool handler, and the vendor's own second argument (item 15).
  *
- * `extra` IS FORWARDED, NOT DROPPED — but what it CARRIES is a measurement, not an assumption. The
- * carry that produced this change asked for it so the official branch could derive WS-10 §12's retry
- * key (the (session, tool-call id) pair a retry must allocate the SAME message id from), and the
- * whole-branch review was right to say that must be checked first: the in-process server's `extra` is
- * the MCP REQUEST CONTEXT — the JSON-RPC request id and `_meta` — which is not the model's
- * `tool_use_id`. `test/official/runtime-aliases.test.ts` records what the pinned runtime actually
- * puts there; see that test and this module's own note below for the answer.
- *
- * Forwarding it is worth doing either way: it is the only channel the vendor gives a tool for request
- * context, dropping it is unrecoverable at the handler, and a handler that does not want it simply
- * declares one parameter.
+ * `extra` IS FORWARDED, NOT DROPPED, and what it carries is measured rather than assumed: on 0.3.250
+ * `extra._meta["claudecode/toolUseId"]` is the id the model emitted, which is the half of WS-10 §12's
+ * retry key the official branch could not otherwise have. The SDK's `toolUseIdFromExtra` reads it (and
+ * falls back to the bound caller's id), so the router forwards the argument and decides nothing.
  */
 export type WinterMcpHandler = (args: unknown, extra?: unknown) => Promise<WinterMcpToolResult>;
-/** One tool on the standing server. Everything a branch needs to register it, and nothing branch-specific. */
+/**
+ * One tool on the standing server — the ROUTER'S OWN COMPOSITION TYPE, and nothing more (R-8-1).
+ *
+ * It is a `WinterToolDefinition` (the SDK's: bare name, description, schemas, annotations, permission
+ * class) plus the two things only a HOST can supply: the handler that runs it and how this branch
+ * exposes it. The router declares no tool of its own — every field but those two is read off the
+ * definition the SDK owns.
+ */
 export interface WinterMcpToolDescriptor {
     /** The bare tool name (`send_message`); the canonical name is derived from it and the brand. */
     tool: string;
@@ -49,43 +54,51 @@ export interface WinterMcpServerDescriptor {
     version: string;
     tools: readonly WinterMcpToolDescriptor[];
 }
-/** The two messaging handlers §7's aliases resolve to. Their implementations are the router's. */
-export interface MessagingHandlers {
-    sendMessage: WinterMcpHandler;
-    listAgents: WinterMcpHandler;
-}
 /**
- * The messaging tools, with the NATIVE schemas mirrored (§7: "handlers MUST accept the native
- * argument schemas exactly").
+ * THE STANDING SERVER, COMPOSED FROM THE SDK'S DEFINITIONS AND THE SDK'S HANDLER FACTORIES (R-8-1).
  *
- * `deferred` on both: they are the canonical twins of aliased built-ins, and §7 wants the model to
- * see one `SendMessage`, not two.
- */
-export declare function messagingToolDescriptors(handlers: MessagingHandlers): readonly WinterMcpToolDescriptor[];
-/**
- * §11's refusal: no advisor on this server, on this branch.
+ * THE ROUTER OWNS NO TOOL. It used to declare `send_message` and `list_agents` here — their
+ * descriptions, their native schemas, their acceptors — beside a second copy of the same declarations
+ * inside the Winter runtime, and the two had already drifted on what `to` may contain and on what an
+ * over-long `summary` does. `@yanlinglabs/winter-agent-sdk/tools` is now the single declaration, and
+ * this function is what BINDS it: `WINTER_DEFAULT_TOOL_DEFINITIONS` × the SDK's handler factories,
+ * under the brand's server name.
  *
- * Thrown rather than filtered. A silent filter would leave a host believing its advisor was
- * registered and wondering why the model never calls it; the whole point of D29's split is that each
- * branch's advisor has a DIFFERENT backing, and a host that tried to register one here has a
- * misunderstanding worth surfacing.
- */
-export declare function assertNoAdvisor(tools: readonly WinterMcpToolDescriptor[], branchLabel: string): void;
-/**
- * Builds the standing server descriptor for a session.
+ * THE PORT IS PASSED STRAIGHT THROUGH (ruling P-3). `GlobalMessagingHandle` satisfies
+ * `MessagingToolPort` structurally — `sendDetailed`, `listReachable({from})`, `readNotifications(id)`
+ * — so the router needs no adapter of its own and `messagingToolPortFromRuntimeDeps` (which adapts the
+ * RUNTIME's deps) is never used here.
  *
- * The capability plugins (browser, computer, office) are passed IN rather than declared here: WS-06
- * owns their exact names and schemas, and a copy of them in the router would be a second declaration
- * to drift. What the router owns is that they are registered under the same canonical names, with the
- * same identity, on both branches — which is what `canonicalToolNames` below makes checkable.
+ * THE ADVISOR IS ALWAYS REGISTERED (interim review I-5). The Winter runtime always advertises
+ * `advisor`; gating the official branch's copy on a host option would make the two legs' advertised
+ * sets differ by a setting that changes nothing on the other leg. `advisor.resolveReviewer` supplies
+ * the reviewer — its default answers `undefined`, which is WS-06 §4's ordinary tool error, not a throw.
  */
 export declare function winterMcpServerDescriptor(args: {
     brand: Pick<BrandProfile, "mcpServerName">;
-    messaging: MessagingHandlers;
+    port: MessagingToolPort;
+    caller: WinterToolCaller | (() => WinterToolCaller);
+    advisor: Omit<AdvisorToolDeps, "resolveReviewer"> & Partial<Pick<AdvisorToolDeps, "resolveReviewer">>;
     capabilities?: readonly WinterMcpToolDescriptor[];
     version?: string;
-    branchLabel: string;
 }): WinterMcpServerDescriptor;
+/** One capability server, as a descriptor the official branch can register. */
+export declare function capabilityServerDescriptor(server: McpSdkServerConfigWithInstance, version?: string): WinterMcpServerDescriptor;
+/**
+ * The ONE refusal both legs raise when a caller's own `mcpServers` key names a forwarded capability.
+ *
+ * IT IS SHARED BECAUSE THE TWO LEGS MUST SAY THE SAME THING (review r1). The Winter leg refuses in
+ * `forwardableOptions`, the official leg before its launch; the same mistake producing a typed error
+ * on one leg and a silent per-key override on the other would leave the two branches advertising
+ * different tools under one name, with nothing to read about it. Two copies of this sentence is how
+ * that starts being true again, so there is one.
+ */
+export declare function capabilityNameCollisionError(args: {
+    field: string;
+    name: string;
+}): RuntimeLaunchInputError;
+/** Every capability server, in the order the host declared them. */
+export declare function capabilityServerDescriptors(servers: readonly McpSdkServerConfigWithInstance[]): readonly WinterMcpServerDescriptor[];
 /** The canonical names a descriptor registers — the identity both branches must agree on. */
 export declare function canonicalToolNames(descriptor: WinterMcpServerDescriptor, brand: Pick<BrandProfile, "mcpServerName">): readonly string[];
 /** The subset of the injected official module this needs. Duck-typed: the seam declares only `query`. */
@@ -119,7 +132,6 @@ export declare function materializeOfficialMcpServer(args: {
     toInputShape: InputShapeFactory;
     branchLabel: string;
 }): unknown;
-/** `Options.mcpServers` for this branch: one entry, keyed by the brand's own server name. */
 /** The descriptor fields the official branch's registration cannot carry (review r1, n3). */
 export declare const OFFICIAL_MATERIALIZATION_DROPS: readonly string[];
 export declare function officialMcpServers(args: {

package/dist/sdk.d.ts

@@ -1,4 +1,4 @@
-import type { BrandProfile, Options, Query, SessionKey } from "@yanlinglabs/winter-agent-sdk";
+import type { BrandProfile, McpSdkServerConfigWithInstance, Options, Query, SessionKey } from "@yanlinglabs/winter-agent-sdk";
 import { type RouterOfficialInput, type RouterOfficialPolicy, type RouterQuery } from "./door.js";
 import type { SeamContextWithDirectory } from "./seams/context.js";
 import type { OfficialSdkModule } from "./seams/official-sdk-shapes.js";
@@ -11,6 +11,8 @@ import type { RuntimeDirectory } from "./seams/directory.js";
 import type { RuntimeDirectoryStore } from "./seams/directory-store.js";
 import type { GlobalMessagingOptions, RuntimeDirectoryOptions } from "./messaging/index.js";
 import type { HandoffBarrierDeps } from "./store/index.js";
+import type { ReviewerResolver } from "@yanlinglabs/winter-agent-sdk/tools";
+import { type InputShapeFactory } from "./official/mcp-descriptors.js";
 import type { RuntimeKind, RuntimeSelection, SelectionInput } from "./selection/runtime-selection.js";
 import { type VersionMatrixReport } from "./version-matrix.js";
 /**
@@ -38,6 +40,21 @@ export interface RuntimeSdkPeers {
 }
 export interface RuntimeSdkOptions {
     peers: RuntimeSdkPeers;
+    /**
+     * Host-declared peer package versions (D19a/R2, WS-02 §7.1) — THE ONLY DOOR inside a compiled
+     * binary. The version matrix's probe 2 (`resolved-manifest`) resolves a peer's `package.json` via
+     * `createRequire(...).resolve()`, which cannot see outside a compiled binary's own bundle
+     * (`file:///$bunfs/...`); a host that self-spawns its own compiled artifact and whose injected peer
+     * exports no version identity of its own (probe 1) has NOTHING for the matrix to read unless it
+     * declares one here, from its own vendored `VERSIONS.json`. Declaring a version wins over both
+     * probes when it parses — it does not bypass the matrix's range/exact-pin checks, only replaces how
+     * the identity was DISCOVERED; an unparseable declared value falls through to probe 1 rather than
+     * refusing on its own. Absent, behaviour is unchanged: probes 1 and 2, in that order.
+     */
+    peerVersions?: {
+        winterAgentSdk?: string;
+        claudeAgentSdk?: string;
+    };
     /** R-7b-2's seam; default = in-memory (which is also what every hermetic test uses). */
     directoryStore?: RuntimeDirectoryStore;
     /** Host-provided credential reads (WS-14 §12) — never disk, never this package's own keychain. */
@@ -57,6 +74,61 @@ export interface RuntimeSdkOptions {
      * fill in when neither does.
      */
     brand?: Partial<BrandProfile>;
+    /**
+     * WS-09 §1.3's capability servers, as the Winter SDK's own in-process shape — FORWARDED ON BOTH
+     * LEGS, never rewritten into anything else (R-8, and the user's tool-ownership ruling R-8-1).
+     *
+     * THE ROUTER OWNS NO TOOL. The daemon owns the capability tools — computer, browser, office — and
+     * hands them over as MCP SERVERS; this is the door they come through, and the router's whole job is
+     * to put the same servers in front of both runtimes. The Winter leg receives each entry BY
+     * REFERENCE under its own `name`, merged into `Options.mcpServers`. The official leg cannot take the
+     * object itself (its runtime registers in-process servers through its own constructor, over its own
+     * validator's schema shape), so the same tools are REGISTERED there from the server's own
+     * declaration — see `capabilityServerDescriptor`. Identical names, identical schemas, identical
+     * handlers, two registrations.
+     *
+     * THE BRAND'S OWN SERVER NAME IS RESERVED. `brand.mcpServerName` is the standing server's key on the
+     * official branch (§7's aliases resolve to `mcp__<mcpServerName>__<tool>`), so a capability server
+     * that claimed it would shadow the messaging tools on one branch and not the other. That is a typed
+     * refusal at construction, not a silent overwrite.
+     *
+     * WITHOUT `toInputShape` THIS IS A WINTER-LEG-ONLY DOOR: the official leg refuses rather than open a
+     * session whose capability tools exist on one branch only.
+     *
+     * A CALLER'S OWN `Options.mcpServers` REACHES THE WINTER LEG ONLY, and always has: the official leg
+     * builds its servers from this constructor and `runtime.official.mcpServers`, and never reads the
+     * pinned `Options` field at all. A caller key that collides with a capability name is therefore
+     * refused for BOTH legs at the door (interim review I-6) rather than refused on one and silently
+     * dropped on the other.
+     */
+    capabilities?: readonly McpSdkServerConfigWithInstance[];
+    /**
+     * The host's JSON-Schema → validator-shape bridge, for the official branch's in-process servers.
+     *
+     * INJECTED BECAUSE THE ROUTER DEPENDS ON NO VALIDATOR (see `official/mcp-descriptors.ts`'s header):
+     * the official runtime's own server constructor takes schemas in its peer validator's shape, and a
+     * package whose entire design is "two injected peers and nothing else" will not grow a third
+     * dependency to produce them. A host that has the official SDK already has that validator, and
+     * writes this in one line.
+     */
+    toInputShape?: InputShapeFactory;
+    /**
+     * The REVIEWER behind the standing advisor (R-8-1(3), ruling P-6; interim review I-5).
+     *
+     * The advisor tool itself is not optional and is not configured here: the official leg registers it
+     * on the standing server unconditionally, because the Winter runtime always advertises `advisor` and
+     * two legs whose advertised sets differ by a host option is the divergence WS-14 §11 exists to
+     * prevent. This supplies WHO REVIEWS — a resolver the host owns, because reviewer RESOLUTION is the
+     * runtime's provider-layer concern (D30) and the router has no provider layer. With no resolver the
+     * tool answers WS-06 §4's ordinary error.
+     *
+     * The transcript is NOT a field here: the source is this session's own, built by the leg over the one
+     * shared store, keyed by the backend session id the runtime reports at `system/init`.
+     */
+    advisor?: {
+        resolveReviewer: ReviewerResolver;
+        maxChars?: number;
+    };
     /**
      * The handoff barrier's collaborators (whole-branch review, F-3).
      *
@@ -197,14 +269,27 @@ export declare function runtimeSdkInternals(sdk: RuntimeSdk): RuntimeSdkInternal
 /**
  * Builds the object forwarded to a peer's `query()`.
  *
+ * THE INVARIANT, IN ONE SENTENCE: **the forwarded options are the caller's options minus
+ * `ROUTER_ONLY_OPTION_KEYS`, plus the brand's capability-server entries under `mcpServers`, and
+ * nothing else is rewritten.**
+ *
  * THE COMMON CASE FORWARDS THE CALLER'S OWN OBJECT, by reference. "Passes through verbatim" is a
  * property a test can only really check by identity, and a router that copied unconditionally would
  * be quietly deciding which of `Options`' members it knows about — the exact drift D19b's "never a
- * translation layer" rules out. A copy is made ONLY when a router-owned key is present, because that
- * key must not reach an SDK that would not recognise it; every other member keeps its own value
- * identity through the copy.
+ * translation layer" rules out. A copy is made ONLY when there is something to remove or something to
+ * add, because that is the only time the caller's own object would be the wrong thing to hand over;
+ * every other member keeps its own value identity through the copy.
+ *
+ * SO R-8 DID NOT WEAKEN THE PROPERTY, IT RESTATED IT. A host that configures no capabilities is
+ * unaffected — the identity return below still fires, and the test that pins it is unchanged. A host
+ * that configures them gets a copy whose every member except `mcpServers` is `Object.is`-identical to
+ * its own, and whose `mcpServers` is its own entries plus the capability entries, by reference.
+ *
+ * A CAPABILITY KEY THE CALLER ALSO USES IS A TYPED REFUSAL, never a silent overwrite in either
+ * direction: one of the two servers would simply not be there, and the party who would find out is
+ * the model, at the one moment the tool matters.
  */
-export declare function forwardableOptions(options: RouterOptions, brand?: Partial<BrandProfile>): Options;
+export declare function forwardableOptions(options: RouterOptions, brand?: Partial<BrandProfile>, capabilityServers?: Readonly<Record<string, unknown>>): Options;
 /**
  * Constructs the router. Throws `RuntimeSdkVersionError` on a version-matrix miss (D19a).
  *

package/dist/testing/capture-env.d.ts

@@ -0,0 +1,41 @@
+/**
+ * THE FOUR TRAFFIC OPT-OUTS THAT MAKE A CHILD RUNTIME ACTUALLY HERMETIC (whole-branch review, F-1).
+ *
+ * HERMETICITY IS A PROPERTY OF THE CHILD ENVIRONMENT, NOT OF THE FAKE. The loopback fake captures the
+ * MODEL endpoint and nothing else; the pinned artifact also fetches REMOTE FEATURE CONFIGURATION
+ * (`cdn.growthbook.io`), telemetry, error reports and update checks, none of which pass through
+ * `ANTHROPIC_BASE_URL`. Measured on this pin, same binary, same options, same fake: with these four
+ * unset the request carries 25 tools; with them set, 21 — `DesignSync`, `Monitor`,
+ * `PushNotification` and `advisor_20260301:advisor` appear ONLY when the remote flag fetch succeeds.
+ *
+ * SO A TEST WITHOUT THESE IS NOT MEASURING THE PIN. It is measuring the pin plus whatever a CDN said
+ * this minute, which is (a) a different answer on a different day, (b) a suite that goes red when the
+ * fetch times out — the "flake seen twice in ~20 runs" — and (c) a `docs/probes/` record whose "no
+ * network" line is false.
+ *
+ * THE SAME OBJECT THE PRODUCTION ENV BUILDER SETS (R-7b-11). It used to be a test-only copy handed to
+ * `configuredExtras`, and a copy is exactly how a test bed and a shipped session end up measuring two
+ * different artifacts: this re-export is what makes "the beds run what a host runs" checkable by
+ * identity rather than by reading two lists.
+ */
+export { TRAFFIC_OPT_OUT_VARIABLES as HERMETIC_TRAFFIC_OPT_OUTS } from "../official/env-allowlist.js";
+/**
+ * The minimal environment that points an official-SDK session at a loopback fake (R-7b-6).
+ *
+ * A REPLACEMENT, never a spread of `process.env` — WS-14 §3's own rule for the child environment, and
+ * the same reason the SDK repository's capture harness sets `HOME`: a throwaway is required because
+ * `os.homedir()` falls back to the OS user database and would otherwise reach the real `~/.claude`
+ * regardless of `CLAUDE_CONFIG_DIR`.
+ *
+ * PLUS THE FOUR OPT-OUTS ABOVE, unconditionally, because "hermetic" has to mean the whole child and
+ * not just its model endpoint (F-1). `allowRemoteConfig` is the ONE deliberate escape hatch: the D29
+ * probe's non-hermetic leg uses it to observe what remote configuration adds, and it is spelled at
+ * the call site so a reader can see which legs are which.
+ */
+export declare function officialCaptureEnv(input: {
+    baseUrl: string;
+    apiKey?: string;
+    claudeConfigDir: string;
+    home: string;
+    allowRemoteConfig?: boolean;
+}): Record<string, string>;

package/dist/testing/hermetic.d.ts

@@ -0,0 +1,33 @@
+import type { CredentialRef } from "@yanlinglabs/winter-agent-sdk";
+import type { KeychainSeam } from "../seams/keychain.js";
+export interface FakeKeychain extends KeychainSeam {
+    /** Stores material for a ref, keyed the same way `read` looks it up. */
+    set(ref: CredentialRef, material: string): void;
+    /** Every `read` this double served, in order — so a test can prove the fetch happened at spawn. */
+    readonly reads: CredentialRef[];
+}
+/**
+ * An in-memory `KeychainSeam`. NEVER `Bun.secrets`, never the OS keychain.
+ *
+ * An unset ref reads `undefined`, which is the seam's own documented "the host has none" answer —
+ * so the missing-credential path is testable without arranging for a real keychain to be empty.
+ */
+export declare function createFakeKeychain(initial?: Array<{
+    ref: CredentialRef;
+    material: string;
+}>): FakeKeychain;
+/**
+ * A fresh temp directory that is removed whatever the body does.
+ *
+ * `mkdtemp` under the OS temp root, never a path built from a home directory: the point is a
+ * directory this process created and this process owns.
+ */
+export declare function withTempDir<T>(prefix: string, fn: (dir: string) => Promise<T>): Promise<T>;
+/**
+ * The home directories a hermetic official-branch test needs: a throwaway `HOME` and a throwaway
+ * `CLAUDE_CONFIG_DIR`, both under one temp root that is removed in a `finally`.
+ */
+export declare function withHermeticHomes<T>(fn: (homes: {
+    home: string;
+    claudeConfigDir: string;
+}) => Promise<T>): Promise<T>;

package/dist/testing/host.d.ts

@@ -0,0 +1,5 @@
+export { createFakeKeychain, withHermeticHomes, withTempDir } from "./hermetic.js";
+export type { FakeKeychain } from "./hermetic.js";
+export { createFakeClaudePeer, createFakeWinterPeer } from "./peers.js";
+export type { FakeClaudePeerOptions, FakeWinterPeer, FakeWinterPeerOptions, RecordedQueryCall } from "./peers.js";
+export { HERMETIC_TRAFFIC_OPT_OUTS, officialCaptureEnv } from "./capture-env.js";

package/dist/testing/host.js

@@ -0,0 +1,139 @@
+import {
+  TRAFFIC_OPT_OUT_VARIABLES
+} from "../index-mfd2rg7x.js";
+
+// src/testing/hermetic.ts
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+function keyOf(ref) {
+  switch (ref.kind) {
+    case "keychain":
+      return `keychain:${ref.service ?? ""}:${ref.account}`;
+    case "env":
+      return `env:${ref.name}`;
+    case "file":
+      return `file:${ref.path}:${ref.format}:${ref.profile ?? ""}`;
+    case "inline":
+      return `inline:${ref.value}`;
+    default:
+      return ref.kind;
+  }
+}
+function createFakeKeychain(initial = []) {
+  const store = new Map;
+  const reads = [];
+  for (const entry of initial)
+    store.set(keyOf(entry.ref), entry.material);
+  return {
+    reads,
+    set(ref, material) {
+      store.set(keyOf(ref), material);
+    },
+    async read(ref) {
+      reads.push(ref);
+      return store.get(keyOf(ref));
+    }
+  };
+}
+async function withTempDir(prefix, fn) {
+  const dir = mkdtempSync(join(tmpdir(), `winter-runtime-sdk-${prefix}-`));
+  try {
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+async function withHermeticHomes(fn) {
+  return withTempDir("homes", async (root) => {
+    const home = mkdtempSync(join(root, "home-"));
+    const claudeConfigDir = mkdtempSync(join(root, "claude-config-"));
+    return fn({ home, claudeConfigDir });
+  });
+}
+// src/testing/peers.ts
+import { InvalidBrandError, resolveBrand, transcriptProjectKey } from "@yanlinglabs/winter-agent-sdk";
+var defaultMessage = () => ({
+  type: "result",
+  subtype: "success",
+  is_error: false,
+  result: "ok"
+});
+function scriptedQuery(messages) {
+  const unsupported = (name) => async () => {
+    throw new Error(`fake winter peer: Query.${name}() is not scripted`);
+  };
+  const generator = async function* () {
+    for (const message of messages)
+      yield message;
+  }();
+  const query = {
+    next: (...args) => generator.next(...args),
+    return: (value) => generator.return(value),
+    throw: (error) => generator.throw(error),
+    [Symbol.asyncIterator]() {
+      return query;
+    },
+    async[Symbol.asyncDispose]() {
+      await generator.return(undefined);
+    },
+    interrupt: unsupported("interrupt"),
+    setModel: unsupported("setModel"),
+    supportedModels: unsupported("supportedModels"),
+    listModelFamilies: unsupported("listModelFamilies"),
+    accountInfo: unsupported("accountInfo"),
+    rewindFiles: unsupported("rewindFiles"),
+    setPermissionMode: unsupported("setPermissionMode"),
+    messaging: {
+      listReachable: unsupported("messaging.listReachable"),
+      deliver: unsupported("messaging.deliver"),
+      steerChild: unsupported("messaging.steerChild"),
+      resumeChild: unsupported("messaging.resumeChild"),
+      subscribeIdle: unsupported("messaging.subscribeIdle"),
+      senderClass: unsupported("messaging.senderClass"),
+      readNotifications: unsupported("messaging.readNotifications"),
+      onIdleNotice: () => {
+        throw new Error("fake winter peer: Query.messaging.onIdleNotice() is not scripted");
+      }
+    }
+  };
+  return query;
+}
+function createFakeWinterPeer(options = {}) {
+  const calls = [];
+  const scripted = options.messages ?? [defaultMessage()];
+  const namespace = {
+    SDK_VERSION: options.packageVersion ?? "0.0.3",
+    PROTOCOL_VERSION: options.protocolVersion ?? "1.0",
+    resolveBrand,
+    InvalidBrandError,
+    transcriptProjectKey,
+    query: (args) => {
+      calls.push({ prompt: args.prompt, options: args.options });
+      return options.query === undefined ? scriptedQuery(scripted) : options.query(args);
+    }
+  };
+  return { peer: namespace, calls, scripted };
+}
+function createFakeClaudePeer(options = {}) {
+  return { version: options.packageVersion ?? "0.3.250" };
+}
+// src/testing/capture-env.ts
+function officialCaptureEnv(input) {
+  return {
+    ANTHROPIC_BASE_URL: input.baseUrl,
+    ANTHROPIC_API_KEY: input.apiKey ?? "sk-ant-fake-hermetic-key",
+    CLAUDE_CONFIG_DIR: input.claudeConfigDir,
+    HOME: input.home,
+    ...input.allowRemoteConfig === true ? {} : TRAFFIC_OPT_OUT_VARIABLES
+  };
+}
+export {
+  withTempDir,
+  withHermeticHomes,
+  officialCaptureEnv,
+  createFakeWinterPeer,
+  createFakeKeychain,
+  createFakeClaudePeer,
+  TRAFFIC_OPT_OUT_VARIABLES as HERMETIC_TRAFFIC_OPT_OUTS
+};

package/dist/testing/peers.d.ts

@@ -0,0 +1,45 @@
+import type { Options, Query, SdkMessage } from "@yanlinglabs/winter-agent-sdk";
+import type { RuntimeSdkPeers } from "../sdk.js";
+export interface RecordedQueryCall {
+    prompt: string | AsyncIterable<string>;
+    options: Options;
+}
+export interface FakeWinterPeer {
+    /** Pass this as `peers.winter`. */
+    peer: RuntimeSdkPeers["winter"];
+    /** Every `query()` the router made, in order, with the values it forwarded. */
+    calls: RecordedQueryCall[];
+    /** The exact message objects the fake yields — for identity assertions on the stream. */
+    scripted: SdkMessage[];
+}
+export interface FakeWinterPeerOptions {
+    /**
+     * The package version the fake reports as its own identity (probe step 1, `peer-export`).
+     * Defaults to a version INSIDE the matrix so a test that does not care about versions constructs
+     * cleanly; pass an out-of-range value to exercise the refusal.
+     */
+    packageVersion?: string;
+    /** Defaults to the one protocol version this router is tested against. */
+    protocolVersion?: string;
+    /** What the returned `Query` yields, in order. Defaults to one result-shaped message. */
+    messages?: SdkMessage[];
+    /** Called instead of the default generator, when a test needs the Query itself to misbehave. */
+    query?: (args: {
+        prompt: string | AsyncIterable<string>;
+        options: Options;
+    }) => Query;
+}
+/** A Winter peer that records what the router forwarded. See this module's header for the cast. */
+export declare function createFakeWinterPeer(options?: FakeWinterPeerOptions): FakeWinterPeer;
+export interface FakeClaudePeerOptions {
+    /** Defaults to the exact pin in the matrix. */
+    packageVersion?: string;
+}
+/**
+ * An official peer, for matrix tests only.
+ *
+ * It exports a version identity ON PURPOSE: without one, the matrix's second probe would resolve the
+ * REAL `@anthropic-ai/claude-agent-sdk@0.3.250` that this repository installs as a dev dependency,
+ * and an "out of range" test would pass for the wrong reason.
+ */
+export declare function createFakeClaudePeer(options?: FakeClaudePeerOptions): NonNullable<RuntimeSdkPeers["claude"]>;