@yanlinglabs/winter-agent-sdk 0.0.32 → 0.0.34

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { Query, SdkMessage, SessionMessagingFacet } 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, MCP_OAUTH_REFRESH_SUBTYPE, CREDENTIAL_RESOLVE_SUBTYPE } from "./options.js";
+export { DEFAULT_PROVIDER_STALL_TIMEOUT_MS, DEFAULT_KEYCHAIN_SERVICE, TEST_KEYCHAIN_ENV, TEST_KEYCHAIN_MEMORY, MCP_OAUTH_REFRESH_SUBTYPE, CREDENTIAL_RESOLVE_SUBTYPE } from "./options.js";
 export { WEB_TOOLS_DEFAULTS, resolveWebToolsConfig } from "./options.js";
 export type { ResolvedWebToolsConfig } from "./options.js";
 export type { WebToolsConfig, WebSearchConfig, WebFetchConfig, WebPrivateAddressPolicy, AutoMemoryConfig } from "./protocol/config.js";
@@ -50,9 +50,9 @@ export type { SettingSource, ResolvedSettingSource, PolicySettingsOrigin, Settin
 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 type { CanUseTool, McpServerIdentity, PermissionResult, PermissionDecisionClassification, PermissionRequestPayload } from "./permissions/types.js";
 export { HOOK_EVENTS } 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 type { HookEvent, HookEventName, HookSource, HookPermissionDecision, BaseHookInput, McpToolProvenance, WinterMcpServerHookField, 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

@@ -66,6 +66,8 @@ var DEFAULT_PLANS_DIRECTORY = `${WINTER_BRAND2.projectDirName}/plans`;
 var DEFAULT_OUTPUT_STYLE = "default";
 var DEFAULT_PROVIDER_STALL_TIMEOUT_MS = 120000;
 var DEFAULT_KEYCHAIN_SERVICE = WINTER_BRAND2.keychainService;
+var TEST_KEYCHAIN_ENV = "WINTER_TEST_KEYCHAIN";
+var TEST_KEYCHAIN_MEMORY = "memory";
 var MCP_OAUTH_REFRESH_SUBTYPE = "mcp_oauth_refresh";
 var CREDENTIAL_RESOLVE_SUBTYPE = "credential_resolve";
 var WEB_TOOLS_DEFAULTS = {
@@ -448,13 +450,17 @@ function makeSdkMcpCallHandler(mcpServers) {
   };
 }
 function makeElicitationHandler(onElicitation, abortController) {
-  return async (payload) => {
+  return async (payload, handlerCtx) => {
     const req = payload;
     const controller = new AbortController;
     if (abortController?.signal.aborted)
       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 });
     let result;
     try {
       result = await onElicitation({
@@ -565,6 +571,9 @@ function buildRuntimeHooksConfig(hooks) {
   }
   return Object.keys(out).length > 0 ? out : undefined;
 }
+function winterMcpServerHookField(server) {
+  return { name: server.name, config_name: server.configName, ...server.readOnlyHint !== undefined ? { read_only_hint: server.readOnlyHint } : {} };
+}
 function buildHookInput(req, cwd) {
   const payload = req.payload ?? {};
   return {
@@ -576,6 +585,7 @@ function buildHookInput(req, cwd) {
     ...req.toolName !== undefined ? { tool_name: req.toolName } : {},
     ...req.mcpServerName !== undefined ? { mcp_server_name: req.mcpServerName } : {},
     ...req.mcpToolName !== undefined ? { mcp_tool_name: req.mcpToolName } : {},
+    ...req.mcpServer !== undefined ? { winter_mcp_server: winterMcpServerHookField(req.mcpServer) } : {},
     ...req.input !== undefined ? { tool_input: req.input } : {},
     ...req.toolUseID !== undefined ? { tool_use_id: req.toolUseID } : {},
     ...payload
@@ -722,7 +732,7 @@ function query(args) {
     command,
     args: ["--run", "--config-json", JSON.stringify(config)],
     cwd: config.cwd,
-    env: options.env ?? process.env,
+    env: withTestKeychainRedirect(options.env) ?? process.env,
     ...options.abortController ? { signal: options.abortController.signal } : {}
   };
   const proc = (options.spawnClaudeCodeProcess ?? defaultSpawn)(spawnOptions);
@@ -810,7 +820,8 @@ function query(args) {
           toolUseID: req.toolUseID,
           ...req.agentID !== undefined ? { agentID: req.agentID } : {},
           requestId: req.requestId,
-          ...req.matchedAskRule !== undefined ? { matchedAskRule: req.matchedAskRule } : {}
+          ...req.matchedAskRule !== undefined ? { matchedAskRule: req.matchedAskRule } : {},
+          ...req.mcpServer !== undefined ? { mcpServer: req.mcpServer } : {}
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -1118,8 +1129,14 @@ function query(args) {
   };
   return gen;
 }
+function withTestKeychainRedirect(env) {
+  const redirect = process.env[TEST_KEYCHAIN_ENV];
+  if (env === undefined || redirect === undefined || redirect === "" || env[TEST_KEYCHAIN_ENV] !== undefined)
+    return env;
+  return { ...env, [TEST_KEYCHAIN_ENV]: redirect };
+}
 // src/version.ts
-var SDK_VERSION = "0.0.32";
+var SDK_VERSION = "0.0.34";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
@@ -2314,6 +2331,8 @@ export {
   SETTING_SOURCES,
   SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
   SessionNotFoundError,
+  TEST_KEYCHAIN_ENV,
+  TEST_KEYCHAIN_MEMORY,
   TRANSCRIPT_PROJECT_KEY_MAX_LENGTH,
   WEB_TOOLS_DEFAULTS,
   WINTER_BRAND2 as WINTER_BRAND,

package/dist/options.d.ts

@@ -15,6 +15,28 @@ export declare const DEFAULT_PLANS_DIRECTORY: string;
 export declare const DEFAULT_OUTPUT_STYLE = "default";
 export declare const DEFAULT_PROVIDER_STALL_TIMEOUT_MS = 120000;
 export declare const DEFAULT_KEYCHAIN_SERVICE: string;
+/**
+ * TEST-ONLY. The environment variable that redirects every DEFAULT secrets backend (the runtime's
+ * `provider/keychain-store.ts`, the one site that may reach the macOS Keychain) to a per-process
+ * in-memory store. Exactly `TEST_KEYCHAIN_MEMORY` enables the redirect; unset or empty leaves the real
+ * Keychain; any other value is REFUSED (a typed `io` credential error, which stops the store stack),
+ * never a silent fall through to the real store or to "no credential". The first time the in-memory
+ * store engages, the process prints one stderr line saying so.
+ *
+ * WHY. A test that resolves a `{ kind: "keychain" }` ref in a process that was handed no store of its
+ * own (a real `winter` child, an embedded Worker) reached the developer's REAL login Keychain -- service
+ * `DEFAULT_KEYCHAIN_SERVICE` by default -- and macOS raised a consent dialog, which also hung the child. Every
+ * `bun test` run sets this through `scripts/test-keychain-guard.ts` (each package's `bunfig.toml`), and
+ * `query()` carries it into the child's environment even when a host supplies an explicit `env`.
+ *
+ * Honoured by a compiled binary too, deliberately: the compiled legs of the test suite run the
+ * release-shaped artifact, and a build that ignored the variable would put exactly those legs back on
+ * the real Keychain. Left on by accident it fails CLOSED -- credentials read as absent, writes vanish
+ * with the process -- and it exposes nothing. Never set it outside a test run.
+ */
+export declare const TEST_KEYCHAIN_ENV = "WINTER_TEST_KEYCHAIN";
+/** The one value of `TEST_KEYCHAIN_ENV` that selects the in-memory backend. */
+export declare const TEST_KEYCHAIN_MEMORY = "memory";
 /**
  * WS-25 (MCP OAuth): the runtime -> host control subtype a session sends when a stored MCP sign-in needs
  * refreshing (`McpOAuthRefreshRequest` -> `McpOAuthRefreshAnswer`, protocol/config.ts). Spelled once:

package/dist/permissions/types.d.ts

@@ -34,6 +34,31 @@ export type PermissionUpdate = {
 };
 export type PermissionUpdateDestination = "userSettings" | "projectSettings" | "localSettings" | "session" | "cliArg";
 export type RuleSource = "managed" | "user" | "project" | "local" | "cliArg" | "session" | "sdk";
+/**
+ * WS-27 (Winter-only): WHICH MCP SERVER a tool call is for, stated exactly by the runtime -- on
+ * `canUseTool`'s options as `mcpServer`, and on the PreToolUse / PostToolUse / PostToolUseFailure hook
+ * input as `winter_mcp_server` (`WinterMcpServerHookField`, the same facts in snake_case). Present when
+ * the tool belongs to a connected MCP server (a stdio/http/sse server, or a host's in-process `sdk` one);
+ * absent for every other tool, and on an older runtime -- a host keeps its own resolver as the fallback.
+ *
+ * - `name`: the server's name as it appears in the tool name `mcp__<name>__<tool>` -- AFTER any rename.
+ *   A subagent definition's inline server that collides with a name already in use is connected under a
+ *   fresh one (`cf` -> `cf_2`); `name` is then `cf_2`.
+ * - `configName`: the key the server had in the config it came from, BEFORE any rename (`cf` above);
+ *   equal to `name` when nothing was renamed. For a plugin's server, the raw name its `.mcp.json` (or
+ *   manifest) declares -- the runtime registers plugin servers under exactly that name.
+ * - `readOnlyHint`: the tool's own `annotations.readOnlyHint` from that server's `tools/list`, only when
+ *   the server states it as a boolean. Absent means "not stated", never "false".
+ *
+ * Why the runtime states it: `mcp__<server>__<tool>` cannot be split reliably (a server name may contain
+ * `__`), a rename is invisible in the tool name, and the annotation lives only on the runtime's side of
+ * the wire.
+ */
+export interface McpServerIdentity {
+    name: string;
+    configName: string;
+    readOnlyHint?: boolean;
+}
 export type CanUseTool = (toolName: string, input: Record<string, unknown>, options: {
     signal: AbortSignal;
     suggestions?: PermissionUpdate[];
@@ -50,6 +75,8 @@ export type CanUseTool = (toolName: string, input: Record<string, unknown>, opti
         toolName: string;
         ruleContent?: string;
     };
+    /** WS-27, Winter-only: the MCP server this tool belongs to -- see `McpServerIdentity`. */
+    mcpServer?: McpServerIdentity;
 }) => Promise<PermissionResult | null>;
 export type PermissionDecisionClassification = "user_temporary" | "user_permanent" | "user_reject";
 export type PermissionResult = {
@@ -82,6 +109,8 @@ export interface PermissionRequestPayload {
         toolName: string;
         ruleContent?: string;
     };
+    /** WS-27: forwarded to `canUseTool` verbatim -- see `McpServerIdentity`. */
+    mcpServer?: McpServerIdentity;
     policyVersion: number;
 }
 export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "UserPromptSubmit", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PermissionRequest", "Notification", "PostToolBatch", "UserPromptExpansion", "MessageDisplay", "StopFailure", "PostCompact", "PermissionDenied", "SessionStart", "SessionEnd", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "InstructionsLoaded", "WorktreeCreate", "WorktreeRemove", "CwdChanged", "FileChanged", "DirectoryAdded"];
@@ -105,13 +134,23 @@ export interface McpToolProvenance {
     mcp_server_name?: string;
     mcp_tool_name?: string;
 }
-export interface PreToolUseHookInput extends BaseHookInput, McpToolProvenance {
+export interface WinterMcpServerHookField {
+    winter_mcp_server?: {
+        /** The server's name in the called tool's name `mcp__<name>__<tool>`, after any rename. */
+        name: string;
+        /** The server's key in the config it came from, before any rename (a plugin server: the raw name its `.mcp.json` declares). */
+        config_name: string;
+        /** The tool's own `annotations.readOnlyHint` from the server's `tools/list`, only when stated. */
+        read_only_hint?: boolean;
+    };
+}
+export interface PreToolUseHookInput extends BaseHookInput, McpToolProvenance, WinterMcpServerHookField {
     hook_event_name: "PreToolUse";
     tool_name: string;
     tool_input: unknown;
     tool_use_id: string;
 }
-export interface PostToolUseHookInput extends BaseHookInput, McpToolProvenance {
+export interface PostToolUseHookInput extends BaseHookInput, McpToolProvenance, WinterMcpServerHookField {
     hook_event_name: "PostToolUse";
     tool_name: string;
     tool_input: unknown;
@@ -119,7 +158,7 @@ export interface PostToolUseHookInput extends BaseHookInput, McpToolProvenance {
     tool_use_id: string;
     duration_ms?: number;
 }
-export interface PostToolUseFailureHookInput extends BaseHookInput, McpToolProvenance {
+export interface PostToolUseFailureHookInput extends BaseHookInput, McpToolProvenance, WinterMcpServerHookField {
     hook_event_name: "PostToolUseFailure";
     tool_name: string;
     tool_input: unknown;
@@ -302,6 +341,8 @@ export interface HookInvocationPayload {
     mcpServerName?: string;
     /** WS-24: for an MCP tool, the tool's own name on that server -- see `McpToolProvenance`. */
     mcpToolName?: string;
+    /** WS-27: PreToolUse/PostToolUse/PostToolUseFailure only -- becomes `winter_mcp_server`, see `McpServerIdentity`. */
+    mcpServer?: McpServerIdentity;
     input?: Record<string, unknown>;
     payload?: unknown;
     policyVersion: string;

package/package.json

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