@yanlinglabs/winter-runtime-sdk 0.0.2 → 0.0.3

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"]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanlinglabs/winter-runtime-sdk",
-  "version": "0.0.2",
+  "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,11 +43,19 @@
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.250",
-    "@yanlinglabs/winter-agent-sdk": ">=0.0.3 <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": {