@yanlinglabs/winter-agent-sdk 0.0.24 → 0.0.28

package/dist/index.d.ts

@@ -20,14 +20,14 @@ export { WinterSDKError, CLIConnectionError, ProcessError, ResultError, Protocol
 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 type { McpServerConfigForProcessTransport, McpVersionNegotiation, AgentMcpServerSpec, RuntimeAgentDefinition } from "./protocol/config.js";
 export { encodeFrame, decodeFrame, splitFrames, ProtocolError } from "./protocol/codec.js";
 export { PROTOCOL_VERSION } from "./protocol/frames.js";
 export { SDK_VERSION } from "./version.js";
 export { MESSAGING_CONTROL_SUBTYPES, MESSAGING_CONTROL_SUBTYPE_LIST, MESSAGING_HOST_REQUEST_SUBTYPES, MESSAGING_RUNTIME_REQUEST_SUBTYPES, resolveFacetTarget } from "./protocol/messaging.js";
 export { isRuntimeAddress, isGlobalAgentMessage, isDeliveryOutcome, isListedRuntimeObjectArray, isPermissionClassLabel, isMessagingDeliverRequest, isMessagingChildRequest, isMessagingSubscribeIdleRequest, isMessagingReadNotificationsRequest, isMessagingNotificationsPage, isMessagingIdleNoticePayload, isNotificationRecord, } from "./protocol/messaging.js";
 export type { MessagingControlSubtype, MessagingDeliverRequest, MessagingChildRequest, MessagingSubscribeIdleRequest, MessagingSenderClassResponse, MessagingReadNotificationsRequest, MessagingNotificationsPage, MessagingIdleNoticePayload, } from "./protocol/messaging.js";
-export type { ProtocolVersion, WinterFrame, SdkMessage as ProtocolSdkMessage, InitFrame, UserFrame, DataFrame, ControlRequestFrame, ControlResponseFrame, ControlCancelRequestFrame, WireResultUsage, UnknownFrame, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKPermissionDenial, SDKTaskStartedMessage, SDKTaskNotificationMessage, SDKTaskUpdatedMessage, SDKTaskProgressMessage, SDKBackgroundTasksChangedMessage, SDKLocalCommandOutputMessage, BackgroundTaskMessage, SDKCompactBoundaryMessage, SDKSessionStateChangedMessage, WireContentBlock, WireStreamEvent, WireStreamEventDelta, SDKPartialAssistantMessage, SDKAssistantMessageError, SDKAPIRetryMessage, SDKRateLimitEvent, SDKRateLimitInfo, SDKAuthStatusMessage, SDKThinkingTokensMessage, SDKModelRefusalFallbackMessage, SDKModelRefusalNoFallbackMessage, SDKReasoningSummaryMessage, SDKModelSwitchMessage, SDKContinuityWarningMessage, } from "./protocol/frames.js";
+export type { ProtocolVersion, WinterFrame, SdkMessage as ProtocolSdkMessage, InitFrame, UserFrame, DataFrame, ControlRequestFrame, ControlResponseFrame, ControlCancelRequestFrame, WireResultUsage, UnknownFrame, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKPermissionDenial, SDKTaskStartedMessage, SDKTaskNotificationMessage, SDKTaskUpdatedMessage, SDKTaskProgressMessage, SDKBackgroundTasksChangedMessage, SDKLocalCommandOutputMessage, BackgroundTaskMessage, SDKCompactBoundaryMessage, SDKSessionStateChangedMessage, SDKInformationalMessage, 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, TRANSCRIPT_PROJECT_KEY_MAX_LENGTH, isVendorCompliantProjectKey } from "./paths/project-key.js";
 export { compatibilityKeys } from "./paths/keys.js";
@@ -50,7 +50,7 @@ export type { PermissionMode, PermissionBehavior, PermissionRuleValue } from "./
 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";
+export type { HookEvent, HookEventName, HookSource, HookPermissionDecision, BaseHookInput, McpToolProvenance, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, UserPromptSubmitHookInput, StopHookInput, SessionStartHookInput, SessionEndHookInput, NotificationHookInput, PermissionRequestHookInput, PermissionDeniedHookInput, SubagentStartHookInput, SubagentStopHookInput, GenericHookInput, HookInput, AsyncHookJSONOutput, SyncHookJSONOutput, HookJSONOutput, PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, UserPromptSubmitHookSpecificOutput, StopHookSpecificOutput, SubagentStartHookSpecificOutput, SubagentStopHookSpecificOutput, SessionStartHookSpecificOutput, NotificationHookSpecificOutput, PermissionRequestHookSpecificOutput, PermissionDeniedHookSpecificOutput, GenericHookSpecificOutput, HookSpecificOutput, HookCallback, HookCallbackMatcher, HookInvocationPayload, } from "./permissions/types.js";
 export { CATALOG_TAG_RENAMES } from "@yanlinglabs/winter-provider-catalog";
 export { PluginManagerError, listMarketplaces, addMarketplace, removeMarketplace, updateMarketplace, installPlugin, uninstallPlugin, setPluginEnabled, updatePlugin, listPlugins } from "./plugins/manage.js";
 export type { PluginScope, PluginManagerOptions, MarketplaceInfo, InstalledPlugin, PluginListing } from "./plugins/manage.js";

package/dist/index.js

@@ -139,7 +139,7 @@ class ProcessError extends WinterSDKError {
 class ResultError extends ProcessError {
   result;
   constructor(result) {
-    super(result.terminal_reason === "api_error" ? `provider request failed: ${result.result ?? "unknown provider error"}` : `result error: ${result.subtype}`);
+    super(result.terminal_reason === "api_error" ? `provider request failed: ${result.result ?? "unknown provider error"}` : result.is_error === true && typeof result.terminal_reason === "string" && result.terminal_reason.length > 0 ? `${result.terminal_reason}: ${result.result ?? result.subtype}` : `result error: ${result.subtype}`);
     this.result = result;
     this.name = "ResultError";
   }
@@ -488,7 +488,8 @@ function buildRuntimeHooksConfig(hooks) {
         hookCount: group.hooks.length,
         ...group.timeout !== undefined ? { timeoutSec: group.timeout } : {},
         source: "sdk",
-        ...hookNames.some((n) => n !== null) ? { hookNames } : {}
+        ...hookNames.some((n) => n !== null) ? { hookNames } : {},
+        ...group.failClosed === true ? { failClosed: true } : {}
       };
     });
   }
