@yanlinglabs/winter-runtime-sdk 0.0.1 → 0.0.2

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/version-matrix.d.ts

@@ -8,7 +8,7 @@ import type { RuntimeSdkPeers } from "./sdk.js";
  * not a range that quietly widens.
  */
 export declare const SUPPORTED: {
-    readonly winterAgentSdk: ">=0.0.2 <0.1.0";
+    readonly winterAgentSdk: ">=0.0.3 <0.1.0";
     readonly claudeAgentSdk: "0.3.250";
 };
 /**
@@ -18,7 +18,7 @@ export declare const SUPPORTED: {
  */
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["1.0"];
 /** Where a peer's package version came from. See this module's header. */
-export type PeerVersionSource = "peer-export" | "resolved-manifest";
+export type PeerVersionSource = "host-declared" | "peer-export" | "resolved-manifest";
 export interface PeerVersionIdentity {
     /** The package name the identity was read for. */
     packageName: string;
@@ -70,8 +70,23 @@ export declare function readExportedVersion(namespace: unknown): string | undefi
  * own manifest as a subpath. Every failure mode — no such package, a manifest that will not parse, a
  * manifest with no `version` — returns `undefined`, which the caller turns into the loud refusal.
  * Never throws: a missing OPTIONAL peer must not crash the matrix on its way to reporting itself.
+ *
+ * `resolveEntry` is an injectable seam (R2), defaulting to the real
+ * `createRequire(import.meta.url).resolve` — NOT deleted, still the only resolver this package ever
+ * uses on its own. It exists so a test can simulate the one condition this package cannot otherwise
+ * reproduce on demand: a compiled binary, where that resolve call cannot see outside the bundle
+ * (`file:///$bunfs/...`) and always throws. Production code never passes a second argument.
+ */
+export declare function readResolvedManifestVersion(packageName: string, resolveEntry?: (name: string) => string): string | undefined;
+/**
+ * The seams `resolveVersionMatrix` accepts. `resolveEntry`, when given, REPLACES probe 2's resolver
+ * end to end (through `identityFor` into `readResolvedManifestVersion`) — the only way a test can make
+ * that probe genuinely fail rather than merely be irrelevant because `declared` or peer-export already
+ * answered. Production code (`assertVersionMatrix`) never supplies one.
  */
-export declare function readResolvedManifestVersion(packageName: string): string | undefined;
+export interface VersionMatrixSeams {
+    resolveEntry?: (name: string) => string;
+}
 /**
  * Reads each injected peer's version identity and refuses loudly on a miss.
  *
@@ -79,6 +94,31 @@ export declare function readResolvedManifestVersion(packageName: string): string
  * Winter-only host injects `{ winter }` and never loads the official runtime (that is the whole
  * point of the optional peer), so "no claude peer" is a valid, fully-supported configuration and the
  * report simply omits the row.
+ *
+ * `declared` is `RuntimeSdkOptions.peerVersions` (R2), optional — the one-arg call
+ * (`assertVersionMatrix(peers)`) stays legal and behaves exactly as before: with nothing declared,
+ * every peer's identity comes from probe 1 or probe 2, unchanged.
+ *
+ * `seams` is test-only (R2 review r1): NOT exposed here — `resolveVersionMatrix` below is where a test
+ * reaches it. A public seam parameter on this function is a production call site that could pass a
+ * broken resolver by accident, for a capability real hosts never need.
+ */
+export declare function assertVersionMatrix(peers: RuntimeSdkPeers, declared?: {
+    winterAgentSdk?: string;
+    claudeAgentSdk?: string;
+}): VersionMatrixReport;
+/**
+ * `assertVersionMatrix`'s full implementation, with an injectable `seams` (R2 review r1, `test/spine/
+ * version-matrix.test.ts`'s test (d)). NOT on the package barrel (`src/index.ts`) — deliberately: a
+ * real host has no reason to override how this package resolves ITS OWN peers' manifests, so this
+ * function exists only so a test can force probe 2 (`resolved-manifest`) to GENUINELY fail — the one
+ * condition a test cannot otherwise reproduce on demand (in an ordinary dev checkout the real peers
+ * really are resolvable, so a test that never overrides the resolver cannot tell "declared won" from
+ * "resolved-manifest would have answered the same value anyway"). `assertVersionMatrix` is the public,
+ * one-line delegation with the real (default) seams.
  */
-export declare function assertVersionMatrix(peers: RuntimeSdkPeers): VersionMatrixReport;
+export declare function resolveVersionMatrix(peers: RuntimeSdkPeers, declared?: {
+    winterAgentSdk?: string;
+    claudeAgentSdk?: string;
+}, seams?: VersionMatrixSeams): VersionMatrixReport;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanlinglabs/winter-runtime-sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "license": "MIT",
   "type": "module",
   "description": "One door over the Winter Agent SDK and the official Claude Agent SDK: runtime selection, the official-SDK adapter, the shared session store, the handoff barrier and the cross-runtime messaging router.",
@@ -39,7 +39,7 @@
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.250",
-    "@yanlinglabs/winter-agent-sdk": ">=0.0.2 <0.1.0"
+    "@yanlinglabs/winter-agent-sdk": ">=0.0.3 <0.1.0"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/claude-agent-sdk": {
@@ -50,9 +50,9 @@
     "@anthropic-ai/claude-agent-sdk": "0.3.250",
     "@types/bun": "^1.3.0",
     "@types/node": "^26.4.0",
-    "@yanlinglabs/winter-agent-sdk": "^0.0.2",
-    "@yanlinglabs/winter-conformance": "^0.0.2",
-    "@yanlinglabs/winter-provider-conformance": "^0.0.2",
+    "@yanlinglabs/winter-agent-sdk": "^0.0.3",
+    "@yanlinglabs/winter-conformance": "^0.0.3",
+    "@yanlinglabs/winter-provider-conformance": "^0.0.3",
     "typescript": "^5.9.0"
   },
   "scripts": {

package/dist/messaging/handlers.d.ts

@@ -1,56 +0,0 @@
-import { type GlobalMessagingHandle } from "./router.js";
-/** The MCP result shape both branches return — structurally the descriptor's own (WS-14 §11). */
-export interface MessagingToolResult {
-    content: Array<{
-        type: "text";
-        text: string;
-    }>;
-    isError?: boolean;
-}
-export type MessagingToolHandler = (args: unknown, extra?: unknown) => Promise<MessagingToolResult>;
-/**
- * WS-10 §12's RETRY KEY, on the official branch — and it exists, which was not known until it was
- * measured (item 15; `test/official/runtime-aliases.test.ts` is the measurement).
- *
- * §12 wants a message id derived from (sender session, TOOL-CALL id) so "a retry allocates the SAME
- * id" and returns the stored outcome instead of starting a second turn. On the Winter branch the
- * caller binds `toolUseId` at registration. On the official branch the handler is inside the vendor's
- * in-process MCP server, where the only per-call channel is the second argument the vendor passes —
- * and the reasonable expectation was that it carries MCP request context (a JSON-RPC request id,
- * `_meta`) rather than an Anthropic-API `tool_use_id`, which is one layer up.
- *
- * THE PINNED RUNTIME BRIDGES THEM. Measured on 0.3.250: `extra._meta["claudecode/toolUseId"]` is the
- * exact id the model emitted. So the official branch gets a real §12 key rather than depending on the
- * rapid-repeat guard, and the vendor's own namespaced `_meta` name is read rather than guessed at.
- *
- * A VENDOR-NAMESPACED KEY IS NEVER REBRANDED (WS-01 §5): `claudecode/toolUseId` is the vendor's name
- * for the vendor's field, exactly like `CLAUDE_CONFIG_DIR`. It is read defensively — an absent or
- * non-string value simply falls back to the bound caller's id — because a future pin may move it, and
- * losing the key must degrade to today's behaviour rather than to a crash.
- */
-export declare const VENDOR_TOOL_USE_ID_META_KEY = "claudecode/toolUseId";
-export declare function toolUseIdFromExtra(extra: unknown): string | undefined;
-export interface MessagingToolHandlers {
-    sendMessage: MessagingToolHandler;
-    listAgents: MessagingToolHandler;
-}
-/**
- * WHO IS CALLING — bound at registration, never read out of the arguments.
- *
- * The standing MCP server is materialized per session (WS-14 §11), so the caller is known when the
- * handler is built. Taking it from the ARGUMENTS instead would make the sender's identity something a
- * model could write, and every fence in this package — the owning-parent rule, the self-target
- * refusal, WS-10 §13's sender class, WS-15 §6.2's dedupe key — is keyed on it.
- *
- * `toolUseId` is the second half of WS-10 §12's retry key. It is OPTIONAL because on the official
- * branch it is not available: the in-process MCP server hands a tool handler its arguments, and the
- * router's own materialization does not forward the vendor's `extra` (which is where a request id
- * would be). A caller that cannot supply one gets no dedupe — stated at the door rather than faked
- * with a stable-looking key that would make two different messages one.
- */
-export interface MessagingToolCaller {
-    sessionId: string;
-    agentId?: string;
-    toolUseId?: string;
-}
-export declare function createMessagingToolHandlers(messaging: GlobalMessagingHandle, caller: MessagingToolCaller | (() => MessagingToolCaller)): MessagingToolHandlers;

package/dist/native-args.d.ts

@@ -1,76 +0,0 @@
-/** WS-10 §10.1's bounds. `to`'s own limit is the subpath's; this is the copy the SCHEMA advertises. */
-export declare const SEND_MESSAGE_TO_MAX = 300;
-export declare const SEND_MESSAGE_SUMMARY_MAX = 200;
-/** WS-10 §10.2's bound on both reserved `ListAgents` fields. */
-export declare const LIST_AGENTS_FIELD_MAX = 256;
-export declare const NATIVE_SEND_MESSAGE_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly to: {
-            readonly type: "string";
-            readonly maxLength: 300;
-            readonly description: "no newline, no \"*\" broadcast";
-        };
-        readonly message: {
-            readonly type: "string";
-            readonly description: "required; defaults \"\" for pure idle subscription";
-        };
-        readonly summary: {
-            readonly type: "string";
-            readonly maxLength: 200;
-        };
-        readonly notify_when_idle: {
-            readonly type: "boolean";
-            readonly description: "one-shot; main conversation -> same-machine session only";
-        };
-    };
-    readonly required: readonly ["to", "message"];
-};
-export declare const NATIVE_LIST_AGENTS_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly channel: {
-            readonly type: "string";
-            readonly maxLength: 256;
-            readonly description: "reserved";
-        };
-        readonly q: {
-            readonly type: "string";
-            readonly maxLength: 256;
-            readonly description: "reserved";
-        };
-    };
-};
-/** WS-10 §10.2: "`ListAgents` output is EXACTLY `{ listing: string }`." */
-export declare const NATIVE_LIST_AGENTS_OUTPUT_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly listing: {
-            readonly type: "string";
-        };
-    };
-    readonly required: readonly ["listing"];
-};
-/** The native `SendMessage` arguments (WS-10 §10.1), after validation. */
-export interface NativeSendMessageArgs {
-    to: string;
-    message: string;
-    summary?: string;
-    notify_when_idle?: boolean;
-}
-/** The native `ListAgents` arguments (WS-10 §10.2). Both fields are reserved in the pinned build. */
-export interface NativeListAgentsArgs {
-    channel?: string;
-    q?: string;
-}
-export type NativeArgsResult<T> = {
-    ok: true;
-    args: T;
-} | {
-    ok: false;
-    reason: string;
-};
-/** Accepts the native `SendMessage` arguments EXACTLY — no more, no less. */
-export declare function acceptNativeSendMessageArgs(input: unknown): NativeArgsResult<NativeSendMessageArgs>;
-/** The same treatment for `ListAgents`: two reserved optional fields, both capped, nothing else. */
-export declare function acceptNativeListAgentsArgs(input: unknown): NativeArgsResult<NativeListAgentsArgs>;