@yanlinglabs/winter-agent-sdk 0.0.15 → 0.0.16

package/README.md

@@ -68,6 +68,57 @@ plus two canonical standing-server twins, and `@yanlinglabs/winter-runtime-sdk`
 definitions under Claude's built-in names. Handlers return `{ text, isError? }` for each host to
 wrap in its own result shape.
 
+## Environment variables and settings
+
+The runtime child reads a handful of environment variables at spawn/per-turn, plus a few
+`Options`/`RuntimeConfig` fields. Every variable name below is `WINTER_`-prefixed for Winter's own
+build (`BrandProfile.envPrefix`); a rebranded host reads the identical suffix under its own prefix.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `WINTER_DISABLE_BACKGROUND_TASKS` | off | A hard kill switch with two effects together: it drops `run_in_background` from the Agent tool's own advertised schema entirely, and it forces every subagent spawn to the foreground unconditionally (outranking a definition's own `background: true`, a fork, and an explicit `run_in_background: true` alike). |
+| `WINTER_BACKGROUND_BY_DEFAULT` | on (background) | A softer opt-out than the kill switch above: a falsy value (`0`/`false`/`no`/`off`, case-insensitive) restores the pre-0.0.16 default (an unflagged spawn runs in the FOREGROUND) without removing `run_in_background` from the schema — the model can still ask for either explicitly either way. `Options.backgroundByDefault` (see below) wins over this variable in either direction when both are set. |
+| `WINTER_PRINT_BG_WAIT_CEILING_MS` | `600000` (10 minutes) | How long a closed-input session holds its result for a still-running background agent/workflow before sweeping it as stopped. `0` waits indefinitely. |
+| `WINTER_EMIT_SESSION_STATE_EVENTS` | off | Truthy (`1`/`true`) emits `system/session_state_changed` frames (`running`/`idle`) as a turn starts and ends. Absent, the frame stream is unchanged from before this existed. |
+| `WINTER_DISABLE_GIT_INSTRUCTIONS` | off | Truthy disables the git status/instructions section of the system prompt outright, overriding `Settings.includeGitInstructions` in either direction. A falsy value (`0`/`false`/`no`/`off`) explicitly re-enables it even when the setting says otherwise. |
+| `WINTER_DISABLE_EXPLORE_INHERIT_CAP` | off | Truthy opts a first-party Anthropic session out of the Explore built-in's own model cap (which otherwise caps a Fable-tier session's Explore spawn down to Opus). |
+| `WINTER_FORK_SUBAGENT` | off | Truthy enables `subagent_type: "fork"` for the session (mirrors `CLAUDE_CODE_FORK_SUBAGENT`). `Options.forkSubagent` (below) wins over this variable in either direction. |
+| `WINTER_WEB_FETCH_AGENT` | off | Truthy makes the `web-fetch` built-in agent type available (off by default, like claude's own). |
+| `WINTER_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | off | Truthy withholds every built-in `subagent_type` (gated or not) for the session. |
+| `WINTER_DISABLE_EXPLORE_PLAN_AGENTS` | off | Truthy withholds the `Explore` and `Plan` built-ins together. |
+| `WINTER_DISABLE_AGENT_VIEW` | off | Truthy withholds the `claude` catch-all built-in (mirrors `CLAUDE_CODE_DISABLE_AGENT_VIEW`). |
+| `WINTER_MAX_SUBAGENT_SPAWN_DEPTH` | `3` | How many levels of subagent nesting are allowed beneath the top-level session before a spawn is refused. |
+| `WINTER_MAX_CONCURRENT_SUBAGENTS` | `20` | How many subagents may run at once (across the whole nesting tree) before a spawn is refused. |
+
+A handful of `Options`/settings fields carry the same weight as their env counterparts, and a
+RuntimeConfig field always wins over its own env fallback in either direction when both are set:
+
+- **`Settings.includeGitInstructions`** (default `true`) — the setting `WINTER_DISABLE_GIT_INSTRUCTIONS` overrides above.
+- **`Options.forkSubagent`** (`boolean`, default unset → env fallback) — the RuntimeConfig field behind `WINTER_FORK_SUBAGENT`.
+- **`Options.backgroundByDefault`** (`boolean`, default unset → env fallback) — the RuntimeConfig field behind `WINTER_BACKGROUND_BY_DEFAULT`, above.
+
+`RuntimeConfig.allowedAgentTypes` (`string[]`) is a different shape of field, not a host-settable
+one: there is no `Options.allowedAgentTypes` and no env fallback to win over. It exists only on the
+wire `RuntimeConfig`, and the engine — never a host — populates it: when a running agent's own
+definition restricts `tools` with an `Agent(a, b)` entry, `allowedAgentTypesFromTools` parses that
+restriction and threads the resulting list onto the CHILD it spawns for that agent's own
+`RuntimeConfig`, so the child's listing / `init.agents` / Agent-tool resolution sees only `[a, b]`,
+never the full universe of types its parent session could otherwise reach. Absent (every top-level
+session, and any child whose parent definition named no `Agent(...)` restriction) means
+unrestricted, the behavior every session had before this field existed.
+
+### The 0.0.16 background-default change
+
+Before 0.0.16, an Agent tool call with no `run_in_background` ran in the **foreground** (this call
+does not return until the spawned agent finishes). From 0.0.16 on, matching claude, the same
+unflagged call runs in the **background** by default: the call returns immediately with a task id,
+and the model is told about the result later as a task notification (mid-turn, or as its own
+unsolicited turn). `run_in_background: false` still asks for the old, synchronous behavior on any
+one call. A host that wants the *default* itself to stay foreground — without losing the
+`run_in_background` field or forcing every call to name it explicitly — sets
+`Options.backgroundByDefault: false` (or `WINTER_BACKGROUND_BY_DEFAULT=false`); the kill switch,
+`WINTER_DISABLE_BACKGROUND_TASKS`, is unrelated and unaffected by this knob in either direction.
+
 ## License
 
 MIT — see [`LICENSE`](./LICENSE), which ships in the published tarball.

package/dist/index.d.ts

@@ -24,7 +24,7 @@ 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, 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 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, SDKSessionStateChangedMessage, 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";

package/dist/index.js

@@ -579,6 +579,7 @@ function query(args) {
     ...options.agents !== undefined ? { agents: options.agents } : {},
     ...options.forwardSubagentText !== undefined ? { forwardSubagentText: options.forwardSubagentText } : {},
     ...options.forkSubagent !== undefined ? { forkSubagent: options.forkSubagent } : {},
+    ...options.backgroundByDefault !== undefined ? { backgroundByDefault: options.backgroundByDefault } : {},
     ...options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {},
     ...options.plugins !== undefined ? { plugins: options.plugins } : {},
     ...options.skills !== undefined ? { skills: options.skills } : {},
@@ -966,7 +967,7 @@ function query(args) {
   return gen;
 }
 // src/version.ts
-var SDK_VERSION = "0.0.15";
+var SDK_VERSION = "0.0.16";
 // 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

@@ -103,6 +103,21 @@ export interface Options {
      * `CLAUDE_CODE_FORK_SUBAGENT`), and is off when that is unset.
      */
     forkSubagent?: boolean;
+    /**
+     * I4 (fix wave): a programmatic opt-out for the Agent tool's own background default (SDK 0.0.16,
+     * `subagents/policy.ts`'s `resolveForegroundBackground` -- "background unless `run_in_background`
+     * is explicitly false"). `false` restores the 0.0.15 default (foreground) for every spawn this
+     * knob's stage of the chain decides; `true` is the 0.0.16 default, spelled out. Omitted = the
+     * runtime reads `WINTER_BACKGROUND_BY_DEFAULT` (falsy -- "0"/"false"/"no"/"off" -- restores
+     * foreground; anything else, including absent, keeps background), the SAME `forkSubagent`
+     * precedent: the field wins in either direction, the env is only the fallback.
+     *
+     * Distinct from `WINTER_DISABLE_BACKGROUND_TASKS` (which keeps its own, unrelated meaning -- a
+     * hard kill switch that ALSO removes `run_in_background` from the advertised schema entirely):
+     * this knob changes only which way an OMITTED `run_in_background` resolves, and the field stays
+     * on the schema either way.
+     */
+    backgroundByDefault?: boolean;
     onElicitation?: (request: {
         serverName: string;
         message: string;

package/dist/protocol/config.d.ts

@@ -197,6 +197,14 @@ export interface RuntimeAgentDefinition {
      * every pre-existing definition's context, unchanged.
      */
     omitProjectContext?: boolean;
+    /**
+     * SDK 0.0.16 Lane P (R3b §5): claude's `whenToUseLean` -- used in place of `description` in the
+     * Agent-tool listing when the session's own model takes the lean prompt (`leanModel`, computed
+     * by `context/agent-listing.ts`'s own caller). Set only on Winter's built-in Explore; every other
+     * definition (Winter's own, or a filesystem/programmatic one) has none, and the listing falls
+     * back to `description` exactly as it always has.
+     */
+    whenToUseLean?: string;
 }
 export interface RuntimeConfig {
     sessionId: string;
@@ -240,6 +248,16 @@ export interface RuntimeConfig {
     toolAliases?: Record<string, string>;
     agents?: Record<string, RuntimeAgentDefinition>;
     forwardSubagentText?: boolean;
+    /**
+     * SDK 0.0.16 Lane P (R3b §4): the RUNNING agent's own `Agent(a, b)` restriction, parsed from its
+     * `AgentDefinition.tools` entries by `subagents/definitions.ts`'s own `allowedAgentTypesFromTools`
+     * and threaded onto a CHILD's own RuntimeConfig at spawn (`child-engine.ts`) -- so a session
+     * spawned from a definition with `tools: ["*", "Agent(Explore, Plan)"]` sees only [Explore, Plan]
+     * in ITS OWN listing / `init.agents` / Agent-tool resolution, never the full universe of types
+     * this session could otherwise reach. Absent = unrestricted, the pre-existing behaviour every
+     * session before this field existed keeps. Pure passthrough; query.ts never interprets it.
+     */
+    allowedAgentTypes?: string[];
     agentId?: string;
     isolationPinnedCwd?: boolean;
     /**
@@ -254,6 +272,13 @@ export interface RuntimeConfig {
      * a forked worker may not fork again (claude's own refusal). Never set by `query()`.
      */
     insideFork?: boolean;
+    /**
+     * I4 (fix wave): mirrors `Options.backgroundByDefault` exactly -- see that field's own comment.
+     * `subagents/policy.ts`'s `resolveForegroundBackground` reads it at its own stage 5, AFTER the
+     * `WINTER_DISABLE_BACKGROUND_TASKS` kill switch (stage 2, unrelated and unaffected) and the
+     * invocation's own explicit `run_in_background` (stage 4, always wins when given).
+     */
+    backgroundByDefault?: boolean;
     systemPrompt?: SystemPromptOption;
     plugins?: SdkPluginConfig[];
     skills?: SkillsOption;

package/dist/protocol/frames.d.ts

@@ -544,6 +544,24 @@ export interface SDKContinuityWarningMessage {
     uuid: string;
     session_id: string;
 }
+/**
+ * SDK 0.0.16 Lane N: `notifySessionStateChanged` (pinned `sdk.d.ts`: "Mirrors notifySessionStateChanged.
+ * 'idle' fires after heldBackResult flushes and the bg-agent do-while exits -- authoritative turn-over
+ * signal"). ENV-GATED on both runtimes: the pinned binary emits it only under
+ * `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS`, Winter only under `WINTER_EMIT_SESSION_STATE_EVENTS`, so a
+ * default session's frame stream is byte-identical with or without this variant existing.
+ *
+ * `requires_action` is declared (it is in the pinned union) but has no Winter producer: Winter's
+ * approval prompts ride `control_request`, not a session-state transition.
+ */
+export interface SDKSessionStateChangedMessage {
+    type: "system";
+    subtype: "session_state_changed";
+    state: "idle" | "running" | "requires_action";
+    uuid: string;
+    session_id: string;
+    [k: string]: unknown;
+}
 export type SdkMessage = {
     type: "system";
     subtype: "init";
@@ -568,7 +586,7 @@ export type SdkMessage = {
      */
     agents?: string[];
     [k: string]: unknown;
-} | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPermissionDeniedMessage | SDKStatusMessage | SDKCompactBoundaryMessage | BackgroundTaskMessage | SDKPartialAssistantMessage | SDKAPIRetryMessage | SDKRateLimitEvent | SDKAuthStatusMessage | SDKThinkingTokensMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKReasoningSummaryMessage | SDKModelSwitchMessage | SDKContinuityWarningMessage | {
+} | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPermissionDeniedMessage | SDKStatusMessage | SDKCompactBoundaryMessage | SDKSessionStateChangedMessage | BackgroundTaskMessage | SDKPartialAssistantMessage | SDKAPIRetryMessage | SDKRateLimitEvent | SDKAuthStatusMessage | SDKThinkingTokensMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKReasoningSummaryMessage | SDKModelSwitchMessage | SDKContinuityWarningMessage | {
     type: "assistant";
     message: {
         content: Array<{

package/dist/settings/types.d.ts

@@ -76,6 +76,11 @@ export interface Settings {
     skillListingMaxDescChars?: number;
     /** `sdk.d.ts:5503`. The listing's share of the context window (default 0.01). */
     skillListingBudgetFraction?: number;
+    /**
+     * `sdk.d.ts:5539`. SDK 0.0.16: whether the systemContext `gitStatus` snapshot is sent (default
+     * true). `<PREFIX>DISABLE_GIT_INSTRUCTIONS` overrides it either way.
+     */
+    includeGitInstructions?: boolean;
     /**
      * A settings-tier MCP server block. Deliberately `Record<string, unknown>` rather than a typed
      * server union: `settings/loaders/mcp-config.ts` validates each entry and `resolveMcpServerSources`

package/package.json

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