@@ -503,6 +504,8 @@ function buildHookInput(req, cwd) {
     ...req.agentID !== undefined ? { agent_id: req.agentID } : {},
     hook_event_name: req.event,
     ...req.toolName !== undefined ? { tool_name: req.toolName } : {},
+    ...req.mcpServerName !== undefined ? { mcp_server_name: req.mcpServerName } : {},
+    ...req.mcpToolName !== undefined ? { mcp_tool_name: req.mcpToolName } : {},
     ...req.input !== undefined ? { tool_input: req.input } : {},
     ...req.toolUseID !== undefined ? { tool_use_id: req.toolUseID } : {},
     ...payload
@@ -517,7 +520,7 @@ function makeHookHandler(hooks, cwd, abortController) {
       });
     });
   }
-  return async (payload) => {
+  return async (payload, handlerCtx) => {
     const req = payload;
     const callback = byId.get(req.hookId);
     if (!callback) {
@@ -528,6 +531,10 @@ function makeHookHandler(hooks, cwd, abortController) {
       controller.abort();
     else
       abortController?.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    if (handlerCtx?.signal.aborted === true)
+      controller.abort();
+    else
+      handlerCtx?.signal.addEventListener("abort", () => controller.abort(), { once: true });
     const input = buildHookInput(req, cwd);
     let output;
     try {
@@ -619,6 +626,7 @@ function query(args) {
     ...options.enableFileCheckpointing !== undefined ? { enableFileCheckpointing: options.enableFileCheckpointing } : {},
     ...options.contextWindowTokens !== undefined ? { contextWindowTokens: options.contextWindowTokens } : {},
     ...options.compactionThreshold !== undefined ? { compactionThreshold: options.compactionThreshold } : {},
+    ...options.promptCacheTtl !== undefined ? { promptCacheTtl: options.promptCacheTtl } : {},
     ...options.trustedWorkspace !== undefined ? { trustedWorkspace: options.trustedWorkspace } : {},
     ...options.plansDirectory !== undefined ? { plansDirectory: options.plansDirectory } : {},
     ...options.outputStyle !== undefined ? { outputStyle: options.outputStyle } : {},
@@ -630,6 +638,7 @@ function query(args) {
     ...options.includePartialMessages !== undefined ? { includePartialMessages: options.includePartialMessages } : {},
     ...options.maxBudgetUsd !== undefined ? { maxBudgetUsd: options.maxBudgetUsd } : {},
     ...options.providerStallTimeoutMs !== undefined ? { providerStallTimeoutMs: options.providerStallTimeoutMs } : {},
+    ...options.maxOutputTokens !== undefined ? { maxOutputTokens: options.maxOutputTokens } : {},
     ...brand.keychainService !== WINTER_BRAND2.keychainService || options.keychainService !== undefined ? { keychainService: brand.keychainService } : {},
     ...options.autoClassifier !== undefined ? { autoClassifier: options.autoClassifier } : {},
     ...options.advisor !== undefined ? { advisor: options.advisor } : {},
@@ -902,6 +911,14 @@ function query(args) {
   gen.setModel = async (model) => {
     await sendControlRequest("set_model", model !== undefined ? { model } : {});
   };
+  gen.setEffort = async (effort) => {
+    await sendControlRequest("set_effort", effort !== undefined ? { effort } : {});
+  };
+  gen.compact = async (opts) => {
+    const payload = await sendControlRequest("compact", opts?.customInstructions !== undefined ? { custom_instructions: opts.customInstructions } : {});
+    const retained = typeof payload === "object" && payload !== null ? payload.retained_count : undefined;
+    return { retainedCount: typeof retained === "number" ? retained : 0 };
+  };
   gen.supportedModels = async () => {
     const payload = await sendControlRequest("list_models", undefined);
     return Array.isArray(payload) ? payload : [];
@@ -1021,7 +1038,7 @@ function query(args) {
   return gen;
 }
 // src/version.ts
-var SDK_VERSION = "0.0.24";
+var SDK_VERSION = "0.0.28";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;

package/dist/options.d.ts

@@ -191,6 +191,15 @@ export interface Options {
     sessionStore?: SessionStore;
     contextWindowTokens?: number;
     compactionThreshold?: number;
+    /**
+     * WS-23 -- DISCLOSED WINTER option: how long the provider keeps this session's cached SYSTEM prompt.
+     * `"5m"` (the default, the vendor's own) or `"1h"` (written at twice the input price, worth it where
+     * idle gaps of 5-60 minutes are common: https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration).
+     * Applies to models whose catalog row documents prompt caching; the conversation's own rolling
+     * breakpoint stays at 5 minutes, which is the order the vendor requires (longer TTLs first). The
+     * host's choice; resolved runtime-side, so absent is byte-identical to before.
+     */
+    promptCacheTtl?: "5m" | "1h";
     trustedWorkspace?: boolean;
     plansDirectory?: string;
     outputStyle?: string;
@@ -269,6 +278,14 @@ export interface Options {
     maxBudgetUsd?: number;
     /** DISCLOSED WINTER option (R6-6): a stream silent for this long aborts as a typed `ProviderStallError`. Absent means DEFAULT_PROVIDER_STALL_TIMEOUT_MS. */
     providerStallTimeoutMs?: number;
+    /**
+     * DISCLOSED WINTER option (WS-23): the output-token ceiling (`max_tokens` on the Anthropic dialect)
+     * every main-loop generation asks for. Absent means the adapter's own default -- on a Claude row,
+     * 64000 capped at the row's declared maximum. A value above the row's maximum is refused typed,
+     * before the request. Forwarded as `TurnRequest.maxOutputTokens`, which an adapter treats as an
+     * explicit request (it wins over every default).
+     */
+    maxOutputTokens?: number;
     /** DISCLOSED WINTER option (R6-10): the macOS Keychain service every `{ kind: "keychain" }` ref resolves under. Absent means DEFAULT_KEYCHAIN_SERVICE. */
     keychainService?: string;
     /** DISCLOSED WINTER option (R6-14): the permission classifier's own model/credential, resolved through the SAME selection path as the session model. With none configured the worker serves only a `classifierEligible` model, else Manual fallback — never a silent weakening. */

package/dist/permissions/types.d.ts

@@ -101,13 +101,17 @@ export interface BaseHookInput {
     };
 }
 export type HookPermissionDecision = "allow" | "ask" | "deny" | "defer";
-export interface PreToolUseHookInput extends BaseHookInput {
+export interface McpToolProvenance {
+    mcp_server_name?: string;
+    mcp_tool_name?: string;
+}
+export interface PreToolUseHookInput extends BaseHookInput, McpToolProvenance {
     hook_event_name: "PreToolUse";
     tool_name: string;
     tool_input: unknown;
     tool_use_id: string;
 }
-export interface PostToolUseHookInput extends BaseHookInput {
+export interface PostToolUseHookInput extends BaseHookInput, McpToolProvenance {
     hook_event_name: "PostToolUse";
     tool_name: string;
     tool_input: unknown;
@@ -115,7 +119,7 @@ export interface PostToolUseHookInput extends BaseHookInput {
     tool_use_id: string;
     duration_ms?: number;
 }
-export interface PostToolUseFailureHookInput extends BaseHookInput {
+export interface PostToolUseFailureHookInput extends BaseHookInput, McpToolProvenance {
     hook_event_name: "PostToolUseFailure";
     tool_name: string;
     tool_input: unknown;
@@ -154,25 +158,39 @@ export interface NotificationHookInput extends BaseHookInput {
     title?: string;
     notification_type: string;
 }
-export interface PermissionRequestHookInput extends BaseHookInput {
+export interface PermissionRequestHookInput extends BaseHookInput, McpToolProvenance {
     hook_event_name: "PermissionRequest";
     tool_name: string;
     tool_input: unknown;
     permission_suggestions?: PermissionUpdate[];
 }
-export interface PermissionDeniedHookInput extends BaseHookInput {
+export interface PermissionDeniedHookInput extends BaseHookInput, McpToolProvenance {
     hook_event_name: "PermissionDenied";
     tool_name: string;
     tool_input: unknown;
     tool_use_id: string;
     reason: string;
 }
+export interface SubagentStartHookInput extends BaseHookInput {
+    hook_event_name: "SubagentStart";
+    agent_id: string;
+    agent_type: string;
+}
+export interface SubagentStopHookInput extends BaseHookInput {
+    hook_event_name: "SubagentStop";
+    stop_hook_active: boolean;
+    agent_id: string;
+    agent_transcript_path: string;
+    agent_type: string;
+    last_assistant_message?: string;
+}
 export interface GenericHookInput extends BaseHookInput {
     hook_event_name: string;
 }
-export type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | UserPromptSubmitHookInput | StopHookInput | SessionStartHookInput | SessionEndHookInput | NotificationHookInput | PermissionRequestHookInput | PermissionDeniedHookInput | GenericHookInput;
+export type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | UserPromptSubmitHookInput | StopHookInput | SessionStartHookInput | SessionEndHookInput | NotificationHookInput | PermissionRequestHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | GenericHookInput;
 export interface AsyncHookJSONOutput {
     async: true;
+    /** Milliseconds the background run may take (the runtime's default is 10 minutes). */
     asyncTimeout?: number;
 }
 export interface PreToolUseHookSpecificOutput {
@@ -203,6 +221,14 @@ export interface StopHookSpecificOutput {
     hookEventName: "Stop";
     additionalContext?: string;
 }
+export interface SubagentStartHookSpecificOutput {
+    hookEventName: "SubagentStart";
+    additionalContext?: string;
+}
+export interface SubagentStopHookSpecificOutput {
+    hookEventName: "SubagentStop";
+    additionalContext?: string;
+}
 export interface SessionStartHookSpecificOutput {
     hookEventName: "SessionStart";
     additionalContext?: string;
@@ -236,7 +262,7 @@ export interface GenericHookSpecificOutput {
     additionalContext?: string;
     [key: string]: unknown;
 }
-export type HookSpecificOutput = PreToolUseHookSpecificOutput | PostToolUseHookSpecificOutput | PostToolUseFailureHookSpecificOutput | UserPromptSubmitHookSpecificOutput | StopHookSpecificOutput | SessionStartHookSpecificOutput | NotificationHookSpecificOutput | PermissionRequestHookSpecificOutput | PermissionDeniedHookSpecificOutput | GenericHookSpecificOutput;
+export type HookSpecificOutput = PreToolUseHookSpecificOutput | PostToolUseHookSpecificOutput | PostToolUseFailureHookSpecificOutput | UserPromptSubmitHookSpecificOutput | StopHookSpecificOutput | SubagentStartHookSpecificOutput | SubagentStopHookSpecificOutput | SessionStartHookSpecificOutput | NotificationHookSpecificOutput | PermissionRequestHookSpecificOutput | PermissionDeniedHookSpecificOutput | GenericHookSpecificOutput;
 export interface SyncHookJSONOutput {
     continue?: boolean;
     suppressOutput?: boolean;
@@ -255,6 +281,15 @@ export interface HookCallbackMatcher {
     matcher?: string;
     hooks: HookCallback[];
     timeout?: number;
+    /**
+     * WS-23: FAIL CLOSED. Default off, so a hook that errors stays a non-blocking error exactly as
+     * before. When true, and the event is `PreToolUse` or `PermissionRequest`, a callback that throws,
+     * times out or returns a malformed output DENIES the call, with a reason naming the hook -- the
+     * posture a SECURITY hook needs (a floor that crashes must not wave the call through). Every hook
+     * in this matcher shares it, like `timeout`. Ignored on every other event: none of them decides a
+     * call, so there is nothing for "closed" to mean there.
+     */
+    failClosed?: boolean;
 }
 export interface HookInvocationPayload {
     event: string;
@@ -263,6 +298,10 @@ export interface HookInvocationPayload {
     agentID?: string;
     toolUseID?: string;
     toolName?: string;
+    /** WS-24: for an MCP tool, the connected server that registered `toolName` -- see `McpToolProvenance`. */
+    mcpServerName?: string;
+    /** WS-24: for an MCP tool, the tool's own name on that server -- see `McpToolProvenance`. */
+    mcpToolName?: string;
     input?: Record<string, unknown>;
     payload?: unknown;
     policyVersion: string;

package/dist/protocol/config.d.ts

@@ -78,6 +78,7 @@ export interface RuntimeHookMatcherGroup {
     timeoutSec?: number;
     source: HookSource;
     hookNames?: Array<string | null>;
+    failClosed?: boolean;
 }
 export type RuntimeHooksConfig = Partial<Record<string, RuntimeHookMatcherGroup[]>>;
 export interface SandboxSettingsConfig {
@@ -103,6 +104,22 @@ export interface McpServerToolPolicy {
     permission_policy?: "always_allow" | "always_ask" | "always_deny";
     org_max_permission?: "allow" | "ask" | "blocked";
 }
+/**
+ * WS-23, WINTER-OWNED (no counterpart on the pinned official shape): how the runtime's MCP client
+ * negotiates the protocol revision with ONE server (MCP TS SDK v2, protocol revision 2026-07-28).
+ *
+ * - `"legacy"` -- the plain 2025 `initialize` handshake, byte-identical to the v1 client.
+ * - `"auto"` -- probe `server/discover` first; a server that offers 2026-07-28 gets the modern era,
+ *   anything else falls back to `initialize`.
+ * - `{ pin: "<revision>" }` -- the modern era at exactly that revision, or the connect fails (typed).
+ *
+ * Absent means the per-transport default the runtime owns (`mcp/client.ts`'s
+ * `resolveVersionNegotiation`): `"auto"` for `http`, `"legacy"` for `stdio` and `sse`. The negotiated
+ * revision is reported per server on the `mcp_status` control response.
+ */
+export type McpVersionNegotiation = "legacy" | "auto" | {
+    pin: string;
+};
 export interface McpStdioServerConfig {
     type?: "stdio";
     command: string;
@@ -110,6 +127,7 @@ export interface McpStdioServerConfig {
     env?: Record<string, string>;
     timeout?: number;
     alwaysLoad?: boolean;
+    versionNegotiation?: McpVersionNegotiation;
 }
 export interface McpHttpServerConfig {
     type: "http";
@@ -118,6 +136,7 @@ export interface McpHttpServerConfig {
     tools?: McpServerToolPolicy[];
     timeout?: number;
     alwaysLoad?: boolean;
+    versionNegotiation?: McpVersionNegotiation;
 }
 export interface McpSSEServerConfig {
     type: "sse";
@@ -126,6 +145,7 @@ export interface McpSSEServerConfig {
     tools?: McpServerToolPolicy[];
     timeout?: number;
     alwaysLoad?: boolean;
+    versionNegotiation?: McpVersionNegotiation;
 }
 export interface WireMcpToolDefinition {
     name: string;
@@ -299,6 +319,8 @@ export interface RuntimeConfig {
     enableFileCheckpointing?: boolean;
     contextWindowTokens?: number;
     compactionThreshold?: number;
+    /** WS-23: the system prompt's cache lifetime (`Options.promptCacheTtl`); absent means the runtime's default, 5 minutes. */
+    promptCacheTtl?: "5m" | "1h";
     trustedWorkspace?: boolean;
     plansDirectory?: string;
     outputStyle?: string;
@@ -332,6 +354,8 @@ export interface RuntimeConfig {
     includePartialMessages?: boolean;
     maxBudgetUsd?: number;
     providerStallTimeoutMs?: number;
+    /** WS-23: `Options.maxOutputTokens`, carried to every main-loop `TurnRequest`. See its own doc. */
+    maxOutputTokens?: number;
     keychainService?: string;
     autoClassifier?: AutoClassifierConfig;
     advisor?: AdvisorConfig;

package/dist/protocol/frames.d.ts

@@ -4,6 +4,7 @@ export declare const PROTOCOL_VERSION: "1.0";
 export interface WireMcpServerStatus {
     name: string;
     status: string;
+    protocolVersion?: string;
 }
 export interface InitFrame {
     type: "init";
@@ -57,8 +58,9 @@ export interface ControlResponseFrame {
  *     adapters send `{type: "ephemeral"}` with no ttl), so `ephemeral_5m_input_tokens` equals
  *     `cache_creation_input_tokens` and `ephemeral_1h_input_tokens` is 0;
  *   - `server_tool_use`: Winter's WebSearch/WebFetch run client-side, never as billed server tools: 0/0;
- *   - `output_tokens_details.thinking_tokens`: 0 -- providers' reasoning-token counts are not threaded
- *     through Winter's usage yet (they are included in `output_tokens`);
+ *   - `output_tokens_details.thinking_tokens`: the Responses family's reasoning-token count (WS-24
+ *     follow-up 1) when the turn's provider reported one, else 0 -- always a SUBSET of `output_tokens`,
+ *     never added on top. Anthropic reports no separate count, so a Claude-only turn stays 0;
  *   - `service_tier: "standard"`, `inference_geo: ""`, `iterations: []`, `speed: "standard"`: the
  *     pinned EMPTY_USAGE's own values.
  */
@@ -82,6 +84,19 @@ export interface WireResultUsage {
     inference_geo: string;
     iterations: unknown[];
     speed: "standard" | "fast";
+    /**
+     * WS-23 -- WINTER-ONLY, additive, present only when there is something to say: each generation of
+     * this turn whose provider reported where its prompt prefix diverged from the previous request
+     * (Anthropic's `diagnostics.cache_miss_reason`: `type`, in Anthropic's own vocabulary only, and the
+     * estimated `missed_input_tokens` it cost), and/or that it dropped replayed thinking blocks
+     * (`thinking_blocks_dropped`, from `input_transformations` -- its own field, never a `type`). claude
+     * has no such field.
+     */
+    cache_misses?: Array<{
+        type?: string;
+        missed_input_tokens?: number;
+        thinking_blocks_dropped?: number;
+    }>;
 }
 export interface ControlCancelRequestFrame {
     type: "control_cancel_request";
@@ -582,8 +597,13 @@ export interface SDKContinuityWarningMessage {
      * ANOTHER provider for which no credential is configured (Ruling E-1 / R-E3) -- the child then
      * runs on a deferred-refusal provider whose first generation is R6-F's result with no request,
      * never the parent's provider with a foreign model id on the parent's wire.
+     *
+     * WS-23 (reasoning-state) adds three, each shown to the user by the host: `model_switch_lossy` at a
+     * switch whose loss class is `warned-lossy`; `switch_compaction` when the conversation is summarized
+     * before a switch to a model that cannot hold it; `reasoning_state_unsaved` when a turn's reasoning
+     * records could not be written after one retry (the thinking is then kept inline in the transcript).
      */
-    warning: "provider_state_missing" | "provider_state_deleted" | "cross_domain_replay_dropped" | "sidecar_unreadable" | "child_provider_refused";
+    warning: "provider_state_missing" | "provider_state_deleted" | "cross_domain_replay_dropped" | "sidecar_unreadable" | "child_provider_refused" | "model_switch_lossy" | "switch_compaction" | "reasoning_state_unsaved";
     detail: string;
     anchor_uuid?: string;
     uuid: string;
@@ -607,6 +627,23 @@ export interface SDKSessionStateChangedMessage {
     session_id: string;
     [k: string]: unknown;
 }
+/**
+ * WS-23: claude 2.1.282's `SDKInformationalMessage` -- "generic text banner emitted by the loop --
+ * non-error status lines, hook feedback (e.g. a UserPromptSubmit hook's block reason)". Winter had no
+ * text-notice frame at all; this is the one a hook's `systemMessage`, a blocked prompt's reason and a
+ * hook's `continue: false` ride to the host. `prevent_continuation` is set when the notice is the
+ * reason the turn is ending.
+ */
+export interface SDKInformationalMessage {
+    type: "system";
+    subtype: "informational";
+    content: string;
+    level: "info" | "notice" | "suggestion" | "warning";
+    tool_use_id?: string;
+    prevent_continuation?: boolean;
+    uuid: string;
+    session_id: string;
+}
 export type SdkMessage = {
     type: "system";
     subtype: "init";
@@ -631,7 +668,7 @@ export type SdkMessage = {
      */
     agents?: string[];
     [k: string]: unknown;
-} | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPermissionDeniedMessage | SDKStatusMessage | SDKCompactBoundaryMessage | SDKSessionStateChangedMessage | BackgroundTaskMessage | SDKPartialAssistantMessage | SDKAPIRetryMessage | SDKRateLimitEvent | SDKAuthStatusMessage | SDKThinkingTokensMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKReasoningSummaryMessage | SDKModelSwitchMessage | SDKContinuityWarningMessage | {
+} | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPermissionDeniedMessage | SDKStatusMessage | SDKCompactBoundaryMessage | SDKSessionStateChangedMessage | SDKInformationalMessage | BackgroundTaskMessage | SDKPartialAssistantMessage | SDKAPIRetryMessage | SDKRateLimitEvent | SDKAuthStatusMessage | SDKThinkingTokensMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKReasoningSummaryMessage | SDKModelSwitchMessage | SDKContinuityWarningMessage | {
     type: "assistant";
     message: {
         content: Array<{
@@ -661,7 +698,7 @@ export type SdkMessage = {
     is_error?: boolean;
     result?: string;
     structured_output?: unknown;
-    terminal_reason?: "structured_output_retry_exhausted" | "api_error" | string;
+    terminal_reason?: "structured_output_retry_exhausted" | "api_error" | "refusal" | "prompt_too_long" | "pause_turn_limit" | string;
     api_error_status?: number | null;
     /** THIS turn's main-loop usage -- claude's `result.usage` (dist-session fixes C1); see `WireResultUsage`. */
     usage?: WireResultUsage;

package/dist/query.d.ts

@@ -1,5 +1,5 @@
 import type { SdkMessage as RuntimeSdkMessage } from "./protocol/frames.js";
-import type { AccountInfo, AgentInfo, ModelInfo, ModelFamilyListing, RewindFilesResult } from "./protocol/config.js";
+import type { AccountInfo, AgentInfo, EffortLevel, ModelInfo, ModelFamilyListing, RewindFilesResult } from "./protocol/config.js";
 import { type Options } from "./options.js";
 import type { PermissionMode, PermissionResult } from "./permissions/types.js";
 import { type DeliveryOutcome, type GlobalAgentMessage, type ListedRuntimeObject, type PermissionClassLabel } from "./messaging/index.js";
@@ -118,6 +118,36 @@ export interface SessionMessagingFacet {
 export interface Query extends AsyncGenerator<SdkMessage> {
     interrupt(): Promise<void>;
     setModel(model?: string): Promise<void>;
+    /**
+     * WS-23 -- WINTER-ONLY, additive: change the session's effort level while it runs. Applied at the
+     * next quiescent boundary (immediately when idle), exactly like `setModel`. Omitted, `null` or
+     * `'default'` resets to the level the session started with.
+     *
+     * On a model whose catalog row documents per-message effort (Claude Fable 5.1, Opus 5.5, Opus 5)
+     * the change rides a mid-conversation `system` message and the cached prompt prefix survives it;
+     * elsewhere it is a new top-level value, which restarts the provider's prompt cache. A level the
+     * current model does not document rejects with an `invalid_effort` error.
+     *
+     * claude 2.1.282 has no method for this (it changes effort through its `apply_flag_settings`
+     * control request); it rides Winter's own `set_effort` control subtype.
+     */
+    setEffort(effort?: EffortLevel | null): Promise<void>;
+    /**
+     * WS-23 -- WINTER-ONLY, additive: compact the conversation NOW, on the model the session is live on,
+     * and resolve once it has finished (`retainedCount`: the messages kept beside the summary). A host
+     * calls it before a switch to another provider whose model cannot hold the conversation, so the model
+     * being left writes the summary. Rejects with `busy` while a turn (or another compaction) runs, and
+     * with `compaction_failed` when there was nothing to compact or the summarizer failed.
+     *
+     * OPTIONAL on the interface (every `Query` this package returns has it): a host's own structural
+     * `Query` double -- the router's test peers, a daemon's fakes -- keeps type-checking without it, and a
+     * caller checks for it before calling.
+     */
+    compact?(opts?: {
+        customInstructions?: string;
+    }): Promise<{
+        retainedCount: number;
+    }>;
     /**
      * Phase 6 Task 10 (derived-shapes-p6 item (d), `sdk.d.ts:2566`): the models this session may select.
      *

package/dist/settings/types.d.ts

@@ -18,12 +18,23 @@ export interface SettingsHookHandler {
     /** `"command"` is the only shape a settings file can express; see buildHookEntriesFromSettings. */
     type?: string;
     command?: string;
-    /** SECONDS (HookCallbackMatcher.timeout's pinned unit) -- converted to ms exactly once, at entry-build time. */
+    /** SECONDS (HookCallbackMatcher.timeout's pinned unit) -- converted to ms exactly once, at entry-build time. For an `async` handler, its background run's timeout. */
     timeout?: number;
+    /** WS-23: fail CLOSED on PreToolUse/PermissionRequest (an error, a timeout or malformed output denies the call). Only a literal `true`. */
+    failClosed?: boolean;
+    /**
+     * WS-24: run in the BACKGROUND -- the event never waits, the hook can never allow or deny anything, and
+     * what it later says (`systemMessage`, `additionalContext`) reaches the model at the next safe point as
+     * a reminder. Refused (the hook stays synchronous, and the refusal is reported) on a fail-closed
+     * PreToolUse/PermissionRequest hook. Only a literal `true`.
+     */
+    async?: boolean;
 }
 export interface SettingsHookMatcherGroup {
     matcher?: string;
     hooks?: SettingsHookHandler[];
+    /** WS-23: `failClosed` for every handler in the group. */
+    failClosed?: boolean;
 }
 /** Open-keyed for the same reason RuntimeHooksConfig is (protocol/config.ts): unknown event names are accepted, preserved and inert. */
 export type SettingsHooksConfig = Partial<Record<string, SettingsHookMatcherGroup[]>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanlinglabs/winter-agent-sdk",
-  "version": "0.0.24",
+  "version": "0.0.28",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,15 +45,15 @@
     }
   },
   "dependencies": {
-    "@yanlinglabs/winter-provider-catalog": "0.0.24"
+    "@yanlinglabs/winter-provider-catalog": "0.0.28"
   },
   "optionalDependencies": {
-    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.24"
+    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.28"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
-    "winter-agent-runtime": "0.0.24",
-    "@yanlinglabs/winter-conformance": "0.0.24"
+    "@yanlinglabs/winter-agent-runtime": "0.0.28",
+    "@yanlinglabs/winter-conformance": "0.0.28"
   },
   "scripts": {}
 }