@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/door.d.ts

@@ -0,0 +1,247 @@
+import type { BrandProfile, CredentialRef, Options, ProviderSelection, Query } from "@yanlinglabs/winter-agent-sdk";
+import type { GlobalMessagingHandle } from "./messaging/router.js";
+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 { RuntimeDirectory } from "./seams/directory.js";
+import type { OfficialAdapter, RemoteConfigPolicy } from "./seams/official-adapter.js";
+import type { OfficialQuery, OfficialUserMessage } from "./seams/official-sdk-shapes.js";
+import type { RuntimeKind, RuntimeSelection } from "./selection/runtime-selection.js";
+import type { SharedSessionStore } from "./store/wiring.js";
+/**
+ * What the door returns.
+ *
+ * A UNION, BECAUSE THE TWO LEGS RETURN THEIR OWN RUNTIME'S HANDLE AND NEITHER IS THE OTHER. The Winter
+ * `Query` carries `messaging` and `listModelFamilies`, which the pinned official `Query` does not have
+ * and this package will not fake; the official one carries a dozen members the router deliberately
+ * does not name (it never imports the vendor's types onto its published surface — see
+ * `seams/official-sdk-shapes.ts`). Collapsing them into one type would mean either a wrapper that
+ * translates — the one thing D19b says this package must not be — or a declared type that lies.
+ *
+ * A HOST PAYS NOTHING FOR THIS UNLESS IT ASKS FOR IT: `query()` is overloaded so that a call with no
+ * runtime input is typed `Query`, which is sound because the official leg is reachable ONLY through a
+ * runtime input. A host that passes one knows which runtime it selected and narrows accordingly.
+ */
+export type RouterQuery = Query | OfficialQuery;
+/** True for a handle THIS package opened on the official leg. Registry-based: nothing is sniffed. */
+export declare function isOfficialQuery(value: RouterQuery): value is OfficialQuery;
+/**
+ * The official leg's host-owned inputs, carried on `RouterOptions.runtime.official`.
+ *
+ * EVERY FIELD IS SOMETHING ONLY THE HOST KNOWS. The router will not guess a session id (the directory
+ * row's identity), invent an auto-memory directory (WS-14 §2's ONE shared directory is a host-wide
+ * decision), or resolve a vendored runtime path (§5.1: "never the user's installed binary" is only
+ * enforceable if the host names the copy it vendored).
+ */
+export interface RouterOfficialInput {
+    /**
+     * This session's Winter session id. Its directory address is `session:<id>`.
+     *
+     * REQUIRED, and it is the one field with no plausible default: §6 rule 2's durable record is written
+     * onto this address, the messaging registry attaches under it, and a listed object that no model can
+     * send to is worse than no listing at all (`UnaddressableEntryError`'s own note).
+     */
+    sessionId: string;
+    /**
+     * R-7b-1: this session is a CHILD of `parentSessionId`, on its own runtime.
+     *
+     * "A child runs on the runtime its OWN slot's family selects at spawn time, independent of the
+     * parent's runtime" — so a `claude`-family child of a Winter parent is not a native subagent inside
+     * another official process, it is an official session in its own right, addressed as
+     * `agent:<parent>:<sessionId>` with `transport: "claude-handle"`. That transport is the field WS-15
+     * §6.1 uses to tell the two apart, and Lane B's official adapter branches on it: a `claude-handle`
+     * child is delivered to DIRECTLY, a `claude-child` only through its owning parent.
+     *
+     * Absent = a top-level session, addressed `session:<sessionId>`.
+     */
+    parentSessionId?: string;
+    /**
+     * Secret variables for families whose mapping this module cannot derive — a cloud credential chain,
+     * or a `custom` family, whose set is open by design (WS-14 §12).
+     *
+     * Each entry is a NAME and a REF, never material: the read happens at spawn, through the host's own
+     * `KeychainSeam`, and nothing here holds the answer.
+     */
+    credentials?: readonly AuthCredentialPlan[];
+    /**
+     * NON-SECRET family variables: a gateway's `ANTHROPIC_BASE_URL`, a region, a project.
+     *
+     * 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.
+     */
+    connectionEnv?: Readonly<Record<string, string>>;
+    /** §3's minimal OS set. Build it with `minimalOsEnvironmentFrom(process.env)` at the host's call site. */
+    base?: Readonly<Record<string, string>>;
+    /** §2's ONE shared auto-memory directory, identical for both branches. */
+    autoMemoryDirectory?: string;
+    /** §3's `CLAUDE_CODE_PROJECT_DIR_NAME` — Winter's stable transcript key. Defaults to `sessionId`. */
+    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`). */
+    mcpServers?: Readonly<Record<string, unknown>>;
+    /** §1 profile 2's staging root. Defaults to the vendor's own `<tmpdir>/claude-resume-<resume id>`. */
+    stagingRoot?: string;
+    /** §1 profile 1's spool. Defaults to `<winter home>/runtimes/official-agent-spool`. */
+    spool?: string;
+    /**
+     * §5: `"eager"` mirroring for a session that advertises cross-runtime handoff. DEFAULT TRUE here,
+     * because a session the ROUTER created is one `sdk.handoff()` can be called on by construction.
+     */
+    advertisesHandoff?: boolean;
+    /** R-7b-11: `"allow"` lets this session's child fetch the runtime's remote feature configuration. */
+    remoteConfig?: RemoteConfigPolicy;
+    /** The display name this session answers to in `ListAgents`. */
+    displayName?: string;
+    /** Extra template policy the host has already checked against the runtime's own schema. */
+    options?: Omit<OptionsTemplatePolicy, "env" | "mcpServers" | "resume" | "forkSession" | "sessionId">;
+}
+/**
+ * The official branch's deployment-wide policy, as a host sets it on `createRuntimeSdk`.
+ *
+ * A SUBSET OF `OfficialAdapterPolicy`, DECLARED HERE RATHER THAN REFERENCED, and the reason is the
+ * published-declaration rule this package already lives by (`seams/official-sdk-shapes.ts`'s header):
+ * naming `OfficialAdapterPolicy` on an exported member pulls `official/adapter.d.ts` — and with it
+ * `spawn-proxy.d.ts`, whose child-process shape is written in Node's own types — into the declaration
+ * graph a CONSUMER type-checks, and a consumer without `@types/node` then fails to compile this
+ * package. The installed-tarball smoke is the gate that says so.
+ *
+ * WHAT IS LEFT OUT IS THE SUPERVISED-SPAWN INJECTION POINTS (`sink`, `reconcile`, `verifyCleanup`,
+ * `spawnChild`), and leaving them out is right on its own terms: the router DEFAULTS the record sink
+ * to the directory row addressed by the launch, which is the answer §6 rule 2 wants, and a host that
+ * genuinely needs to replace the spawn machinery builds its own adapter and reaches it through
+ * `runtimeSdkInternals`.
+ */
+export interface RouterOfficialPolicy {
+    /** §3's child-environment policy: declared extras, host prefixes, the two reviewed hatches, `remoteConfig`. */
+    env?: OfficialEnvPolicy;
+    /** §8's dispositions, threaded into the floor every launch installs. */
+    containment?: ContainmentPolicy;
+    /** The permission mode the bridge is built with when a query supplies no broker. */
+    permissionMode?: OfficialPermissionMode;
+    /** §2's template policy every official session in this deployment starts from. */
+    options?: OptionsTemplatePolicy;
+}
+/**
+ * The canonical address this leg's session is recorded under — `session:<id>`, or R-7b-1's
+ * `agent:<parent>:<id>` for a cross-runtime child.
+ *
+ * EXPORTED because the door is not the only party that needs it: `query()`'s in-process ledger is
+ * keyed by ADDRESS rather than by the bare session id (review r1, L-3), since a top-level Winter
+ * session `x` and a claude child `x` of some parent are different objects that would otherwise share
+ * one slot and refuse each other as `handoff-required`.
+ */
+export declare function officialLegAddress(input: Pick<RouterOfficialInput, "sessionId" | "parentSessionId">): string;
+/** The same key for a session named on either leg — the Winter leg has no parent to name. */
+export declare function sessionLedgerKey(sessionId: string): string;
+/** The collaborators the leg composes. Built once by `createRuntimeSdk`; not part of any public shape. */
+export interface OfficialLegDeps {
+    brand: BrandProfile;
+    official: OfficialAdapter;
+    directory: RuntimeDirectory;
+    messaging: GlobalMessagingHandle;
+    keychain: {
+        read(ref: CredentialRef): Promise<string | undefined>;
+    };
+    /** Lane C's ONE shared store, resolved on first use (the identity also carries the winter home). */
+    shared: () => SharedSessionStore;
+    /**
+     * R-7b-13: the Winter SDK's OWN transcript project key for a working directory.
+     *
+     * INJECTED FROM THE PEER, NEVER RE-DERIVED. WS-14 §3 calls `CLAUDE_CODE_PROJECT_DIR_NAME` "Winter's
+     * stable transcript key" and §2 wants ONE shared auto-memory directory "identical for both
+     * branches" — which is only true if the official leg writes under the key the WINTER leg writes
+     * under. The SDK exports `transcriptProjectKey(cwd)`; re-implementing its sanitizer here would give
+     * two branches two keys for one cwd the first time either changed.
+     */
+    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 adapter's own policy, so a host's `env`/`containment` choices reach the door's own builders. */
+    policy?: RouterOfficialPolicy;
+    /**
+     * "A leg opened on this runtime" — the door's in-process ledger, told only when it is true
+     * (review r1, I-1).
+     *
+     * CALLED AFTER THE LAUNCH RETURNS, never before. `query()` used to write the ledger the moment it
+     * DECIDED, which poisoned it on every path that then refused: a claude-agent selection with no
+     * `runtime.official` threw, and the session's own correct Winter runtime was refused ever after with
+     * `from=claude-agent`. Worse on the restart path — the durable row says `winter-agent`, the official
+     * leg is correctly refused by the row, and the honest follow-up (a Winter query) was then refused by
+     * a ledger that contradicted the row the door had just read. The session was wedged on both legs and
+     * `sdk.handoff()` could not move it, because it had never been where the ledger claimed.
+     *
+     * It is also called with the ROW's runtime when the durable check refuses, so the ledger learns the
+     * truth it just read rather than keeping a guess.
+     */
+    onOpened?: (runtimeKind: RuntimeKind) => void;
+}
+/** A turn stream with backpressure: `push` resolves when the consumer has taken the turn. */
+export interface OfficialInputStream extends AsyncIterable<string> {
+    push(text: string): Promise<void>;
+    close(): void;
+    readonly closed: boolean;
+}
+/**
+ * A single-slot handoff between producers and the runtime.
+ *
+ * BACKPRESSURE IS THE POINT, not a refinement. The alternative — an unbounded queue drained eagerly
+ * from the caller's own iterable — would buffer a whole conversation in memory and, worse, would drain
+ * a caller's generator at a rate the runtime never asked for, so a host streaming from a UI would see
+ * its turns consumed before the model was ready for them. Here nothing moves until the runtime pulls.
+ *
+ * A PUSH AFTER `close()` IS A TYPED REJECTION rather than a silent drop: the messaging adapter turns a
+ * throw into `delivery_uncertain`, and "the session's input ended" is at least an answer the sender's
+ * ledger can record.
+ */
+export declare function createOfficialInputStream(): OfficialInputStream;
+/**
+ * One turn, in the shape the official runtime's streaming input takes.
+ *
+ * The vendor's `SDKUserMessage` is `{ type: "user"; message: MessageParam; parent_tool_use_id }` — a
+ * public Messages-API user message plus two envelope fields. `parent_tool_use_id: null` says this turn
+ * belongs to the session itself rather than to a tool call, which is what a top-level push is.
+ */
+export declare function officialUserTurn(text: string, sessionId: string): OfficialUserMessage;
+/**
+ * Which variable each of this session's credentials fills, and where it lives.
+ *
+ * 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.
+ */
+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`. */
+export declare function officialConnectionEnv(args: {
+    selection: RuntimeSelection;
+    provider: ProviderSelection | undefined;
+    explicit: Readonly<Record<string, string>> | undefined;
+}): Record<string, string>;
+export interface OfficialLegRequest {
+    prompt: string | AsyncIterable<string>;
+    options: Options;
+    input: RouterOfficialInput;
+    selection: RuntimeSelection;
+}
+/**
+ * Opens the official leg, synchronously, returning the vendor's `Query` through a handle that defers
+ * the launch to the first pull (see this module's header, note 1).
+ */
+export declare function openOfficialLeg(deps: OfficialLegDeps, request: OfficialLegRequest): OfficialQuery;
+/**
+ * Starts the caller's own iterable feeding the stream, and closes the stream when it ends.
+ *
+ * SEPARATE FROM `mapPrompt` because the two ends have different owners: the caller's iterable decides
+ * when the session's input is over, and the messaging registry writes into the same stream until it is.
+ */
+export declare function pumpCallerPrompt(prompt: AsyncIterable<string>, stream: OfficialInputStream, onFailure?: (error: unknown) => void): void;

package/dist/errors.d.ts

@@ -0,0 +1,104 @@
+/** The base class of every error this package throws. */
+export declare class RuntimeSdkError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A session's runtime was changed MID-SESSION, and the door will not rewrite the past to serve it.
+ *
+ * D13's own words: "the certified handoff or a visible fork, never a silent rewrite". A persisted
+ * `RuntimeSelection` is a fact about a transcript that already exists — which runtime wrote it, in
+ * which dialect, against which backend session id. Honouring a different `runtimeKind` on the next
+ * `query()` would continue that transcript on a runtime that never wrote any of it, which is the
+ * silent rewrite, and it would do it at the one door where nothing else is watching.
+ *
+ * SO THE DOOR REFUSES AND NAMES THE TWO LEGITIMATE ROUTES. `sdk.handoff(session, to)` runs WS-05
+ * §12's eight steps — drain, compare, validate, persist, transfer the lease, confirm the destination
+ * — and produces a `HandoffOutcome` the host renders; a `forkSession` resume is the visible fork.
+ * Both leave evidence; neither pretends the change did not happen.
+ */
+export declare class RuntimeHandoffRequiredError extends RuntimeSdkError {
+    /** The runtime this session is persisted on. */
+    readonly from: string;
+    /** The runtime the caller asked for. */
+    readonly to: string;
+    readonly address: string;
+    constructor(args: {
+        from: string;
+        to: string;
+        address: string;
+    });
+}
+/**
+ * The official leg was asked for and something only the HOST can supply was missing.
+ *
+ * WHY ITS OWN CLASS RATHER THAN `OfficialConfigurationError`. That class is WS-14 §13's, and it is
+ * about an options object that is wrong — a field this branch refuses, a combination the runtime
+ * 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.
+ */
+export declare class RuntimeLaunchInputError extends RuntimeSdkError {
+    readonly field: string;
+    constructor(args: {
+        field: string;
+        reason: string;
+    });
+}
+/**
+ * A directory row whose address the router cannot name — refused at the door rather than listed.
+ *
+ * WHY IT IS AN ERROR AND NOT A DROPPED ROW (review r4, NEW-13). Every row the directory holds is
+ * shown to a model by `ListAgents` and is then expected to answer `SendMessage`. An address that does
+ * not parse fails all three resolution doors — by the listed string, by its canonicalised form, and
+ * by `deliver()` on the row's own address — so the listing advertises an object nothing can reach and
+ * no error explains why. A LISTED OBJECT IS ALWAYS ADDRESSABLE; the writer is an adapter recording a
+ * launch, and the fix is always one line at the call site, so it is told.
+ *
+ * SPINE-OWNED because two lanes throw it: the directory's `record()` door and the official adapter's
+ * default record sink, which is where the non-canonical address actually came from.
+ */
+export declare class UnaddressableEntryError extends RuntimeSdkError {
+    readonly address: string;
+    constructor(address: string);
+}
+/**
+ * D19a: the injected peers are outside the tested compatibility matrix, so construction refuses.
+ *
+ * `expected`/`actual` are the two fields the plan pins. They are STRINGS, not objects, because the
+ * one thing a host does with them is print them: `expected` is the matrix entry that was violated
+ * (`"@yanlinglabs/winter-agent-sdk >=0.0.2 <0.1.0"`), `actual` is what the injected peer reported
+ * (`"0.0.1"`, or `"unknown (the injected module exports no version identity and no installed copy
+ * could be resolved)"`).
+ */
+export declare class RuntimeSdkVersionError extends RuntimeSdkError {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(args: {
+        expected: string;
+        actual: string;
+        message?: string;
+    });
+}
+/** Which lane of Phase 7b owns a seam that is declared but not yet implemented. */
+export type LaneId = "lane-a" | "lane-b" | "lane-c" | "lane-d";
+/**
+ * A seam the spine pinned and a lane has not landed yet.
+ *
+ * DELIBERATELY A THROW, not a silent no-op or a plausible default. The spine's whole job is to let
+ * four lanes build against final signatures in parallel; a stub that returned something shaped right
+ * would let a lane (or a host) build on an answer nobody computed, and the failure would surface as
+ * wrong behaviour somewhere else. The lane id is a field, not just prose, so a test can assert WHICH
+ * seam is still open (`test/spine/seams.test.ts` does exactly that) and so a close-out check can
+ * enumerate the remaining ones.
+ */
+export declare class NotImplementedYet extends RuntimeSdkError {
+    readonly lane: LaneId;
+    readonly seam: string;
+    constructor(lane: LaneId, seam: string);
+}
+/** A `RuntimeSdk` method called after `dispose()`. */
+export declare class RuntimeSdkDisposedError extends RuntimeSdkError {
+    constructor(method: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export * from "@yanlinglabs/winter-agent-sdk";
+export { createRuntimeSdk, forwardableOptions, runtimeSdkInternals, ROUTER_ONLY_OPTION_KEYS } from "./sdk.js";
+export type { RouterOnlyOptionKey, RouterOptions, RouterRuntimeInput, RuntimeSdk, RuntimeSdkInternals, RuntimeSdkOptions, RuntimeSdkPeers } from "./sdk.js";
+export { assertVersionMatrix, parseVersion, readExportedVersion, readResolvedManifestVersion, satisfiesRange, SUPPORTED, SUPPORTED_PROTOCOL_VERSIONS, VERSION_EXPORT_NAMES } from "./version-matrix.js";
+export type { PeerVersionIdentity, PeerVersionSource, VersionMatrixReport } from "./version-matrix.js";
+export { isSelectionRefusal, selectChildRuntime, selectRuntime, SelectionRefusedError } from "./selection/runtime-selection.js";
+export type { ChildSelectionInput, CredentialPresence, RuntimeKind, RuntimeSelection, SelectionInput, SelectionRefusal } from "./selection/runtime-selection.js";
+export { CHILD_PROVIDER_UNAVAILABLE, resumeChildSelection, selectChildRuntimePairing } from "./selection/child-runtime.js";
+export type { ChildResumeOutcome, ChildRuntimePairing } from "./selection/child-runtime.js";
+export type { ProviderAuthView, SelectionAuthFamily, SelectionVersions } from "./selection/runtime-selection.js";
+export { D14_CLAUDE_OAUTH_APPROVED_DEFAULT, SELECTION_RULES, UNKNOWN_VERSION, reviewPersistedSelection, ruleIdOf, selectionVersionsFrom } from "./selection/select-runtime.js";
+export type { SelectionReview, SelectionRuleId } from "./selection/select-runtime.js";
+export { RESUME_STAGING_PREFIX, isResumeStagingRoot, resumeStagingRoot } from "./vendor-paths.js";
+export { MATERIALIZED_RESUME_PROBE_REPORTS, materializedResumeReportForPin } from "./store/pinned-probes.js";
+export { EXECUTION_INDIRECTION_ENV_NAMES, EXECUTION_INDIRECTION_ENV_PREFIXES, isExecutionIndirectionVariable } from "./official/env-allowlist.js";
+export { TRAFFIC_OPT_OUT_VARIABLES, TRAFFIC_OPT_OUT_VARIABLE_NAMES } from "./official/env-allowlist.js";
+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";
+export * from "./seams/index.js";
+export { NotImplementedYet, RuntimeHandoffRequiredError, RuntimeLaunchInputError, RuntimeSdkDisposedError, RuntimeSdkError, RuntimeSdkVersionError, UnaddressableEntryError } from "./errors.js";
+export { createOfficialInputStream, isOfficialQuery, officialCredentialPlan, officialConnectionEnv, officialUserTurn } from "./door.js";
+export type { OfficialInputStream, RouterOfficialInput, RouterOfficialPolicy, RouterQuery } from "./door.js";
+export type { LaneId } from "./errors.js";
+export { createRuntimeMessaging, createMessagingToolHandlers, createAttachedSessionRegistry } from "./messaging/index.js";
+export type { AttachedOfficialSession, AttachedSession, AttachedSessionRegistry, AttachedWinterSession, DirectorySnapshot, GlobalMessagingHandle, GlobalMessagingOptions, MessagingToolCaller, MessagingToolHandlers, MessagingToolResult, ReplyRequest, RouterMessagingAdapter, RuntimeDirectoryHandle, RuntimeDirectoryOptions, RuntimeDirectoryRecoveryHooks, } from "./messaging/index.js";