@yanlinglabs/winter-runtime-sdk 0.0.2 → 0.0.4

package/README.md

@@ -25,7 +25,7 @@ Decision record: WS-00 D19 (2026-09-05). Boundaries that do not move:
   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 landed all four lanes and routed the door; `0.0.2` is the Phase-8b prerequisite
+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
@@ -33,7 +33,16 @@ barrier, and runtime selection — are on `main`, with WS-17's eighteen router-o
 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.2` changes** (peer floor: `@yanlinglabs/winter-agent-sdk >=0.0.3 <0.1.0`):
+**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`):
 
 | | |
 |---|---|

package/dist/door.d.ts

@@ -68,11 +68,13 @@ export interface RouterOfficialInput {
      */
     credentials?: readonly AuthCredentialPlan[];
     /**
-     * NON-SECRET family variables: a gateway's `ANTHROPIC_BASE_URL`, a region, a project.
+     * NON-SECRET family variables: a gateway's `ANTHROPIC_BASE_URL`, a region, a project, or (router
+     * 0.0.4, C1) a `console-profile` session's `ANTHROPIC_PROFILE` name and `ANTHROPIC_CONFIG_DIR` path.
      *
      * Separate from `credentials` because they are not secrets and must not travel through a keychain
      * read — and because §12's gateway caveat ("set the full credential pair or neither") is checked
-     * across both halves by the auth validator, whichever side each variable came from.
+     * across both halves by the auth validator, whichever side each variable came from. The same shape
+     * applies to `console-profile`'s pairing rule: set both names here or neither.
      */
     connectionEnv?: Readonly<Record<string, string>>;
     /** §3's minimal OS set. Build it with `minimalOsEnvironmentFrom(process.env)` at the host's call site. */
@@ -273,16 +275,31 @@ export declare function officialUserTurn(text: string, sessionId: string): Offic
  * DERIVED ONLY WHERE THE MAPPING IS UNAMBIGUOUS. `api-key` is one variable; `console-oauth` is a
  * bearer token whose endpoint is non-secret and travels in `connectionEnv` (§12's "gateway configs
  * MUST set the full credential pair" is then checked by the auth validator, across both halves). The
- * two families that inject nothing inject nothing. A cloud credential chain and a `custom` family name
- * their own variables, because their sets are the host's: a chain's variables depend on which of
- * Bedrock's or Vertex's several auth modes the deployment uses, and `custom` is open by definition.
+ * three families that inject nothing (`claude-oauth`, `local-none`, and router 0.0.4's
+ * `console-profile` — its `ANTHROPIC_PROFILE`/`ANTHROPIC_CONFIG_DIR` pair are non-secret and travel in
+ * `connectionEnv` exactly like `console-oauth`'s base URL, never through a keychain-backed plan)
+ * inject nothing. A cloud credential chain and a `custom` family name their own variables, because
+ * their sets are the host's: a chain's variables depend on which of Bedrock's or Vertex's several auth
+ * modes the deployment uses, and `custom` is open by definition.
  */
 export declare function officialCredentialPlan(args: {
     selection: RuntimeSelection;
     provider: ProviderSelection | undefined;
     explicit: readonly AuthCredentialPlan[] | undefined;
 }): readonly AuthCredentialPlan[];
-/** Non-secret connection variables a family sets, from the contract's own `ProviderConnectionConfig`. */
+/**
+ * Non-secret connection variables a family sets, from the contract's own `ProviderConnectionConfig`
+ * plus whatever the host names in `RouterOfficialInput.connectionEnv`.
+ *
+ * ROUTER 0.0.4, C1: `console-profile`'s `ANTHROPIC_PROFILE` and `ANTHROPIC_CONFIG_DIR` have no
+ * counterpart on `ProviderConnectionConfig` (that shape carries only `baseUrl`, a pinned contract type
+ * this package does not extend) and are non-secret by the same reasoning `ANTHROPIC_BASE_URL` is, so a
+ * host sets them the identical way — `connectionEnv: { ANTHROPIC_PROFILE, ANTHROPIC_CONFIG_DIR }` —
+ * and they ride through `explicit` here unchanged, exactly like any other family's non-secret pair.
+ * No family-specific derivation is needed for them the way `console-oauth`'s base URL gets one below,
+ * because the host already has both values in hand (a profile name, a directory it manages) and there
+ * is no `ProviderSelection` field to read them from instead.
+ */
 export declare function officialConnectionEnv(args: {
     selection: RuntimeSelection;
     provider: ProviderSelection | undefined;