@yanlinglabs/winter-agent-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yanlingLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# `@yanlinglabs/winter-agent-sdk`
+
+Winter's wrapper: `query()`, the `Options` surface, the session-management API, settings resolution,
+the transcript store and the brand profile. This is the package a host installs by name; it spawns
+the compiled `winter` runtime and speaks to it over the pinned protocol.
+
+This is the DROP-IN surface Winter's conformance corpus measures against
+`@anthropic-ai/claude-agent-sdk` — same option names, same message shapes, same ordering.
+
+## Install
+
+This package is published to **two registries**, and which one you want depends on who you are.
+
+### From public npm (anyone)
+
+```sh
+npm install @yanlinglabs/winter-agent-sdk
+```
+
+Nothing else is needed: the `@yanlinglabs` scope is public on npm.
+
+### From GitHub Packages (the `yanlingLabs` org)
+
+GitHub Packages needs the scope pointed at it and an authenticated read, even for a public package.
+In your project's `.npmrc`:
+
+```
+@yanlinglabs:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+…with `GITHUB_TOKEN` in the environment — a personal access token carrying `read:packages`, never a
+literal in the file. Then `npm install @yanlinglabs/winter-agent-sdk` as usual.
+
+**The published packages contain COMPILED OUTPUT ONLY.** Each tarball ships `dist/` — the bundled
+JavaScript a consumer imports and the `.d.ts` declarations their type-checker reads — plus its data
+files, `README.md` and `LICENSE`. It does **not** ship `src/`: the TypeScript sources live at
+<https://github.com/yanlingLabs/winter-agent-sdk>, which is where to read them, file an issue, or send
+a patch.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE), which ships in the published tarball.

package/dist/brand.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Every Winter-owned name, as one swappable object.
+ *
+ * Field-by-field authority is WS-01 §2 (§2.1 packages/executables, §2.2 homes, §2.3 ephemeral
+ * state, §2.4 project-local files, §2.5 environment variables) and §3 (product layer).
+ */
+export interface BrandProfile {
+    /** Display name. "Winter" — user-facing prose, never a path segment. */
+    productName: string;
+    /**
+     * The honest product token in `User-Agent` and vendor identity headers (WS-13 §5, D21).
+     *
+     * A reuser presents its OWN identity here: that is the whole point of the field. What it may
+     * never be is somebody else's — the catalog's identity-header validator and the
+     * `codexOriginator` rule below are the two enforcement points for that.
+     */
+    packageName: string;
+    /** `~/<homeDirName>` (WS-01 §2.2). The dev profile appends `-dev`. */
+    homeDirName: string;
+    /** `<cwd>/<projectDirName>/` (WS-01 §2.4) — settings, agents, skills, commands, plans, rules. */
+    projectDirName: string;
+    /** Project + user instructions file (WS-01 §2.4): Claude's `CLAUDE.md` convention, Winter's token. */
+    instructionsFile: string;
+    /** Env-name prefix (WS-01 §2.5). `envName(brand, "HOME")` is the only way product code spells one. */
+    envPrefix: string;
+    /** macOS Keychain service every `{ kind: "keychain" }` credential ref resolves under (WS-01 §3). */
+    keychainService: string;
+    /** The standing in-process MCP server's name: `mcp__<mcpServerName>__<tool>` (WS-09 §1.3). */
+    mcpServerName: string;
+    /** The independently-authored system-prompt preset (WS-11); `preset: "claude_code"` maps onto it. */
+    presetName: string;
+    /** argv0 / process label for supervised spawns (WS-01 §2.1, D12). */
+    processLabel: string;
+    /**
+     * The codex backend's `originator`. DELIBERATELY NON-FIRST-PARTY and validated as such: sending a
+     * vendor's own originator would present Winter as that vendor's client, which is the exact thing
+     * WS-01 §3 and the standing hard rule forbid. A reuser must supply their own token, not borrow one.
+     */
+    codexOriginator: string;
+    /** `/private/tmp/<tempRootName>-<uid>/` — the shared per-user temp root (WS-01 §2.3, D18). */
+    tempRootName: string;
+    /**
+     * Winter's own plugin manifest directory (WS-11). NOT `.claude-plugin`: that is the directory the
+     * OFFICIAL runtime reads, a Claude-mirroring literal this profile deliberately does not own.
+     */
+    pluginManifestDir: string;
+    /**
+     * P7a fix wave (item 7; Lane A review M-4): WHERE TO REACH THE RUNNING PRODUCT.
+     *
+     * A vendor identity field is a `<name>:<version>:<contact>` triple, not a name (AI Horde's
+     * `Client-Agent` is the shipped example, and its whole purpose is that an operator whose workers
+     * are misbehaving can contact whoever wrote the client). `packageName` already moved with the
+     * brand; the CONTACT did not, so a rebranded product's honest-identity header still pointed a
+     * vendor at Winter's issue tracker for traffic Winter never sent. That is not a cosmetic leak —
+     * it is a false statement in the one field whose entire purpose is being true.
+     *
+     * A URL rather than an email: it is what the shipped row already carried, it is the form vendors
+     * document, and it is the one contact shape that discloses nothing personal. Validated as an
+     * `https:` URL — `http:` is refused because this value is published to third parties, and any
+     * other scheme (`mailto:`, `javascript:`, a bare token) is refused because a header value pasted
+     * from a profile is exactly where a surprising scheme should not be accepted.
+     */
+    contactUrl: string;
+}
+/**
+ * The token grammar for the NAME-shaped fields: lowercase, digit- and hyphen-continued, 1..32 chars.
+ *
+ * Applied to `packageName`, `mcpServerName`, `processLabel`, `tempRootName` and `codexOriginator`
+ * and to NOTHING ELSE. `presetName` ("winter_code") has an underscore and is deliberately outside
+ * it; the dot-prefixed dirs, the instructions file, the env prefix and the keychain service each
+ * have their own shape below. A uniform rule over every field would refuse WINTER_BRAND itself.
+ */
+export declare const BRAND_TOKEN_RE: RegExp;
+/**
+ * Originator values that name a FIRST PARTY. `codexOriginator` may never be one of these.
+ *
+ * The list is exported so its refusals are testable by iteration rather than by spot check: adding
+ * a name here automatically adds a test for it (brand.test.ts loops this array).
+ */
+export declare const FIRST_PARTY_ORIGINATORS: readonly string[];
+/** WS-01 §2/§3's own values, byte for byte. Frozen: `resolveBrand()` hands back copies, never this. */
+export declare const WINTER_BRAND: Readonly<BrandProfile>;
+/** A refusal carries WHICH field and WHY, never a bare boolean — the host has to fix something. */
+export type BrandValidation = {
+    ok: true;
+    brand: BrandProfile;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Fold a host's partial profile onto Winter's defaults and validate the result.
+ *
+ * ABSENT AND EXPLICITLY-`undefined` ARE THE SAME THING (`exactOptionalPropertyTypes` is on
+ * repo-wide, so a caller spreading an options object can legitimately produce either): both mean
+ * "keep Winter's value for this field".
+ *
+ * Returns a RESULT rather than throwing. The one caller that must turn a refusal into a throw is
+ * `query()`, which does so as its own typed `InvalidBrandError` at construction time alongside its
+ * other option validation; everything else (tests, a host previewing a profile) wants the value.
+ */
+export declare function resolveBrand(partial?: Partial<BrandProfile>): BrandValidation;
+/**
+ * The ONLY way product code spells a brand-derived environment variable.
+ *
+ * `envName(brand, "HOME")` -> `"WINTER_HOME"`. Takes a `Pick` so a caller holding one field (a
+ * partially-threaded config, a test) can call it without constructing a whole profile.
+ */
+export declare function envName(brand: Pick<BrandProfile, "envPrefix">, suffix: string): string;
+/** `mcpToolName(brand, "send_message")` -> `"mcp__winter__send_message"` (WS-09 §1.3's canonical form). */
+export declare function mcpToolName(brand: Pick<BrandProfile, "mcpServerName">, tool: string): string;
+/** `userAgent(brand, "0.0.1")` -> `"winter-agent-sdk/0.0.1"` — the honest identity on every wire. */
+export declare function userAgent(brand: Pick<BrandProfile, "packageName">, version: string): string;

package/dist/errors.d.ts

@@ -0,0 +1,42 @@
+import type { SdkMessage } from "./protocol/frames.js";
+export declare class WinterSDKError extends Error {
+    constructor(message: string);
+}
+export declare class CLIConnectionError extends WinterSDKError {
+    constructor(message: string);
+}
+export declare class ProcessError extends WinterSDKError {
+    code?: number | null | undefined;
+    signal?: string | null | undefined;
+    constructor(message: string, code?: number | null | undefined, signal?: string | null | undefined);
+}
+export declare class ResultError extends ProcessError {
+    result: Extract<SdkMessage, {
+        type: "result";
+    }>;
+    constructor(result: Extract<SdkMessage, {
+        type: "result";
+    }>);
+}
+export declare class ProtocolDecodeError extends WinterSDKError {
+    constructor(message: string);
+}
+export declare class AbortError extends WinterSDKError {
+    constructor(message: string);
+}
+export declare class SessionNotFoundError extends WinterSDKError {
+    readonly reason: "not_found" | "ambiguous";
+    constructor(reason: "not_found" | "ambiguous", message: string);
+}
+export declare class InvalidBrandError extends WinterSDKError {
+    readonly reason: string;
+    readonly code = "invalid_brand";
+    constructor(reason: string);
+}
+export declare class WinterRpcError extends WinterSDKError {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class WinterRpcTimeoutError extends WinterRpcError {
+    constructor(subtype: string, timeoutMs: number);
+}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+export { query } from "./query.js";
+export type { Query, SdkMessage } from "./query.js";
+export type { QueryInternal, ControlRequestHandler, ControlRequestHandlerResult } from "./query.js";
+export type { Options } from "./options.js";
+export { SYSTEM_PROMPT_DYNAMIC_BOUNDARY, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_PLANS_DIRECTORY, DEFAULT_OUTPUT_STYLE } from "./options.js";
+export { DEFAULT_PROVIDER_STALL_TIMEOUT_MS, DEFAULT_KEYCHAIN_SERVICE } from "./options.js";
+export type { ProviderSelection, ProviderConnectionConfig, CredentialRef, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig, ModelInfo, AccountInfo } from "./protocol/config.js";
+export type { SlotView, ActiveSlotSet, ModelFamilyListing, ModelSlotSetting, ModelRowServable } from "./protocol/config.js";
+export type { SdkPluginConfig, SystemPromptOption, SystemPromptPreset, OutputFormat, JsonSchemaOutputFormat, SkillsOption, RewindFilesResult, RewindFilesRequest, InitPluginInfo } from "./protocol/config.js";
+export type { McpServerConfig, McpSdkServerConfigWithInstance, McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, AgentDefinition } from "./options.js";
+export { isWinterMcpServerInstance } from "./options.js";
+export type { WinterMcpServerInstance } from "./options.js";
+export type { WireMcpToolDefinition } from "./protocol/config.js";
+export { WINTER_BRAND, BRAND_TOKEN_RE, FIRST_PARTY_ORIGINATORS, resolveBrand, envName, mcpToolName, userAgent } from "./brand.js";
+export type { BrandProfile, BrandValidation } from "./brand.js";
+export { WinterSDKError, CLIConnectionError, ProcessError, ResultError, ProtocolDecodeError, AbortError, SessionNotFoundError, WinterRpcError, WinterRpcTimeoutError, InvalidBrandError, } from "./errors.js";
+export { resolveRuntimeExecutable, defaultSpawn } from "./transport.js";
+export type { SpawnedRuntimeProcess, SpawnRuntimeOptions, SpawnClaudeCodeProcess } from "./transport.js";
+export type { RuntimeConfig, RuntimeHooksConfig, RuntimeHookMatcherGroup, SandboxSettingsConfig } from "./protocol/config.js";
+export type { McpServerConfigForProcessTransport, AgentMcpServerSpec, RuntimeAgentDefinition } from "./protocol/config.js";
+export { encodeFrame, decodeFrame, splitFrames, ProtocolError } from "./protocol/codec.js";
+export { PROTOCOL_VERSION } from "./protocol/frames.js";
+export type { ProtocolVersion, WinterFrame, SdkMessage as ProtocolSdkMessage, InitFrame, UserFrame, DataFrame, ControlRequestFrame, ControlResponseFrame, UnknownFrame, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKPermissionDenial, SDKTaskStartedMessage, SDKTaskNotificationMessage, SDKTaskUpdatedMessage, SDKTaskProgressMessage, SDKBackgroundTasksChangedMessage, SDKLocalCommandOutputMessage, BackgroundTaskMessage, SDKCompactBoundaryMessage, WireContentBlock, WireStreamEvent, WireStreamEventDelta, SDKPartialAssistantMessage, SDKAssistantMessageError, SDKAPIRetryMessage, SDKRateLimitEvent, SDKRateLimitInfo, SDKAuthStatusMessage, SDKThinkingTokensMessage, SDKModelRefusalFallbackMessage, SDKModelRefusalNoFallbackMessage, SDKReasoningSummaryMessage, SDKModelSwitchMessage, SDKContinuityWarningMessage, } from "./protocol/frames.js";
+export { resolveWinterHome, resolveKeychainServiceForProfile, isUnset } from "./paths/home.js";
+export { transcriptProjectKey } from "./paths/project-key.js";
+export { compatibilityKeys } from "./paths/keys.js";
+export type { CompatibilityKeys } from "./paths/keys.js";
+export { WinterCompatibilitySessionStore, WinterStoreError, WinterStoreLeaseError, DIALECT_RECORD_ENTRY_TYPE, PROVIDER_STATE_FILE_SUFFIX, } from "./store/session-store.js";
+export type { SessionKey, SessionStoreEntry, SessionSummaryEntry, SessionStore } from "./store/session-store.js";
+export { forkSessionByKey } from "./store/fork-session.js";
+export { listSessions, getSessionInfo, getSessionMessages, renameSession, tagSession, deleteSession, forkSession, listSubagents, getSubagentMessages, } from "./sessions.js";
+export { resolveSettings, filterEscalatingDefaultMode, resolveSettingsDetailed, applyWorkspaceTrust, } from "./settings/resolve.js";
+export { settingsPathFor, loadSettingsFile } from "./settings/sources.js";
+export { validateModelSlots } from "./settings/model-slots.js";
+export type { ModelSlotsLookup, ModelSlotsValidation } from "./settings/model-slots.js";
+export type { SettingsPathOptions, LoadedSettingsFile } from "./settings/sources.js";
+export { SETTING_SOURCES, OVERLAY_NEVER_KEYS, ESCALATING_PERMISSION_MODES, PROJECT_PERMISSIVE_KEYS, providerSettingsFrom, } from "./settings/types.js";
+export type { SettingSource, ResolvedSettingSource, PolicySettingsOrigin, Settings, SettingsPermissionsBlock, SettingsHooksConfig, SettingsHookMatcherGroup, SettingsHookHandler, ProvenanceEntry, ResolvedSettings, ResolvedSettingsSourceEntry, ResolveSettingsOptions, DetailedResolvedSettings, DetailedSettingsSourceEntry, ResolveSettingsDetailedOptions, } from "./settings/types.js";
+export type { WorkspaceTrustFilterOptions } from "./settings/resolve.js";
+export type { PermissionMode, PermissionBehavior, PermissionRuleValue } from "./permissions/types.js";
+export type { PermissionUpdate, PermissionUpdateDestination, RuleSource } from "./permissions/types.js";
+export type { CanUseTool, PermissionResult, PermissionDecisionClassification, PermissionRequestPayload } from "./permissions/types.js";
+export { HOOK_EVENTS } from "./permissions/types.js";
+export type { HookEvent, HookEventName, HookSource, HookPermissionDecision, BaseHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, UserPromptSubmitHookInput, StopHookInput, SessionStartHookInput, SessionEndHookInput, NotificationHookInput, PermissionRequestHookInput, PermissionDeniedHookInput, GenericHookInput, HookInput, AsyncHookJSONOutput, SyncHookJSONOutput, HookJSONOutput, PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, UserPromptSubmitHookSpecificOutput, StopHookSpecificOutput, SessionStartHookSpecificOutput, NotificationHookSpecificOutput, PermissionRequestHookSpecificOutput, PermissionDeniedHookSpecificOutput, GenericHookSpecificOutput, HookSpecificOutput, HookCallback, HookCallbackMatcher, HookInvocationPayload, } from "./permissions/types.js";