@yanlinglabs/winter-agent-sdk 0.0.38 → 0.0.40

package/README.md

@@ -176,6 +176,34 @@ All three report the icon of each site they name to the HOST only, as `winter_si
 
 Subagents inherit both.
 
+### Messaging a host's other sessions (0.0.39)
+
+**`Options.hostMessaging`** — `{ send, list }`, for a host that runs many sessions (one process or one
+Worker each) and wants `SendMessage` and `ListAgents` to reach the others. With it set, `query()` puts
+`hostMessaging: true` on the wire and answers two runtime → host control requests,
+`host_message_send` and `host_message_list` (`HOST_MESSAGE_SEND_SUBTYPE` / `HOST_MESSAGE_LIST_SUBTYPE`),
+the same way for a spawned `winter` process and an embedded Worker:
+
+- `SendMessage` resolves `to` in-process first — the session's own subagents, then the in-process
+  peers. Only a `not_found` there goes to `send`, with the model's raw `to`, the message, its summary,
+  `notifyWhenIdle`, the runtime's message id and (for a subagent's call) `fromAgentId`. The host's
+  answer (`delivered`, `queued`, `resumed_and_delivered`, `refused`, `not_found`, `unavailable`,
+  `delivery_uncertain`, plus an optional `notify` fact and a one-sentence `note`) is the tool's
+  result under the runtime's message id, so a retry of the same tool call is answered from the
+  ledger and never asks the host twice. A throwing or malformed `send` is `delivery_uncertain`.
+- `ListAgents` lists the subagents, then the sessions `list` returns as `session` rows, ending with
+  a count of the ones the host left out (`omitted`) — a listing is never silently cut. A failing
+  `list` lists nothing more.
+- `TaskStop` with a `task_id` that names no task of this session goes to the optional `stop`
+  (`host_session_stop`): the host interrupts that session's running turn and answers `stopped`,
+  `not_running`, `refused`, `not_found` or `unavailable`.
+- The calling tool's abort signal travels with the request: an interrupted call cancels it
+  (`control_cancel_request`), and the handler's own `signal` aborts so the host can skip the delivery.
+
+The handler is per session and never told who is sending: it knows its caller by construction. The
+router core reaches the same seam through `MessagingRuntimeDeps.hostMessaging` (a `HostMessagingPort`
+per owning session, on the `/messaging` subpath). Without the option, nothing changes.
+
 ### 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

package/dist/{index-51ysrfm8.js → index-3zhkc4nb.js}

@@ -419,6 +419,138 @@ function facetNotificationKey2(sessionId) {
 function isReservedNotificationKey2(key) {
   return key.startsWith(RESERVED_NOTIFICATION_KEY_PREFIX2);
 }
+// src/messaging/host.ts
+var SEND_STATUSES = new Set(["delivered", "queued", "resumed_and_delivered", "refused", "not_found", "unavailable", "delivery_uncertain"]);
+var NEEDS_REASON = new Set(["refused", "not_found", "unavailable", "delivery_uncertain"]);
+var LISTED_STATUSES = new Set(["starting", "running", "idle", "exited", "unavailable", "archived"]);
+var HOST_MESSAGE_NOTE_MAX2 = 500;
+var HOST_MESSAGE_LIST_MAX2 = 200;
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isHostMessageSendRequest2(payload) {
+  if (!isRecord(payload))
+    return false;
+  return typeof payload.to === "string" && typeof payload.message === "string" && typeof payload.messageId === "string" && (payload.summary === undefined || typeof payload.summary === "string") && (payload.notifyWhenIdle === undefined || typeof payload.notifyWhenIdle === "boolean") && (payload.fromAgentId === undefined || typeof payload.fromAgentId === "string");
+}
+function isHostMessageListRequest2(payload) {
+  if (payload === undefined)
+    return true;
+  return isRecord(payload) && (payload.fromAgentId === undefined || typeof payload.fromAgentId === "string");
+}
+function isHostSessionStopRequest2(payload) {
+  return isRecord(payload) && typeof payload.id === "string" && (payload.fromAgentId === undefined || typeof payload.fromAgentId === "string");
+}
+var STOP_STATUSES = new Set(["stopped", "not_running", "refused", "not_found", "unavailable"]);
+var STOP_NEEDS_REASON = new Set(["refused", "not_found", "unavailable"]);
+function isHostSessionStopAnswer2(value) {
+  if (!isRecord(value))
+    return false;
+  if (typeof value.status !== "string" || !STOP_STATUSES.has(value.status))
+    return false;
+  if (value.reason !== undefined && typeof value.reason !== "string")
+    return false;
+  if (STOP_NEEDS_REASON.has(value.status) && (typeof value.reason !== "string" || value.reason.length === 0))
+    return false;
+  if (value.note !== undefined && typeof value.note !== "string")
+    return false;
+  return true;
+}
+function isHostMessageSendAnswer2(value) {
+  if (!isRecord(value))
+    return false;
+  if (typeof value.status !== "string" || !SEND_STATUSES.has(value.status))
+    return false;
+  if (value.reason !== undefined && typeof value.reason !== "string")
+    return false;
+  if (NEEDS_REASON.has(value.status) && (typeof value.reason !== "string" || value.reason.length === 0))
+    return false;
+  if (value.retryable !== undefined && typeof value.retryable !== "boolean")
+    return false;
+  if (value.note !== undefined && typeof value.note !== "string")
+    return false;
+  if (value.notify !== undefined) {
+    if (!isRecord(value.notify))
+      return false;
+    if (value.notify.subscribed !== undefined && value.notify.subscribed !== true)
+      return false;
+    if (value.notify.refused !== undefined && typeof value.notify.refused !== "string")
+      return false;
+  }
+  return true;
+}
+function isHostReachableSession(value) {
+  if (!isRecord(value))
+    return false;
+  if (typeof value.address !== "string" || !validateToField2(value.address).ok)
+    return false;
+  if (value.name !== undefined && (typeof value.name !== "string" || value.name.includes(`
+`)))
+    return false;
+  if (typeof value.status !== "string" || !LISTED_STATUSES.has(value.status))
+    return false;
+  if (typeof value.mode !== "string")
+    return false;
+  if (value.cwd !== undefined && typeof value.cwd !== "string")
+    return false;
+  return true;
+}
+function normaliseHostMessageListAnswer2(value) {
+  if (!isRecord(value) || !Array.isArray(value.sessions))
+    return;
+  const valid = value.sessions.filter(isHostReachableSession);
+  const sessions = valid.slice(0, HOST_MESSAGE_LIST_MAX2);
+  const hostOmitted = typeof value.omitted === "number" && Number.isInteger(value.omitted) && value.omitted > 0 ? value.omitted : 0;
+  const omitted = hostOmitted + (valid.length - sessions.length);
+  return {
+    ...omitted > 0 ? { omitted } : {},
+    sessions: sessions.map((s) => ({
+      address: s.address,
+      ...s.name !== undefined ? { name: s.name } : {},
+      status: s.status,
+      mode: s.mode,
+      ...s.cwd !== undefined ? { cwd: s.cwd } : {}
+    }))
+  };
+}
+function hostSessionToListed2(row) {
+  const reachable = row.status !== "archived" && row.status !== "unavailable";
+  return {
+    address: row.address,
+    ...row.name !== undefined ? { name: row.name } : {},
+    objectKind: "session",
+    runtimeKind: "winter-agent",
+    status: row.status,
+    mode: row.mode,
+    ...row.cwd !== undefined ? { cwd: row.cwd } : {},
+    capabilities: { message: reachable, resume: reachable, notifyWhenIdle: false, reply: reachable }
+  };
+}
+function hostAnswerToOutcome2(messageId, answer) {
+  const reason = answer.reason ?? answer.status;
+  switch (answer.status) {
+    case "delivered":
+    case "queued":
+    case "resumed_and_delivered":
+      return { status: answer.status, messageId };
+    case "refused":
+      return { status: "refused", messageId, reason };
+    case "not_found":
+      return { status: "not_found", messageId, reason };
+    case "unavailable":
+      return { status: "unavailable", messageId, retryable: answer.retryable === true, reason };
+    case "delivery_uncertain":
+      return { status: "delivery_uncertain", messageId, deliveryMayHaveOccurred: true, reason };
+  }
+}
+function boundedHostNote2(note) {
+  if (note === undefined)
+    return;
+  const trimmed = note.trim();
+  if (trimmed.length === 0)
+    return;
+  return trimmed.length > HOST_MESSAGE_NOTE_MAX2 ? `${trimmed.slice(0, HOST_MESSAGE_NOTE_MAX2 - 1)}…` : trimmed;
+}
 // src/messaging/router.ts
 var MAX_TRACKED_MESSAGE_IDS2 = 1e4;
 function rememberBounded2(map, key, value, cap = MAX_TRACKED_MESSAGE_IDS2) {
@@ -484,15 +616,15 @@ var SUCCESS_CLASS_STATUSES = new Set(["delivered", "queued", "resumed_and_delive
 function outcomeReason(outcome) {
   return "reason" in outcome ? outcome.reason : outcome.status;
 }
-async function sendMessage2(deps, caller, input) {
+async function sendMessage2(deps, caller, input, opts = {}) {
   const now = deps.now();
   const messageId = deps.seam.allocateMessageId(caller.sessionId, caller.toolUseId);
   const existing = deps.seam.lookupOutcome(messageId);
   if (existing !== undefined)
     return { outcome: existing };
-  function settle(outcome, notify) {
+  function settle(outcome, notify, note) {
     deps.seam.recordOutcome(messageId, outcome);
-    return notify !== undefined ? { outcome, notify } : { outcome };
+    return { outcome, ...notify !== undefined ? { notify } : {}, ...note !== undefined ? { note } : {} };
   }
   const from = callerAddress2(caller);
   const fromKey = serializeRuntimeAddress2(from);
@@ -512,8 +644,12 @@ async function sendMessage2(deps, caller, input) {
   const reachable = await deps.adapter.listReachable({ parent: buildSessionAddress2(caller.sessionId) });
   const peers = reachable.filter((r) => r.objectKind === "session");
   const resolved = resolveTarget2({ to: input.to, callerParentSessionId: caller.sessionId, children: deps.seam.children(), peers });
-  if (resolved.kind === "not_found")
-    return settle(notFound2(messageId, resolved.message));
+  if (resolved.kind === "not_found") {
+    const host = deps.hostMessaging?.(caller.sessionId);
+    if (host === undefined)
+      return settle(notFound2(messageId, resolved.message));
+    return settle(...await askHost(host, messageId, caller, input, opts.signal));
+  }
   if (resolved.kind === "stale")
     return settle(refused2(messageId, resolved.message));
   if (resolved.kind === "ambiguous")
@@ -560,6 +696,25 @@ async function sendMessage2(deps, caller, input) {
   const idleOutcome = await deps.adapter.subscribeIdle(to, { messageId });
   return settle(bodyOutcome, idleOutcome.status === "subscribed" ? { subscribed: true } : { refused: outcomeReason(idleOutcome) });
 }
+async function askHost(host, messageId, caller, input, signal) {
+  let answer;
+  try {
+    answer = await host.send({
+      to: input.to,
+      message: input.message,
+      ...input.summary !== undefined ? { summary: input.summary } : {},
+      ...input.notify_when_idle !== undefined ? { notifyWhenIdle: input.notify_when_idle } : {},
+      messageId,
+      ...caller.agentId !== undefined ? { fromAgentId: caller.agentId } : {}
+    }, signal !== undefined ? { signal } : {});
+  } catch (err) {
+    return [deliveryUncertain2(messageId, `the host did not answer the delivery: ${describeThrow(err)}`)];
+  }
+  if (!isHostMessageSendAnswer2(answer))
+    return [deliveryUncertain2(messageId, "the host answered the delivery with a malformed outcome")];
+  const notify = answer.notify === undefined ? undefined : { ...answer.notify.subscribed === true ? { subscribed: true } : {}, ...answer.notify.refused !== undefined ? { refused: answer.notify.refused } : {} };
+  return [hostAnswerToOutcome2(messageId, answer), notify, boundedHostNote2(answer.note)];
+}
 function describeThrow(err) {
   return err instanceof Error ? err.message : String(err);
 }
@@ -593,12 +748,32 @@ function formatListing(rows) {
   }).join(`
 `);
 }
-async function listAgents2(deps, caller, _input) {
+function omittedLine(omitted) {
+  return `(${omitted} more reachable session${omitted === 1 ? "" : "s"} not listed)`;
+}
+async function listAgents2(deps, caller, _input, opts = {}) {
   const selfAddr = buildSessionAddress2(caller.sessionId);
   const selfKey = serializeRuntimeAddress2(selfAddr);
   const reachable = await deps.adapter.listReachable({ parent: selfAddr });
   const rows = reachable.filter((r) => r.address !== selfKey);
-  return { listing: formatListing(rows), rows };
+  const host = deps.hostMessaging?.(caller.sessionId);
+  let omitted = 0;
+  if (host !== undefined) {
+    const answer = normaliseHostMessageListAnswer2(await host.list({}, opts.signal !== undefined ? { signal: opts.signal } : {}).catch(() => {
+      return;
+    }));
+    omitted = answer?.omitted ?? 0;
+    const seen = new Set(rows.map((r) => r.address));
+    for (const row of answer?.sessions ?? []) {
+      if (seen.has(row.address) || row.address === selfKey)
+        continue;
+      seen.add(row.address);
+      rows.push(hostSessionToListed2(row));
+    }
+  }
+  const listing = omitted > 0 ? `${formatListing(rows)}
+${omittedLine(omitted)}` : formatListing(rows);
+  return { listing, rows, ...omitted > 0 ? { omitted } : {} };
 }
 function readNotifications2(deps, caller) {
   return deps.notifications.drain(caller.sessionId);
@@ -611,4 +786,4 @@ function createMessagingRouter2(deps) {
     readNotifications: (caller) => readNotifications2(deps, caller)
   };
 }
-export { serializeRuntimeAddress2, createFakeMessagingRouterSeam2, REFERENCE_RUNTIME_KIND2, validateToField2, buildSessionAddress2, buildChildAddress2, parseRuntimeAddress2, sameAddress2, MAX_GLOBAL_MESSAGE_SIZE2, DEFAULT_MESSAGE_TTL_MS2, MAX_HOP_COUNT2, RAPID_REPEAT_WINDOW_MS2, HELD_INBOX_CAP2, ACCEPTED_QUEUE_CAP2, DEFAULT_HOLD_EXPIRY_MS2, NOTIFY_IDLE_EXPIRY_MS2, messageExceedsMaxSize2, hopCountExceeded2, delivered2, queued2, resumedAndDelivered2, held2, subscribed2, deliveryUncertain2, refused2, ambiguous2, notFound2, unavailable2, createLoopGuard2, childToListedRuntimeObject2, resolveTarget2, classifyPermissionMode2, mapFromModeToPermissionClass2, defaultInboundResult2, resolveInboundDecision2, createMailbox2, buildDefaultHoldEntry2, buildExplicitHoldEntry2, isIdleSubscribeSenderAllowed2, isIdleSubscribeTargetAllowed2, createNotificationQueue2, createIdleSubscriptionStore2, AGENT_MESSAGE_TAG2, escapeAttributionText2, escapeAttributionAttribute2, RESERVED_NOTIFICATION_KEY_PREFIX2, facetNotificationKey2, isReservedNotificationKey2, MAX_TRACKED_MESSAGE_IDS2, rememberBounded2, createMessagingRouterSeam2, createSubscriberDirectory2, callerAddress2, sendMessage2, formatListing, listAgents2, readNotifications2, createMessagingRouter2 };
+export { serializeRuntimeAddress2, createFakeMessagingRouterSeam2, REFERENCE_RUNTIME_KIND2, validateToField2, buildSessionAddress2, buildChildAddress2, parseRuntimeAddress2, sameAddress2, HOST_MESSAGE_NOTE_MAX2, HOST_MESSAGE_LIST_MAX2, isHostMessageSendRequest2, isHostMessageListRequest2, isHostSessionStopRequest2, isHostSessionStopAnswer2, isHostMessageSendAnswer2, normaliseHostMessageListAnswer2, hostSessionToListed2, hostAnswerToOutcome2, boundedHostNote2, MAX_GLOBAL_MESSAGE_SIZE2, DEFAULT_MESSAGE_TTL_MS2, MAX_HOP_COUNT2, RAPID_REPEAT_WINDOW_MS2, HELD_INBOX_CAP2, ACCEPTED_QUEUE_CAP2, DEFAULT_HOLD_EXPIRY_MS2, NOTIFY_IDLE_EXPIRY_MS2, messageExceedsMaxSize2, hopCountExceeded2, delivered2, queued2, resumedAndDelivered2, held2, subscribed2, deliveryUncertain2, refused2, ambiguous2, notFound2, unavailable2, createLoopGuard2, childToListedRuntimeObject2, resolveTarget2, classifyPermissionMode2, mapFromModeToPermissionClass2, defaultInboundResult2, resolveInboundDecision2, createMailbox2, buildDefaultHoldEntry2, buildExplicitHoldEntry2, isIdleSubscribeSenderAllowed2, isIdleSubscribeTargetAllowed2, createNotificationQueue2, createIdleSubscriptionStore2, AGENT_MESSAGE_TAG2, escapeAttributionText2, escapeAttributionAttribute2, RESERVED_NOTIFICATION_KEY_PREFIX2, facetNotificationKey2, isReservedNotificationKey2, MAX_TRACKED_MESSAGE_IDS2, rememberBounded2, createMessagingRouterSeam2, createSubscriberDirectory2, callerAddress2, sendMessage2, formatListing, omittedLine, listAgents2, readNotifications2, createMessagingRouter2 };

package/dist/index.d.ts

@@ -3,7 +3,8 @@ 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, TEST_KEYCHAIN_ENV, TEST_KEYCHAIN_MEMORY, 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, HOST_MESSAGE_SEND_SUBTYPE, HOST_MESSAGE_LIST_SUBTYPE, HOST_SESSION_STOP_SUBTYPE } from "./options.js";
+export type { HostMessagingHandler } 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";
@@ -22,7 +23,7 @@ export type { SpawnedRuntimeProcess, SpawnRuntimeOptions, SpawnClaudeCodeProcess
 export type { RuntimeConfig, RuntimeHooksConfig, RuntimeHookMatcherGroup, SandboxSettingsConfig } from "./protocol/config.js";
 export type { McpServerConfigForProcessTransport, McpVersionNegotiation, AgentMcpServerSpec, RuntimeAgentDefinition } from "./protocol/config.js";
 export type { McpOAuthConfig, McpOAuthSecretRef, McpOAuthRefreshRequest, McpOAuthRefreshAnswer } from "./protocol/config.js";
-export type { CredentialResolveRequest, CredentialResolveAnswer } from "./protocol/config.js";
+export type { CredentialResolveRequest, CredentialResolveAnswer, HostMessageSendRequest, HostMessageSendAnswer, HostMessageListRequest, HostMessageListAnswer, HostReachableSession, HostSessionStopRequest, HostSessionStopAnswer } 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";

package/dist/index.js

@@ -16,10 +16,16 @@ import {
   WinterCompatibilitySessionStore2
 } from "./index-0xks1t4r.js";
 import {
+  isHostMessageSendRequest2,
+  isHostMessageListRequest2,
+  isHostSessionStopRequest2,
+  isHostSessionStopAnswer2,
+  isHostMessageSendAnswer2,
+  normaliseHostMessageListAnswer2,
   deliveryUncertain2,
   refused2,
   unavailable2
-} from "./index-51ysrfm8.js";
+} from "./index-3zhkc4nb.js";
 
 // src/query.ts
 import { randomUUID } from "node:crypto";
@@ -70,6 +76,9 @@ 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 HOST_MESSAGE_SEND_SUBTYPE = "host_message_send";
+var HOST_MESSAGE_LIST_SUBTYPE = "host_message_list";
+var HOST_SESSION_STOP_SUBTYPE = "host_session_stop";
 var WEB_TOOLS_DEFAULTS = {
   searchEnabled: true,
   maxSearchesPerCall: 8,
@@ -420,13 +429,15 @@ function toWireMcpServers(servers) {
       name: cfg.name,
       ...cfg.timeout !== undefined ? { timeout: cfg.timeout } : {},
       ...isWinterMcpServerInstance(cfg.instance) ? { tools: cfg.instance.listTools() } : {},
-      ...cfg.toolNames !== undefined ? { toolNames: { ...cfg.toolNames } } : {}
+      ...cfg.toolNames !== undefined ? { toolNames: { ...cfg.toolNames } } : {},
+      ...cfg.toolLanes !== undefined ? { toolLanes: { ...cfg.toolLanes } } : {}
     } : cfg;
   }
   return out;
 }
+var ANSWERED_AFTER_CANCEL = new Set(["sdk_mcp_call"]);
 function makeSdkMcpCallHandler(mcpServers) {
-  return async (payload) => {
+  return async (payload, handlerCtx) => {
     const req = payload;
     const cfg = req.server !== undefined ? mcpServers[req.server] : undefined;
     if (!cfg || cfg.type !== "sdk") {
@@ -442,7 +453,7 @@ function makeSdkMcpCallHandler(mcpServers) {
       };
     }
     try {
-      const result = await cfg.instance.callTool(req.tool ?? "", req.arguments ?? {});
+      const result = await cfg.instance.callTool(req.tool ?? "", req.arguments ?? {}, ...handlerCtx !== undefined ? [{ signal: handlerCtx.signal }] : []);
       return { ok: true, payload: result };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -551,6 +562,79 @@ function makeCredentialResolveHandler(onCredentialResolve, abortController) {
     }
   };
 }
+function abortableFor(abortController, handlerCtx) {
+  const controller = new AbortController;
+  const onAbort = () => controller.abort();
+  if (abortController?.signal.aborted === true || handlerCtx?.signal.aborted === true)
+    controller.abort();
+  abortController?.signal.addEventListener("abort", onAbort, { once: true });
+  handlerCtx?.signal.addEventListener("abort", onAbort, { once: true });
+  return {
+    controller,
+    dispose: () => {
+      abortController?.signal.removeEventListener("abort", onAbort);
+      handlerCtx?.signal.removeEventListener("abort", onAbort);
+    }
+  };
+}
+function makeHostMessageSendHandler(host, abortController) {
+  return async (payload, handlerCtx) => {
+    if (!isHostMessageSendRequest2(payload))
+      return { ok: false, error: { code: "invalid_payload", message: "host_message_send expects { to, message, messageId, summary?, notifyWhenIdle?, fromAgentId? }" } };
+    const { controller, dispose } = abortableFor(abortController, handlerCtx);
+    const request = {
+      to: payload.to,
+      message: payload.message,
+      messageId: payload.messageId,
+      ...payload.summary !== undefined ? { summary: payload.summary } : {},
+      ...payload.notifyWhenIdle !== undefined ? { notifyWhenIdle: payload.notifyWhenIdle } : {},
+      ...payload.fromAgentId !== undefined ? { fromAgentId: payload.fromAgentId } : {}
+    };
+    try {
+      const answer = await host.send(request, { signal: controller.signal });
+      return { ok: true, payload: isHostMessageSendAnswer2(answer) ? answer : { status: "delivery_uncertain", reason: "the host's message handler returned a malformed answer" } };
+    } catch (err) {
+      console.error(`winter: hostMessaging.send threw (${err instanceof Error ? err.name : "error"}) -- answering delivery_uncertain`);
+      return { ok: true, payload: { status: "delivery_uncertain", reason: "the host's message handler failed" } };
+    } finally {
+      dispose();
+    }
+  };
+}
+function makeHostMessageListHandler(host, abortController) {
+  return async (payload, handlerCtx) => {
+    if (!isHostMessageListRequest2(payload))
+      return { ok: false, error: { code: "invalid_payload", message: "host_message_list expects { fromAgentId? }" } };
+    const { controller, dispose } = abortableFor(abortController, handlerCtx);
+    try {
+      const answer = await host.list({ ...payload?.fromAgentId !== undefined ? { fromAgentId: payload.fromAgentId } : {} }, { signal: controller.signal });
+      return { ok: true, payload: normaliseHostMessageListAnswer2(answer) ?? { sessions: [] } };
+    } catch (err) {
+      console.error(`winter: hostMessaging.list threw (${err instanceof Error ? err.name : "error"}) -- answering an empty listing`);
+      return { ok: true, payload: { sessions: [] } };
+    } finally {
+      dispose();
+    }
+  };
+}
+function makeHostSessionStopHandler(host, abortController) {
+  return async (payload, handlerCtx) => {
+    if (!isHostSessionStopRequest2(payload))
+      return { ok: false, error: { code: "invalid_payload", message: "host_session_stop expects { id, fromAgentId? }" } };
+    if (host.stop === undefined)
+      return { ok: true, payload: { status: "not_found", reason: `no task or session "${payload.id}" is known` } };
+    const { controller, dispose } = abortableFor(abortController, handlerCtx);
+    try {
+      const answer = await host.stop({ id: payload.id, ...payload.fromAgentId !== undefined ? { fromAgentId: payload.fromAgentId } : {} }, { signal: controller.signal });
+      return { ok: true, payload: isHostSessionStopAnswer2(answer) ? answer : { status: "unavailable", reason: "the host's stop handler returned a malformed answer" } };
+    } catch (err) {
+      console.error(`winter: hostMessaging.stop threw (${err instanceof Error ? err.name : "error"}) -- answering unavailable`);
+      return { ok: true, payload: { status: "unavailable", reason: "the host's stop handler failed" } };
+    } finally {
+      dispose();
+    }
+  };
+}
 function buildRuntimeHooksConfig(hooks) {
   if (!hooks)
     return;
@@ -735,6 +819,7 @@ function query(args) {
     ...options.maxOutputTokens !== undefined ? { maxOutputTokens: options.maxOutputTokens } : {},
     ...brand.keychainService !== WINTER_BRAND2.keychainService || options.keychainService !== undefined ? { keychainService: brand.keychainService } : {},
     ...options.onCredentialResolve !== undefined ? { hostCredentials: true } : {},
+    ...options.hostMessaging !== undefined ? { hostMessaging: true } : {},
     ...options.autoClassifier !== undefined ? { autoClassifier: options.autoClassifier } : {},
     ...options.advisor !== undefined ? { advisor: options.advisor } : {},
     ...options.web !== undefined ? { web: options.web } : {},
@@ -812,7 +897,7 @@ function query(args) {
       incomingRequestAborts.set(cf.requestId, cancel);
       try {
         const result = await handler(cf.payload, { signal: cancel.signal });
-        if (cancel.signal.aborted)
+        if (cancel.signal.aborted && !ANSWERED_AFTER_CANCEL.has(cf.subtype))
           return;
         if (result.ok) {
           writeControlResponse({
@@ -825,7 +910,7 @@ function query(args) {
           writeControlResponse({ type: "control_response", requestId: cf.requestId, ok: false, error: result.error });
         }
       } catch (err) {
-        if (cancel.signal.aborted)
+        if (cancel.signal.aborted && !ANSWERED_AFTER_CANCEL.has(cf.subtype))
           return;
         const message = err instanceof Error ? err.message : String(err);
         writeControlResponse({ type: "control_response", requestId: cf.requestId, ok: false, error: { code: "handler_threw", message } });
@@ -897,6 +982,11 @@ function query(args) {
   if (options.onCredentialResolve) {
     controlRequestHandlers.set(CREDENTIAL_RESOLVE_SUBTYPE, makeCredentialResolveHandler(options.onCredentialResolve, options.abortController));
   }
+  if (options.hostMessaging) {
+    controlRequestHandlers.set(HOST_MESSAGE_SEND_SUBTYPE, makeHostMessageSendHandler(options.hostMessaging, options.abortController));
+    controlRequestHandlers.set(HOST_MESSAGE_LIST_SUBTYPE, makeHostMessageListHandler(options.hostMessaging, options.abortController));
+    controlRequestHandlers.set(HOST_SESSION_STOP_SUBTYPE, makeHostSessionStopHandler(options.hostMessaging, options.abortController));
+  }
   if (options.onMcpOAuthRefresh) {
     controlRequestHandlers.set(MCP_OAUTH_REFRESH_SUBTYPE, makeMcpOAuthRefreshHandler(options.onMcpOAuthRefresh, options.abortController));
   }
@@ -1180,7 +1270,7 @@ function withTestKeychainRedirect(env) {
   return { ...env, [TEST_KEYCHAIN_ENV]: redirect };
 }
 // src/version.ts
-var SDK_VERSION = "0.0.38";
+var SDK_VERSION = "0.0.40";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
@@ -2356,6 +2446,9 @@ export {
   ESCALATING_PERMISSION_MODES,
   FIRST_PARTY_ORIGINATORS2 as FIRST_PARTY_ORIGINATORS,
   HOOK_EVENTS,
+  HOST_MESSAGE_LIST_SUBTYPE,
+  HOST_MESSAGE_SEND_SUBTYPE,
+  HOST_SESSION_STOP_SUBTYPE,
   InvalidBrandError,
   MCP_OAUTH_REFRESH_SUBTYPE,
   MESSAGING_CONTROL_SUBTYPES,

package/dist/messaging/host.d.ts

@@ -0,0 +1,42 @@
+import type { HostMessageListAnswer, HostMessageListRequest, HostMessageSendAnswer, HostMessageSendRequest, HostReachableSession, HostSessionStopAnswer, HostSessionStopRequest } from "../protocol/config.js";
+import type { DeliveryOutcome, ListedRuntimeObject } from "./adapter.js";
+/**
+ * What the router core (and `TaskStop`) need from a host: `Options.hostMessaging`, already bound to one
+ * session. `signal` is the calling tool's own: an interrupted sender cancels the request, and the host
+ * is told (its handler's `signal` aborts) so it can avoid delivering.
+ */
+export interface HostMessagingPort {
+    send(request: HostMessageSendRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<HostMessageSendAnswer>;
+    list(request: HostMessageListRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<HostMessageListAnswer>;
+    stop(request: HostSessionStopRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<HostSessionStopAnswer>;
+}
+/** A host's sentence for the model is bounded: it is rendered into a tool result. */
+export declare const HOST_MESSAGE_NOTE_MAX = 500;
+/** A host listing is bounded: it is rendered into a tool result, one line per row. */
+export declare const HOST_MESSAGE_LIST_MAX = 200;
+/** The request shape, checked on the WRAPPER side before the host's callback sees it. */
+export declare function isHostMessageSendRequest(payload: unknown): payload is HostMessageSendRequest;
+export declare function isHostMessageListRequest(payload: unknown): payload is HostMessageListRequest;
+export declare function isHostSessionStopRequest(payload: unknown): payload is HostSessionStopRequest;
+/** A well-formed stop answer: a known status, a non-empty reason wherever one is required. */
+export declare function isHostSessionStopAnswer(value: unknown): value is HostSessionStopAnswer;
+/** A well-formed send answer: a known status, a reason wherever one is required, the optional facts typed. */
+export declare function isHostMessageSendAnswer(value: unknown): value is HostMessageSendAnswer;
+/**
+ * A list answer, normalised: every malformed row is DROPPED (one bad row must not hide the others, and
+ * an unaddressable row would advertise a target the model cannot name), and the listing is capped.
+ * `undefined` for an answer that is not a listing at all.
+ */
+export declare function normaliseHostMessageListAnswer(value: unknown): HostMessageListAnswer | undefined;
+/** A host's session row as a ListAgents row: always a `session` of the Winter runtime, never resumable "for free" or idle-notifiable unless the host says so through SendMessage itself. */
+export declare function hostSessionToListed(row: HostReachableSession): ListedRuntimeObject;
+/** The host's answer as the router's outcome, under the RUNTIME's message id. Assumes `isHostMessageSendAnswer`. */
+export declare function hostAnswerToOutcome(messageId: string, answer: HostMessageSendAnswer): DeliveryOutcome;
+/** A host note, cut to its bound (it is model-visible). Empty and absent read the same. */
+export declare function boundedHostNote(note: string | undefined): string | undefined;

package/dist/messaging/index.d.ts

@@ -11,5 +11,8 @@ export type { PermissionClassLabel, CrossSessionInbound, InboundDecisionParams,
 export { isIdleSubscribeSenderAllowed, isIdleSubscribeTargetAllowed, createNotificationQueue, createIdleSubscriptionStore, } from "./idle.js";
 export type { NotificationRecord, NotificationQueue, PendingIdleSubscription, IdleSubscriptionStore } from "./idle.js";
 export { AGENT_MESSAGE_TAG, RESERVED_NOTIFICATION_KEY_PREFIX, escapeAttributionText, escapeAttributionAttribute, facetNotificationKey, isReservedNotificationKey } from "./attribution.js";
+export { HOST_MESSAGE_NOTE_MAX, HOST_MESSAGE_LIST_MAX, isHostMessageSendRequest, isHostMessageListRequest, isHostMessageSendAnswer, isHostSessionStopRequest, isHostSessionStopAnswer, normaliseHostMessageListAnswer, hostSessionToListed, hostAnswerToOutcome, boundedHostNote, } from "./host.js";
+export type { HostMessagingPort } from "./host.js";
+export type { HostMessageSendRequest, HostMessageSendAnswer, HostMessageListRequest, HostMessageListAnswer, HostReachableSession, HostSessionStopRequest, HostSessionStopAnswer } from "../protocol/config.js";
 export { MAX_TRACKED_MESSAGE_IDS, rememberBounded, createMessagingRouterSeam, createSubscriberDirectory, callerAddress, sendMessage, listAgents, readNotifications, createMessagingRouter, } from "./router.js";
 export type { MessagingRouterSeamWithRoster, SubscriberDirectory, MessagingRuntimeDeps, CallerContext, SessionCallerContext, SendMessageInput, NotifyOutcome, SendMessageResult, ListAgentsInput, MessagingRouter, } from "./router.js";

package/dist/messaging/index.js

@@ -7,6 +7,17 @@ import {
   buildChildAddress2,
   parseRuntimeAddress2,
   sameAddress2,
+  HOST_MESSAGE_NOTE_MAX2,
+  HOST_MESSAGE_LIST_MAX2,
+  isHostMessageSendRequest2,
+  isHostMessageListRequest2,
+  isHostSessionStopRequest2,
+  isHostSessionStopAnswer2,
+  isHostMessageSendAnswer2,
+  normaliseHostMessageListAnswer2,
+  hostSessionToListed2,
+  hostAnswerToOutcome2,
+  boundedHostNote2,
   MAX_GLOBAL_MESSAGE_SIZE2,
   DEFAULT_MESSAGE_TTL_MS2,
   MAX_HOP_COUNT2,
@@ -56,13 +67,15 @@ import {
   listAgents2,
   readNotifications2,
   createMessagingRouter2
-} from "../index-51ysrfm8.js";
+} from "../index-3zhkc4nb.js";
 export {
   ACCEPTED_QUEUE_CAP2 as ACCEPTED_QUEUE_CAP,
   AGENT_MESSAGE_TAG2 as AGENT_MESSAGE_TAG,
   DEFAULT_HOLD_EXPIRY_MS2 as DEFAULT_HOLD_EXPIRY_MS,
   DEFAULT_MESSAGE_TTL_MS2 as DEFAULT_MESSAGE_TTL_MS,
   HELD_INBOX_CAP2 as HELD_INBOX_CAP,
+  HOST_MESSAGE_LIST_MAX2 as HOST_MESSAGE_LIST_MAX,
+  HOST_MESSAGE_NOTE_MAX2 as HOST_MESSAGE_NOTE_MAX,
   MAX_GLOBAL_MESSAGE_SIZE2 as MAX_GLOBAL_MESSAGE_SIZE,
   MAX_HOP_COUNT2 as MAX_HOP_COUNT,
   MAX_TRACKED_MESSAGE_IDS2 as MAX_TRACKED_MESSAGE_IDS,
@@ -71,6 +84,7 @@ export {
   REFERENCE_RUNTIME_KIND2 as REFERENCE_RUNTIME_KIND,
   RESERVED_NOTIFICATION_KEY_PREFIX2 as RESERVED_NOTIFICATION_KEY_PREFIX,
   ambiguous2 as ambiguous,
+  boundedHostNote2 as boundedHostNote,
   buildChildAddress2 as buildChildAddress,
   buildDefaultHoldEntry2 as buildDefaultHoldEntry,
   buildExplicitHoldEntry2 as buildExplicitHoldEntry,
@@ -94,12 +108,20 @@ export {
   facetNotificationKey2 as facetNotificationKey,
   held2 as held,
   hopCountExceeded2 as hopCountExceeded,
+  hostAnswerToOutcome2 as hostAnswerToOutcome,
+  hostSessionToListed2 as hostSessionToListed,
+  isHostMessageListRequest2 as isHostMessageListRequest,
+  isHostMessageSendAnswer2 as isHostMessageSendAnswer,
+  isHostMessageSendRequest2 as isHostMessageSendRequest,
+  isHostSessionStopAnswer2 as isHostSessionStopAnswer,
+  isHostSessionStopRequest2 as isHostSessionStopRequest,
   isIdleSubscribeSenderAllowed2 as isIdleSubscribeSenderAllowed,
   isIdleSubscribeTargetAllowed2 as isIdleSubscribeTargetAllowed,
   isReservedNotificationKey2 as isReservedNotificationKey,
   listAgents2 as listAgents,
   mapFromModeToPermissionClass2 as mapFromModeToPermissionClass,
   messageExceedsMaxSize2 as messageExceedsMaxSize,
+  normaliseHostMessageListAnswer2 as normaliseHostMessageListAnswer,
   notFound2 as notFound,
   parseRuntimeAddress2 as parseRuntimeAddress,
   queued2 as queued,

package/dist/messaging/router.d.ts

@@ -1,4 +1,5 @@
 import { type RuntimeAddress, type ListedRuntimeObject, type DeliveryOutcome, type RuntimeMessagingAdapter, type MessagingRouterSeam, type ChildLike } from "./adapter.js";
+import { type HostMessagingPort } from "./host.js";
 import type { NotificationQueue, NotificationRecord } from "./idle.js";
 import { type LoopGuard } from "./outcomes.js";
 export interface MessagingRouterSeamWithRoster extends MessagingRouterSeam {
@@ -34,6 +35,14 @@ export interface MessagingRuntimeDeps {
      * "everything is uncertain", which is exactly the conservative reading.
      */
     classifyDeliveryError?(err: unknown): "refused" | "uncertain";
+    /**
+     * Host messaging (`Options.hostMessaging`): the port to the HOST's other sessions for the OWNING
+     * session `owningSessionId` (a subagent's calls use its parent's, since they share the session id),
+     * or `undefined` when that session has none -- which is every session of a standalone SDK user, and
+     * every session of a host that composes this core itself (the router package). Consulted only after
+     * in-process resolution answered `not_found` (SendMessage) and to add rows (ListAgents).
+     */
+    hostMessaging?(owningSessionId: string): HostMessagingPort | undefined;
 }
 export interface CallerContext {
     sessionId: string;
@@ -57,8 +66,11 @@ export interface NotifyOutcome {
 export interface SendMessageResult {
     outcome: DeliveryOutcome;
     notify?: NotifyOutcome;
+    note?: string;
 }
-export declare function sendMessage(deps: MessagingRuntimeDeps, caller: CallerContext, input: SendMessageInput): Promise<SendMessageResult>;
+export declare function sendMessage(deps: MessagingRuntimeDeps, caller: CallerContext, input: SendMessageInput, opts?: {
+    signal?: AbortSignal;
+}): Promise<SendMessageResult>;
 export interface ListAgentsInput {
     channel?: string;
     q?: string;
@@ -76,9 +88,14 @@ export declare function formatListing(rows: readonly ListedRuntimeObject[]): str
 export interface SessionCallerContext {
     sessionId: string;
 }
-export declare function listAgents(deps: MessagingRuntimeDeps, caller: SessionCallerContext, _input: ListAgentsInput): Promise<{
+/** The line a listing ends with when the host left reachable sessions out (its cap), so nothing is silently cut. */
+export declare function omittedLine(omitted: number): string;
+export declare function listAgents(deps: MessagingRuntimeDeps, caller: SessionCallerContext, _input: ListAgentsInput, opts?: {
+    signal?: AbortSignal;
+}): Promise<{
     listing: string;
     rows: ListedRuntimeObject[];
+    omitted?: number;
 }>;
 export declare function readNotifications(deps: MessagingRuntimeDeps, caller: SessionCallerContext): {
     notifications: NotificationRecord[];
@@ -90,6 +107,7 @@ export interface MessagingRouter {
     listAgents(caller: SessionCallerContext, input: ListAgentsInput): Promise<{
         listing: string;
         rows: ListedRuntimeObject[];
+        omitted?: number;
     }>;
     readNotifications(caller: SessionCallerContext): {
         notifications: NotificationRecord[];

package/dist/options.d.ts

@@ -1,6 +1,6 @@
 import type { SpawnClaudeCodeProcess } from "./transport.js";
 import type { PermissionMode, CanUseTool, HookEvent, HookCallbackMatcher } from "./permissions/types.js";
-import type { SandboxSettingsConfig, McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, RuntimeAgentDefinition, SdkPluginConfig, SystemPromptOption, OutputFormat, SkillsOption, ProviderSelection, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig, WebToolsConfig, WebPrivateAddressPolicy, AutoMemoryConfig, CredentialRef, McpOAuthRefreshRequest, McpOAuthRefreshAnswer, CredentialResolveRequest, CredentialResolveAnswer } from "./protocol/config.js";
+import type { SandboxSettingsConfig, McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, RuntimeAgentDefinition, SdkPluginConfig, SystemPromptOption, OutputFormat, SkillsOption, ProviderSelection, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig, WebToolsConfig, WebPrivateAddressPolicy, AutoMemoryConfig, CredentialRef, McpOAuthRefreshRequest, McpOAuthRefreshAnswer, CredentialResolveRequest, CredentialResolveAnswer, HostMessageSendRequest, HostMessageSendAnswer, HostMessageListRequest, HostMessageListAnswer, HostSessionStopRequest, HostSessionStopAnswer } from "./protocol/config.js";
 import type { SettingSource } from "./settings/types.js";
 import type { SessionStore } from "./store/session-store.js";
 import { type BrandProfile } from "./brand.js";
@@ -45,6 +45,33 @@ export declare const TEST_KEYCHAIN_MEMORY = "memory";
 export declare const MCP_OAUTH_REFRESH_SUBTYPE = "mcp_oauth_refresh";
 /** WS-25 §7: the runtime -> host control subtype a host-brokered session resolves a Keychain credential with (`CredentialResolveRequest` -> `CredentialResolveAnswer`). */
 export declare const CREDENTIAL_RESOLVE_SUBTYPE = "credential_resolve";
+/** Host messaging: the runtime -> host control subtype `SendMessage` asks its host to deliver with (`HostMessageSendRequest` -> `HostMessageSendAnswer`). */
+export declare const HOST_MESSAGE_SEND_SUBTYPE = "host_message_send";
+/** Host messaging: the runtime -> host control subtype `ListAgents` asks its host what it can reach with (`HostMessageListRequest` -> `HostMessageListAnswer`). */
+export declare const HOST_MESSAGE_LIST_SUBTYPE = "host_message_list";
+/** Host messaging: the runtime -> host control subtype `TaskStop` asks its host to stop one of the host's sessions with (`HostSessionStopRequest` -> `HostSessionStopAnswer`). */
+export declare const HOST_SESSION_STOP_SUBTYPE = "host_session_stop";
+/**
+ * Host messaging, WINTER-ONLY: the handler a host that runs MANY sessions gives one session so its
+ * `SendMessage` and `ListAgents` reach the host's other sessions. See `Options.hostMessaging`.
+ */
+export interface HostMessagingHandler {
+    /** Deliver one message this session's `SendMessage` could not resolve in-process. Never throws for a policy answer -- refuse with a typed status. */
+    send(request: HostMessageSendRequest, options: {
+        signal: AbortSignal;
+    }): Promise<HostMessageSendAnswer>;
+    /** The sessions this session can reach through the host, for `ListAgents` (beside its own subagents). */
+    list(request: HostMessageListRequest, options: {
+        signal: AbortSignal;
+    }): Promise<HostMessageListAnswer>;
+    /**
+     * Stop (interrupt the running turn of) one of the host's sessions, for a `TaskStop` whose `task_id`
+     * names no task of this session. Optional: a host without it answers every such request `not_found`.
+     */
+    stop?(request: HostSessionStopRequest, options: {
+        signal: AbortSignal;
+    }): Promise<HostSessionStopAnswer>;
+}
 /**
  * Every web-tool default, spelled ONCE. A reader function resolves an absent field against this --
  * no consumer writes a literal of its own.
@@ -101,7 +128,16 @@ export interface WinterMcpServerInstance {
         };
         _meta?: Record<string, unknown>;
     }>;
-    callTool(name: string, args: Record<string, unknown>): Promise<{
+    /**
+     * `extra.signal` (SDK 0.0.40) is ABORTED when the runtime cancels the call (an interrupted turn sends
+     * `control_cancel_request`). A tool that holds an exclusive resource should stop promptly and then return:
+     * the runtime keeps the tool's concurrency lane held until this promise settles (or a bounded grace runs
+     * out), so the next call of that lane never overlaps a tool still running. Optional: an instance that
+     * ignores it behaves as before.
+     */
+    callTool(name: string, args: Record<string, unknown>, extra?: {
+        signal?: AbortSignal;
+    }): Promise<{
         content: unknown[];
         isError?: boolean;
     }>;
@@ -256,6 +292,29 @@ export interface Options {
     onCredentialResolve?: (request: CredentialResolveRequest, options: {
         signal: AbortSignal;
     }) => Promise<CredentialResolveAnswer>;
+    /**
+     * Host messaging, WINTER-ONLY: this session's line to the host's OTHER sessions. When set, `query()`
+     * puts `hostMessaging: true` on the wire and answers the runtime's `host_message_send` /
+     * `host_message_list` control requests with it -- identically for a spawned `winter` process and an
+     * embedded Worker, since both speak the same frame stream to this wrapper.
+     *
+     * - `SendMessage` resolves `to` in-process first (this session's subagents, then the in-process peer
+     *   directory). Only a `not_found` there is handed to `send`; a subagent, a self-target, a stale or an
+     *   ambiguous name never reaches the host. The host's typed answer is the tool's result, under the
+     *   runtime's own message id (so a retry of the same tool call short-circuits on the stored outcome).
+     * - `ListAgents` lists this session's subagents and then whatever `list` returns, as `session` rows
+     *   (with the host's `omitted` count, so nothing is silently cut).
+     * - `TaskStop` with a `task_id` that names no task of this session is handed to `stop` (when given):
+     *   the host interrupts that session's running turn.
+     *
+     * The handler is per session: it knows its caller by construction, and the request never names the
+     * sender (only `fromAgentId`, information about which subagent of THIS session asked). A throwing
+     * `send` answers `delivery_uncertain`; a throwing `list` lists nothing.
+     *
+     * Absent: `SendMessage` and `ListAgents` reach exactly what the session's own process holds, as before.
+     * Never serialized (a JS object of functions).
+     */
+    hostMessaging?: HostMessagingHandler;
     systemPrompt?: SystemPromptOption;
     plugins?: SdkPluginConfig[];
     skills?: SkillsOption;

package/dist/protocol/config.d.ts

@@ -231,6 +231,100 @@ export type CredentialResolveAnswer = {
     ok: false;
     reason: "not_found" | "not_allowed" | "stale" | "unavailable";
 };
+/**
+ * Host messaging, WINTER-ONLY: the runtime -> host `host_message_send` control request (subtype
+ * `HOST_MESSAGE_SEND_SUBTYPE`), sent only when `RuntimeConfig.hostMessaging` is set.
+ *
+ * WHY. A session's `SendMessage` resolves `to` against what its own process can reach: the session's
+ * subagents and the in-process peer directory, which holds the calling session alone. A HOST that runs
+ * many sessions (the Winter daemon: one process or one Worker per session) owns every other one, so the
+ * runtime asks it when -- and only when -- local resolution finds nothing (`not_found`). Subagents,
+ * self-target, a stale or ambiguous name are all still answered in-process and never reach the host.
+ *
+ * - `to` -- EXACTLY what the model wrote (a host session id, a `session:<id>` address from ListAgents,
+ *   a name the host recognises). Resolution is the host's.
+ * - `messageId` -- the runtime's own id for this call, stable across a retry of the same tool call (the
+ *   runtime's ledger short-circuits a retry before it ever asks again; the host MAY also dedupe on it).
+ * - `fromAgentId` -- set when one of this session's SUBAGENTS is the sender. Information only: the host
+ *   knows which session is asking from which session's handler answered, and must never take the sender
+ *   from the payload.
+ */
+export interface HostMessageSendRequest {
+    to: string;
+    message: string;
+    summary?: string;
+    notifyWhenIdle?: boolean;
+    messageId: string;
+    fromAgentId?: string;
+}
+/**
+ * The host's answer. `status` is one of the delivery outcomes a host can honestly report; the runtime
+ * stamps its own `messageId` on it and records it in its ledger.
+ *
+ * - `delivered` (the target is reading it now), `queued` (behind a turn already running),
+ *   `resumed_and_delivered` (the target was not running and the host resumed it for this message);
+ * - `refused` / `not_found` -- `reason` required; `unavailable` -- `reason` required, `retryable`
+ *   optional (default `false`); `delivery_uncertain` -- `reason` required (the effect may have happened).
+ *
+ * `notify` is the separate fact of whether `notifyWhenIdle` was honoured, rendered beside the outcome
+ * exactly like the in-process router's combined call. `note` is ONE short sentence for the model beside
+ * the outcome (e.g. whether it will be told when the target finishes) -- never a second outcome.
+ */
+export interface HostMessageSendAnswer {
+    status: "delivered" | "queued" | "resumed_and_delivered" | "refused" | "not_found" | "unavailable" | "delivery_uncertain";
+    reason?: string;
+    retryable?: boolean;
+    notify?: {
+        subscribed?: true;
+        refused?: string;
+    };
+    note?: string;
+}
+/** `host_message_list` (subtype `HOST_MESSAGE_LIST_SUBTYPE`): what this session can reach through its host, for `ListAgents`. */
+export interface HostMessageListRequest {
+    /** As on `HostMessageSendRequest`: set when a subagent is asking. Information only. */
+    fromAgentId?: string;
+}
+/**
+ * One session the host lists. `address` is what the model passes back as `to` (it must satisfy
+ * `SendMessage`'s own `to` rules: non-empty, at most 300 characters, no newline, no `*`); `name` is a
+ * display name (a title). The runtime renders each as an ordinary `session` row of ListAgents.
+ */
+export interface HostReachableSession {
+    address: string;
+    name?: string;
+    status: "starting" | "running" | "idle" | "exited" | "unavailable" | "archived";
+    /** The session's product mode (`code`, `dispatch`, …). */
+    mode: string;
+    cwd?: string;
+}
+export interface HostMessageListAnswer {
+    sessions: HostReachableSession[];
+    /** How many MORE reachable sessions the host did not list (its own cap). Rendered as a count, so a listing is never silently truncated. */
+    omitted?: number;
+}
+/**
+ * Host messaging: the runtime -> host `host_session_stop` control request (subtype
+ * `HOST_SESSION_STOP_SUBTYPE`). `TaskStop` sends it when its `task_id` names no task of this session (a
+ * background command, a subagent, a workflow) -- i.e. when the id may be one of the HOST's sessions.
+ * Stopping a session interrupts the turn it is running; it never deletes or archives anything.
+ * `fromAgentId` as on `HostMessageSendRequest`: information only.
+ */
+export interface HostSessionStopRequest {
+    id: string;
+    fromAgentId?: string;
+}
+/**
+ * `stopped` (a running turn was interrupted) and `not_running` (nothing to stop) are ordinary answers;
+ * `refused`, `not_found` and `unavailable` carry a required `reason` and reach the model as errors.
+ */
+export interface HostSessionStopAnswer {
+    status: "stopped" | "not_running" | "refused" | "not_found" | "unavailable";
+    reason?: string;
+    /** One sentence for the model beside a `stopped` / `not_running` result — e.g. what happens to messages
+     *  that were queued behind the interrupted turn. Rendered into TaskStop's `message`. */
+    note?: string;
+}
 export interface McpStdioServerConfig {
     type?: "stdio";
     command: string;
@@ -301,6 +395,17 @@ export interface McpSdkServerConfig {
      * host owns it.
      */
     toolNames?: Record<string, string>;
+    /**
+     * SDK 0.0.40, a Winter extension: CONCURRENCY LANES for some of this server's tools, keyed by the
+     * server's own tool name (`{ computer: "computer", browser: "browser" }`). A round's calls normally run
+     * one at a time unless the tool is read-only (`readOnlyHint: true`); a tool in a lane instead runs BESIDE
+     * the round's other calls, but never beside another call of the SAME lane -- calls of one lane run one at
+     * a time, in call order, across the round. Use it for a tool that holds one exclusive resource (a screen,
+     * a browser) yet is safe next to everything else. A call that is neither read-only nor in a lane is a
+     * barrier, exactly as before. A lane key is 1-64 characters of `[A-Za-z0-9_.:-]`; anything else is
+     * ignored. Only an in-process (`sdk`) server may declare lanes; the host vouches for its own tools.
+     */
+    toolLanes?: Record<string, string>;
 }
 export type McpServerConfigForProcessTransport = McpStdioServerConfig | McpHttpServerConfig | McpSSEServerConfig | McpSdkServerConfig;
 export type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
@@ -538,6 +643,13 @@ export interface RuntimeConfig {
      * runtime's own Keychain store, as before (a standalone SDK user). A flag, never material.
      */
     hostCredentials?: boolean;
+    /**
+     * Host messaging, WINTER-ONLY: `true` when the host answers `host_message_send` / `host_message_list`
+     * (`Options.hostMessaging`). `SendMessage` then asks the host to deliver whatever it cannot resolve
+     * in-process, and `ListAgents` adds the sessions the host lists. Absent: in-process only, as before.
+     * A flag, never a handler.
+     */
+    hostMessaging?: boolean;
     autoClassifier?: AutoClassifierConfig;
     advisor?: AdvisorConfig;
     /** The wire twin of `Options.web` -- see `WebToolsConfig`. Pure passthrough; absent means every default in `WEB_TOOLS_DEFAULTS`. */

package/dist/tools/index.js

@@ -3,8 +3,9 @@ import {
   callerAddress2,
   sendMessage2,
   formatListing,
+  omittedLine,
   listAgents2
-} from "../index-51ysrfm8.js";
+} from "../index-3zhkc4nb.js";
 import {
   resolveWinterHome2,
   WinterCompatibilitySessionStore2
@@ -220,12 +221,16 @@ function messagingToolPortFromRuntimeDeps(deps) {
         message: request.body,
         ...request.summary === undefined ? {} : { summary: request.summary },
         ...request.notifyWhenIdle === undefined ? {} : { notify_when_idle: request.notifyWhenIdle }
-      });
+      }, request.signal !== undefined ? { signal: request.signal } : {});
     },
     async listReachable(scope) {
       const { rows } = await listAgents2(deps, { sessionId: scope.from.parentWinterSessionId ?? scope.from.winterSessionId }, {});
       return rows;
     },
+    async listReachableDetailed(scope) {
+      const { rows, omitted } = await listAgents2(deps, { sessionId: scope.from.parentWinterSessionId ?? scope.from.winterSessionId }, {}, scope.signal !== undefined ? { signal: scope.signal } : {});
+      return { rows, ...omitted !== undefined ? { omitted } : {} };
+    },
     readNotifications(sessionId) {
       return deps.notifications.drain(sessionId);
     }
@@ -274,9 +279,10 @@ function createMessagingToolHandlers(port, caller) {
           body: accepted.args.message,
           ...summary === undefined ? {} : { summary },
           ...accepted.args.notify_when_idle === undefined ? {} : { notifyWhenIdle: accepted.args.notify_when_idle },
-          ...who.toolUseId === undefined ? {} : { originToolCallId: who.toolUseId }
+          ...who.toolUseId === undefined ? {} : { originToolCallId: who.toolUseId },
+          ...who.signal === undefined ? {} : { signal: who.signal }
         });
-        const payload = result.notify === undefined ? result.outcome : { ...result.outcome, notify: result.notify };
+        const payload = { ...result.outcome, ...result.notify === undefined ? {} : { notify: result.notify }, ...result.note === undefined ? {} : { note: result.note } };
         return text(JSON.stringify(payload), MODEL_FACING_FAILURES.has(result.outcome.status));
       });
     },
@@ -285,8 +291,13 @@ function createMessagingToolHandlers(port, caller) {
       if (!accepted.ok)
         return text(accepted.reason, true);
       return guarded("ListAgents could not reach the messaging system", async () => {
-        const rows = await port.listReachable({ from: callerAddress2(identity()) });
-        return text(JSON.stringify({ listing: formatListing(rows) }));
+        const who = identity();
+        const from = callerAddress2(who);
+        const detailed = port.listReachableDetailed !== undefined ? await port.listReachableDetailed({ from, ...who.signal !== undefined ? { signal: who.signal } : {} }) : { rows: await port.listReachable({ from }) };
+        const rows = detailed.rows;
+        const omitted = detailed.omitted ?? 0;
+        return text(JSON.stringify({ listing: omitted > 0 ? `${formatListing(rows)}
+${omittedLine(omitted)}` : formatListing(rows) }));
       });
     },
     async readNotifications(rawArgs) {

package/dist/tools/messaging-handlers.d.ts

@@ -15,6 +15,8 @@ export interface WinterToolCaller {
     sessionId: string;
     agentId?: string;
     toolUseId?: string;
+    /** The calling tool's own abort signal, when the host binds the caller per call (host messaging cancels a pending delivery with it). */
+    signal?: AbortSignal;
 }
 /** The host-neutral tool result: one text body, plus whether the model should read it as a failure. */
 export interface WinterToolResult {

package/dist/tools/port.d.ts

@@ -1,5 +1,6 @@
 import { callerAddress, type ListedRuntimeObject, type MessagingRuntimeDeps, type NotificationRecord, type RuntimeAddress, type SendMessageResult } from "../messaging/index.js";
 export interface MessagingToolPort {
+    /** `signal`: the calling tool's own (host messaging cancels a pending host delivery with it). */
     sendDetailed(request: {
         from: RuntimeAddress;
         to: string;
@@ -7,10 +8,19 @@ export interface MessagingToolPort {
         summary?: string;
         notifyWhenIdle?: boolean;
         originToolCallId?: string;
+        signal?: AbortSignal;
     }): Promise<SendMessageResult>;
     listReachable(scope: {
         from: RuntimeAddress;
     }): Promise<ListedRuntimeObject[]>;
+    /** Optional: the rows plus how many reachable ones were NOT listed (a host's cap). Preferred by the ListAgents handler when present. */
+    listReachableDetailed?(scope: {
+        from: RuntimeAddress;
+        signal?: AbortSignal;
+    }): Promise<{
+        rows: ListedRuntimeObject[];
+        omitted?: number;
+    }>;
     readNotifications(sessionId: string): {
         notifications: NotificationRecord[];
         remaining: number;

package/package.json

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