@yanlinglabs/winter-runtime-sdk 0.0.1 → 0.0.3

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.3",
   "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.",
@@ -21,6 +21,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/host.d.ts",
+      "default": "./dist/testing/host.js"
     }
   },
   "files": [
@@ -39,20 +43,28 @@
   },
   "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",
+    "@yanlinglabs/winter-conformance": ">=0.0.3 <0.1.0",
+    "@yanlinglabs/winter-provider-conformance": ">=0.0.3 <0.1.0"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/claude-agent-sdk": {
       "optional": true
+    },
+    "@yanlinglabs/winter-conformance": {
+      "optional": true
+    },
+    "@yanlinglabs/winter-provider-conformance": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@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>;