@yanlinglabs/winter-runtime-sdk 0.0.1 → 0.0.3

package/README.md

@@ -14,19 +14,42 @@ Decision record: WS-00 D19 (2026-09-05). Boundaries that do not move:
   builtin-path containment, Winter MCP plugin registration), shared session-store wiring, the
   cross-runtime handoff barrier with the materialized-resume decoration doors, and the runtime
   directory plus cross-runtime messaging router.
+- **It owns NO TOOL** (the user's tool-ownership ruling, R-8-1). The default tools — `SendMessage`,
+  `ListAgents`, `ReadNotifications`, `advisor` — are DECLARED once in
+  `@yanlinglabs/winter-agent-sdk/tools` and BOUND here, under the official runtime's own built-in
+  names; the capability tools (computer, browser, office) are the HOST's, handed over as MCP servers
+  and forwarded to both legs unchanged. This package re-exports no tool surface of its own.
 - The host vendors all three packages directly (`winter-runtime-sdk`, `winter-agent-sdk`,
   `claude-agent-sdk`); this package declares the two SDKs as peer dependencies and receives their
   module instances by injection, so a host that never creates a Claude session never loads the
   official runtime and no SDK is ever instantiated twice.
 - A `brand` profile flows through unchanged (Winter defaults); Claude Code's own literals stay fixed.
 
-Status: Phase 7b, all four lanes landed and the door routed. The spine (the package scaffold, the
-contract re-export, the `createRuntimeSdk` constructor with its version matrix, the seams, the test
-harness and CI) and the four lanes behind those seams — the official-SDK adapter, the runtime
-directory and messaging router, the store wiring and handoff barrier, and runtime selection — are on
-`main`, with WS-17's eighteen router-owned rows proven and cited in `docs/conformance-rows.md`. See
-`docs/architecture.md` for the ownership map, the pinned interfaces and how this package consumes the
-Winter SDK before its first publish.
+Status: Phase 7b landed all four lanes and routed the door; `0.0.2` was the Phase-8b prerequisite
+release. The spine (the package scaffold, the contract re-export, the `createRuntimeSdk` constructor
+with its version matrix, the seams, the test harness and CI) and the four lanes behind those seams —
+the official-SDK adapter, the runtime directory and messaging router, the store wiring and handoff
+barrier, and runtime selection — are on `main`, with WS-17's eighteen router-owned rows proven and
+cited in `docs/conformance-rows.md`. See `docs/architecture.md` for the ownership map, the pinned
+interfaces and how this package consumes the Winter SDK.
+
+**What `0.0.3` changes** (P8c-13 — the official-leg HOST SURFACE, so a host can bridge its own
+approval broker and materialize MCP servers; no peer floor change):
+
+| | |
+|---|---|
+| root exports | `createApprovalBridge`/`isOurApprovalBridge` (+ `ApprovalBroker`/`ApprovalRequest`/`ApprovalBridgeOptions`/`DecisionSource`/`OfficialPermissionMode`/`OfficialApprovalBridge`), `materializeOfficialMcpServer`/`officialMcpServers`/`winterMcpServerDescriptor`/`canonicalToolNames`/`OFFICIAL_MATERIALIZATION_DROPS` (+ their descriptor/schema types), `minimalOsEnvironmentFrom`/`buildOfficialChildEnv` (+ env-policy types), the containment/auth/options-template types, `containmentDispositions`/`officialDisallowedTools`, `officialBranchLabel`/`OFFICIAL_DISCLOSURES`, and `renderAttributedTurn` — all previously reachable only through `./official/index.ts`, a test-only import site. `buildOfficialOptions` uses `policy.canUseTool` verbatim and `assertOptionsInvariants` refuses anything not built by `createApprovalBridge`, so without this a host's every official-leg tool call was denied by the fail-closed default. The spawn-proxy/adapter internals (`createSupervisedSpawnProxy`, `createOfficialAdapter`, …) stay OUT — their declaration graph pulls Node-only types into a consumer that never asked for them; the door reaches the adapter through the seam, not through a root import. |
+| `./testing` subpath | `createFakeKeychain`, `withHermeticHomes`, `withTempDir`, `createFakeClaudePeer`, `createFakeWinterPeer`, `HERMETIC_TRAFFIC_OPT_OUTS`, `officialCaptureEnv` — a NARROW barrel (`src/testing/host.ts`) that resolves neither `@yanlinglabs/winter-conformance` nor `@yanlinglabs/winter-provider-conformance`, so a host writing its own approval-bridge/MCP fixtures does not have to install either. The loopback fakes (`anthropicFake`, `openaiResponsesFake`, `requestsTo`, `withLoopbackFake`) and the golden-trace tooling stay on the internal, unpublished `./index.ts` barrel this repository's own tests use by relative path — a dynamic `import()` fixes their RUNTIME load without the peer, but not their TYPES, which still name it. |
+| root exports (types only) | `HandoffParticipants`, `HandoffSourceOwner`, `HandoffDestinationRuntime`, `HandoffResumeTarget`, `HandoffStepReport`, `HandoffOwnerHealth`, `HandoffEligibilityLike`, `DetailedHandoffOutcome`, `HandoffBarrierDeps`, `HandoffSelection`, and `MaterializedResumeDecoratorHandle` (`HandoffBarrierDeps.decorator`'s type) — the data shapes a host actually renders a handoff plan/outcome from, not just `HandoffBarrier`/`HandoffOutcome`/`HandoffPlan` (already reachable via the seams). Pure interfaces: none pulls a `node:*` specifier into the declaration graph. |
+
+**What `0.0.2` changed** (peer floor: `@yanlinglabs/winter-agent-sdk >=0.0.3 <0.1.0`):
+
+| | |
+|---|---|
+| `peerVersions` | A host DECLARES its peers' versions — the only door inside a compiled binary, where `require.resolve` cannot see out of the bundle to read a manifest. |
+| `capabilities` + `toInputShape` | The host's own MCP servers, forwarded to BOTH legs: by reference into the Winter leg's `Options.mcpServers`, and registered into the official runtime from the same declaration. One declaration, two registrations, identical canonical names. |
+| `advisor` | The standing server carries Winter's four default tools, `advisor` among them, bound under the official runtime's built-in names (measured: the pin honours an alias key that is not one of its own built-ins — `docs/probes/advisor-alias.md`). `advisor` supplies the REVIEWER; the tool is always registered. |
+| no tool ownership | `src/native-args.ts` and the router's messaging handlers are gone: the definitions, schemas, acceptors, handler factories and the advisor all come from `@yanlinglabs/winter-agent-sdk/tools`, and this package re-exports none of them. |
 
 ---
 
@@ -36,8 +59,22 @@ Winter SDK before its first publish.
 runtime's handle untouched.
 
 ```ts
+// The host owns the capability tools and hands them over as MCP SERVERS; the router forwards the same
+// servers to BOTH legs and rewrites nothing else (R-8-1). `toInputShape` is the one line of glue the
+// official branch needs — its in-process server constructor takes schemas in its own validator's shape,
+// and this package deliberately depends on no validator.
+const sdk = createRuntimeSdk({
+  peers,
+  keychain,
+  vendoredOfficialRuntime,
+  capabilities: [computerServer, browserServer, officeServer],   // your own `{ type: "sdk", name, tools, instance }`
+  toInputShape: (schema) => jsonSchemaToZodRawShape(schema),     // one line, over the validator you already have
+});
+
 // The Winter leg: exactly what it always was. No runtime input, so nothing is decided and nothing
-// is stripped — the caller's own `options` object is forwarded by reference.
+// is stripped — the caller's own `options` object is forwarded by reference (with no `capabilities`
+// configured, by IDENTITY; with them, a copy whose every other member is still your own object, plus
+// your servers under `mcpServers`).
 for await (const message of sdk.query({ prompt: "hello" })) { /* SdkMessage */ }
 
 // The official leg: a `claude-agent` selection, plus what only a host can answer.
@@ -51,7 +88,13 @@ const query = sdk.query({
       official: {
         sessionId: "s-42",                        // its directory row is `session:s-42`
         base: minimalOsEnvironmentFrom(process.env),
-        mcpServers: officialMcpServers({ /* … */ }),
+        // OPTIONAL SINCE 0.0.2: the router materializes the standing server and your capability
+        // servers itself. This stays as the escape hatch, and its reach is exactly one key: an entry
+        // under the BRAND's own standing-server name replaces the router's (that key reaches no other
+        // leg, so overriding it diverges from nothing); an entry naming a forwarded CAPABILITY is a
+        // typed refusal on BOTH legs, because that name is on both and a silent override would leave
+        // the two branches running different tools under one canonical name.
+        // mcpServers: officialMcpServers({ /* … */ }),
       },
     },
   },
@@ -134,12 +177,19 @@ at all.
 **The official branch disables the runtime's remote feature configuration by default** (R-7b-11).
 Every official child gets `TRAFFIC_OPT_OUT_VARIABLES` — the four names are exported, so read them
 rather than trusting this sentence. Measured on the pin, same binary and same options: 25 advertised
-tools with the fetch, 21 without; `DesignSync`, `Monitor`, `PushNotification` and
-`advisor_20260301:advisor` appear only when a CDN answers. A tool surface that moves with no version
-moving is not a pinned artifact, so this is on unless you say otherwise: `remoteConfig: "allow"` (per
-query on `runtime.official`, or deployment-wide on `createRuntimeSdk({ official: { env: { … } } })`)
-opts back in, and the choice is recorded on the session's directory row as
-`RuntimeDirectoryEntry.remoteConfig`.
+tools with the fetch, 21 without; `DesignSync`, `Monitor`, `PushNotification` and Anthropic's own
+API-side `advisor_20260301:advisor` appear only when a CDN answers — that one is the vendor's server
+tool, orthogonal to what follows. A tool surface that moves with no version moving is not a pinned
+artifact, so this is on unless you say otherwise: `remoteConfig: "allow"` (per query on
+`runtime.official`, or deployment-wide on `createRuntimeSdk({ official: { env: { … } } })`) opts back
+in, and the choice is recorded on the session's directory row as `RuntimeDirectoryEntry.remoteConfig`.
+
+**Winter's own `advisor` is registered on the official branch too (R-8-1), backing Anthropic's rather
+than being refused.** WS-14 §11's standing MCP server used to throw if a capability list named
+`advisor` — each branch was meant to have its own, unrelated advisor. The user's tool-ownership ruling
+reverses that: `mcp__<brand>__advisor` is reachable on the official branch exactly like
+`send_message`/`list_agents`, independent of whether the CDN-gated API-side one above is present that
+session. `docs/probes/d29-advisor.md` §6 has the full reversal and what it does and does not change.
 
 **The materialized-resume PREFERRED door is open for the pinned runtime, by measurement** (R-7b-12).
 WS-17 §8's four probes pass against 0.3.250 on darwin-arm64 and linux-x64, so a handle over that peer
@@ -242,6 +292,18 @@ was handed, the `claude-resume-<uuid>` staging root SURVIVES — the destination
 deleting a live child's `CLAUDE_CONFIG_DIR` is worse than leaving a directory behind. It is locatable
 at `outcome.target.stagingRoot` and belongs to your retention pass.
 
+**Compiled hosts must declare their peers' versions.** The version matrix's second probe
+(`resolved-manifest`) resolves a peer's `package.json` by walking up from `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
+has nothing left for the matrix to read, and construction refuses. `createRuntimeSdk({ peerVersions:
+{ winterAgentSdk, claudeAgentSdk } })` is the door: supply both from your own vendored
+`VERSIONS.json`, stamped at your own build time (WS-02 §7.1). A declared version is checked FIRST —
+it wins even over a peer that exports its own identity — and still has to satisfy the same
+range/exact-pin checks as either probe; it changes how the identity was discovered, not what counts
+as supported. A host that runs uncompiled (plain `bun`/`node`, source or an ordinary install) never
+needs this field.
+
 **"Exactly one runtime owns a session" is a convention here, not a mechanism.** The barrier moves
 ownership only after the destination confirms, and the transcript's producer record is authoritative —
 but the store's writer lease is re-entrant per pid and this router hosts both branches in one process,

package/dist/door.d.ts

@@ -1,10 +1,12 @@
 import type { BrandProfile, CredentialRef, Options, ProviderSelection, Query } from "@yanlinglabs/winter-agent-sdk";
 import type { GlobalMessagingHandle } from "./messaging/router.js";
+import { type ReviewerResolver } from "@yanlinglabs/winter-agent-sdk/tools";
 import type { ContainmentPolicy } from "./official/containment.js";
 import { type OfficialPermissionMode } from "./official/callbacks.js";
 import { type OfficialEnvPolicy } from "./official/env-allowlist.js";
 import { type AuthCredentialPlan } from "./official/auth.js";
 import { type OptionsTemplatePolicy } from "./official/options-template.js";
+import { type InputShapeFactory, type OfficialMcpModule, type WinterMcpServerDescriptor } from "./official/mcp-descriptors.js";
 import type { RuntimeDirectory } from "./seams/directory.js";
 import type { OfficialAdapter, RemoteConfigPolicy } from "./seams/official-adapter.js";
 import type { OfficialQuery, OfficialUserMessage } from "./seams/official-sdk-shapes.js";
@@ -81,7 +83,24 @@ export interface RouterOfficialInput {
     projectKey?: string;
     /** §3's `CLAUDE_CODE_TMPDIR` — the shared per-user temp root the host derives from the brand. */
     sharedTempRoot?: string;
-    /** §11's servers, already materialized by the host (`officialMcpServers`). */
+    /**
+     * §11's servers, already materialized by the host (`officialMcpServers`) — THE ESCAPE HATCH, AND
+     * EXACTLY HOW FAR IT REACHES (review r1).
+     *
+     * Since R-8 the router materializes the standing server and the constructor's capability servers
+     * itself (`RuntimeSdkOptions.capabilities` + `toInputShape`), so most hosts never fill this in.
+     *
+     *   * THE STANDING-SERVER KEY (`brand.mcpServerName`): THE HOST WINS. A host that built its own
+     *     standing server means that server, and the router replacing it would be the translation layer
+     *     this package is not — the same precedence `remoteConfig` (`:148-149`) and `options` (`:153`)
+     *     have. It is also a key the OTHER leg never receives from the router, so one branch overriding
+     *     it diverges from nothing.
+     *   * A FORWARDED CAPABILITY'S NAME: REFUSED, with the same `RuntimeLaunchInputError` the Winter leg
+     *     raises for the identical collision, before any runtime is launched. `capabilities` are
+     *     forwarded to BOTH legs, so a per-key override here would leave this branch running the host's
+     *     server and the Winter branch running the daemon's under one name — two different tools, one
+     *     canonical name, no error anywhere.
+     */
     mcpServers?: Readonly<Record<string, unknown>>;
     /** §1 profile 2's staging root. Defaults to the vendor's own `<tmpdir>/claude-resume-<resume id>`. */
     stagingRoot?: string;
@@ -160,6 +179,48 @@ export interface OfficialLegDeps {
     transcriptProjectKey: (cwd: string) => string;
     /** WS-14 §5.1's vendored runtime, from the constructor. A per-query `Options` value wins over it. */
     vendoredOfficialRuntime?: string;
+    /**
+     * The daemon's capability servers, as DESCRIPTORS (R-8 / R-8-1).
+     *
+     * DESCRIPTORS RATHER THAN THE WINTER INSTANCES, because this branch does not consume a server — it
+     * REGISTERS one, through its own runtime's in-process constructor. `createRuntimeSdk` reads the
+     * host's declaration once (`capabilityServerDescriptors`) and the leg materializes it per session,
+     * beside the standing server it builds from `messaging`.
+     *
+     * PER SERVER, UNDER ITS OWN NAME, so `mcp__<server>__<tool>` is the same canonical name on both legs
+     * — which is the whole of WS-14 §11's "registered identically into BOTH branches".
+     */
+    capabilities?: readonly WinterMcpServerDescriptor[];
+    /**
+     * The host's JSON-Schema → validator-shape bridge (`RuntimeSdkOptions.toInputShape`).
+     *
+     * IT IS WHAT SWITCHES THE ROUTER-BUILT SERVERS ON. With it, this leg registers the standing server
+     * (the messaging tools) and every capability server itself, and a host stops hand-materializing.
+     * Without it and WITH capabilities configured, the leg REFUSES: a session whose capability tools
+     * exist on the Winter branch and silently not on this one is the divergence §11 exists to prevent.
+     */
+    toInputShape?: InputShapeFactory;
+    /**
+     * The injected official peer, duck-typed to §11's surface (`createSdkMcpServer`/`tool`).
+     *
+     * THE SAME OBJECT `peers.claude` ALREADY IS — the seam declares only `query`, because that is all
+     * the launch path needs, and this is the one other member of it this package uses. A module without
+     * the constructor is `OfficialMcpError`, thrown where the server would have been built.
+     */
+    mcpModule?: OfficialMcpModule;
+    /**
+     * What the host supplies for the STANDING ADVISOR — the reviewer, never the tool (interim review I-5).
+     *
+     * The advisor is registered on this branch whether or not a host fills this in, because the Winter
+     * runtime always advertises `advisor` and two legs whose advertised sets differ by a host option is
+     * exactly the divergence WS-14 §11 forbids. What this supplies is the REVIEWER: absent, the default
+     * resolver answers `undefined`, which is WS-06 §4's ordinary tool error ("no reviewer configured"),
+     * not a throw and not a missing tool.
+     */
+    advisor?: {
+        resolveReviewer?: ReviewerResolver;
+        maxChars?: number;
+    };
     /** The adapter's own policy, so a host's `env`/`containment` choices reach the door's own builders. */
     policy?: RouterOfficialPolicy;
     /**

package/dist/errors.d.ts

@@ -38,12 +38,20 @@ export declare class RuntimeHandoffRequiredError extends RuntimeSdkError {
  * cannot run. This one is about the DOOR's own inputs: the session id its directory row is addressed
  * by, the credential its auth family needs, the vendored runtime path §5.1 will not guess. A host
  * catching it knows to fix a call site, not a configuration.
+ *
+ * THE PREFIX IS LEG-NEUTRAL, AND IT HAD TO BECOME SO (interim review I-7). It read "the official leg
+ * needs `<field>`" for as long as the official leg was the only caller — and then R-8 gave the class
+ * three refusals that are not: `capabilities` at CONSTRUCTION (before any leg exists, and fatal to a
+ * Winter-only host), and `mcpServers` on the WINTER leg. A host with no official peer at all reading
+ * "the official leg needs `mcpServers`" is told to look at the one branch it does not use. `leg` names
+ * the branch when there IS one, so nothing is lost where the old sentence was right.
  */
 export declare class RuntimeLaunchInputError extends RuntimeSdkError {
     readonly field: string;
     constructor(args: {
         field: string;
         reason: string;
+        leg?: "official" | "winter";
     });
 }
 /**