@yanlinglabs/winter-agent-sdk 0.0.1 → 0.0.3

package/README.md

@@ -38,6 +38,36 @@ files, `README.md` and `LICENSE`. It does **not** ship `src/`: the TypeScript so
 <https://github.com/yanlingLabs/winter-agent-sdk>, which is where to read them, file an issue, or send
 a patch.
 
+## Subpaths
+
+The main entry is the wrapper surface above. Two subpaths ship beside it, for hosts that compose
+Winter rather than only call it:
+
+**`@yanlinglabs/winter-agent-sdk/messaging`** (since 0.0.2) — the cross-runtime messaging contract
+and its router core: addresses, listings, delivery outcomes, the adapter interface, inbound policy,
+the `notify_when_idle` subscription store, and the three orchestration functions a host drives them
+with. It ships no adapter and no process-level singleton; those are host composition.
+
+**`@yanlinglabs/winter-agent-sdk/tools`** (since 0.0.3) — Winter's default tools, declared and
+implemented once:
+
+- `WINTER_DEFAULT_TOOL_DEFINITIONS` — `send_message`, `list_agents`, `read_notifications` and
+  `advisor`, each a `WinterToolDefinition` carrying a BARE `toolName`, the official built-in alias
+  key in `builtinName`, the description, the schemas and a permission class. No registry policy
+  fields: a host supplies its own.
+- the native schemas and their bounds (`NATIVE_SEND_MESSAGE_SCHEMA`, `SEND_MESSAGE_TO_MAX` and the
+  rest), plus strict acceptors — unknown arguments are refused, `summary` is truncated rather than
+  rejected, and a refusal is returned as data the model can correct from, never thrown.
+- `MessagingToolPort` + `messagingToolPortFromRuntimeDeps`, and `createMessagingToolHandlers`, which
+  turn a messaging world into the three tool handlers over it.
+- `createAdvisorToolHandler` and `transcriptSourceForSessionKey`, with the reviewer left to the host
+  to resolve.
+
+A host BINDS these under its own names: the Winter runtime registers them as its native built-ins
+plus two canonical standing-server twins, and `@yanlinglabs/winter-runtime-sdk` binds the same
+definitions under Claude's built-in names. Handlers return `{ text, isError? }` for each host to
+wrap in its own result shape.
+
 ## License
 
 MIT — see [`LICENSE`](./LICENSE), which ships in the published tarball.

package/dist/index-51ysrfm8.js

@@ -0,0 +1,614 @@
+// src/messaging/adapter.ts
+function serializeRuntimeAddress2(addr) {
+  if (addr.objectKind === "session")
+    return `session:${addr.winterSessionId}`;
+  if (addr.childId === undefined) {
+    throw new Error("serializeRuntimeAddress: objectKind 'agent' requires childId");
+  }
+  const parent = addr.parentWinterSessionId ?? addr.winterSessionId;
+  return `agent:${parent}:${addr.childId}`;
+}
+function createFakeMessagingRouterSeam2() {
+  const outcomes = new Map;
+  const idsBySenderAndTool = new Map;
+  let children = [];
+  let counter = 0;
+  return {
+    outcomes,
+    setChildren(next) {
+      children = next;
+    },
+    allocateMessageId(senderSessionId, toolUseId) {
+      const key = `${senderSessionId}:${toolUseId}`;
+      const existing = idsBySenderAndTool.get(key);
+      if (existing !== undefined)
+        return existing;
+      const id = `msg-${++counter}`;
+      idsBySenderAndTool.set(key, id);
+      return id;
+    },
+    recordOutcome(messageId, outcome) {
+      outcomes.set(messageId, outcome);
+    },
+    lookupOutcome(messageId) {
+      return outcomes.get(messageId);
+    },
+    children() {
+      return children;
+    }
+  };
+}
+// src/messaging/addressing.ts
+var REFERENCE_RUNTIME_KIND2 = "winter-agent";
+var MAX_TO_LENGTH = 300;
+function validateToField2(to) {
+  if (typeof to !== "string" || to.length === 0)
+    return { ok: false, message: "to must be a non-empty string" };
+  if (to.length > MAX_TO_LENGTH)
+    return { ok: false, message: `to must be at most ${MAX_TO_LENGTH} characters (got ${to.length})` };
+  if (to.includes(`
+`) || to.includes("\r"))
+    return { ok: false, message: "to must not contain a newline" };
+  if (to.includes("*"))
+    return { ok: false, message: 'to must not contain "*" ("*" broadcast is forbidden, WS-10 §10.1)' };
+  return { ok: true };
+}
+function buildSessionAddress2(winterSessionId) {
+  return { objectKind: "session", runtimeKind: REFERENCE_RUNTIME_KIND2, winterSessionId };
+}
+function buildChildAddress2(parentWinterSessionId, childId) {
+  return { objectKind: "agent", runtimeKind: REFERENCE_RUNTIME_KIND2, winterSessionId: parentWinterSessionId, parentWinterSessionId, childId };
+}
+function parseRuntimeAddress2(serialized) {
+  if (serialized.startsWith("session:")) {
+    const id = serialized.slice("session:".length);
+    if (id.length === 0)
+      return;
+    return buildSessionAddress2(id);
+  }
+  if (serialized.startsWith("agent:")) {
+    const rest = serialized.slice("agent:".length);
+    const sep = rest.indexOf(":");
+    if (sep <= 0 || sep === rest.length - 1)
+      return;
+    const parent = rest.slice(0, sep);
+    const childId = rest.slice(sep + 1);
+    return buildChildAddress2(parent, childId);
+  }
+  return;
+}
+function sameAddress2(a, b) {
+  try {
+    return serializeRuntimeAddress2(a) === serializeRuntimeAddress2(b);
+  } catch {
+    return false;
+  }
+}
+// src/messaging/outcomes.ts
+var MAX_GLOBAL_MESSAGE_SIZE2 = 1e6;
+var DEFAULT_MESSAGE_TTL_MS2 = 24 * 60 * 60 * 1000;
+var MAX_HOP_COUNT2 = 10;
+var RAPID_REPEAT_WINDOW_MS2 = 5000;
+var HELD_INBOX_CAP2 = 100;
+var ACCEPTED_QUEUE_CAP2 = 50;
+var DEFAULT_HOLD_EXPIRY_MS2 = 5 * 60 * 1000;
+var NOTIFY_IDLE_EXPIRY_MS2 = 12 * 60 * 60 * 1000;
+function messageExceedsMaxSize2(body) {
+  return body.length > MAX_GLOBAL_MESSAGE_SIZE2;
+}
+function hopCountExceeded2(hopCount) {
+  return hopCount >= MAX_HOP_COUNT2;
+}
+function delivered2(messageId) {
+  return { status: "delivered", messageId };
+}
+function queued2(messageId) {
+  return { status: "queued", messageId };
+}
+function resumedAndDelivered2(messageId) {
+  return { status: "resumed_and_delivered", messageId };
+}
+function held2(messageId, reason) {
+  return { status: "held", messageId, reason };
+}
+function subscribed2(messageId) {
+  return { status: "subscribed", messageId };
+}
+function deliveryUncertain2(messageId, reason) {
+  return { status: "delivery_uncertain", messageId, deliveryMayHaveOccurred: true, reason };
+}
+function refused2(messageId, reason) {
+  return { status: "refused", messageId, reason };
+}
+function ambiguous2(messageId, candidates) {
+  return { status: "ambiguous", messageId, candidates };
+}
+function notFound2(messageId, reason) {
+  return { status: "not_found", messageId, reason };
+}
+function unavailable2(messageId, retryable, reason) {
+  return { status: "unavailable", messageId, retryable, reason };
+}
+function createLoopGuard2() {
+  const lastSeen = new Map;
+  return {
+    check(from, to, body, now) {
+      const key = JSON.stringify([from, to, body]);
+      const prev = lastSeen.get(key);
+      lastSeen.set(key, now);
+      if (prev !== undefined && now - prev < RAPID_REPEAT_WINDOW_MS2)
+        return "duplicate";
+      return "ok";
+    }
+  };
+}
+// src/messaging/resolution.ts
+function childToListedRuntimeObject2(parentSessionId, child) {
+  const running = child.status() === "running";
+  return {
+    address: serializeRuntimeAddress2(buildChildAddress2(parentSessionId, child.record.id)),
+    ...child.record.name !== undefined ? { name: child.record.name } : {},
+    objectKind: "agent",
+    runtimeKind: "winter-agent",
+    status: running ? "running" : "exited",
+    mode: child.record.permission.effectiveMode,
+    capabilities: {
+      message: running,
+      resume: !running,
+      notifyWhenIdle: false,
+      reply: running
+    }
+  };
+}
+function resolveTarget2(input) {
+  const ownChildren = input.children.filter((c) => c.record.parentSessionId === input.callerParentSessionId);
+  const parsed = parseRuntimeAddress2(input.to);
+  if (parsed !== undefined) {
+    if (parsed.objectKind === "agent") {
+      const owningParent = parsed.parentWinterSessionId ?? parsed.winterSessionId;
+      if (owningParent !== input.callerParentSessionId) {
+        return { kind: "not_found", message: `"${input.to}" is not reachable from this session (a child agent is only addressable within its owning parent)` };
+      }
+      const child = ownChildren.find((c) => c.record.id === parsed.childId);
+      if (child === undefined)
+        return { kind: "not_found", message: `no child at canonical address "${input.to}"` };
+      return { kind: "resolved", address: parsed, child };
+    }
+    const peer = input.peers.find((p) => p.address === input.to);
+    if (peer === undefined)
+      return { kind: "not_found", message: `no live session at canonical address "${input.to}"` };
+    return { kind: "resolved", address: { ...parsed, runtimeKind: peer.runtimeKind } };
+  }
+  const byId = ownChildren.find((c) => c.record.id === input.to);
+  if (byId !== undefined) {
+    return { kind: "resolved", address: buildChildAddress2(input.callerParentSessionId, byId.record.id), child: byId };
+  }
+  const childrenNamed = ownChildren.filter((c) => c.record.name === input.to);
+  const distinctChildIds = new Set(childrenNamed.map((c) => c.record.id));
+  if (distinctChildIds.size > 1) {
+    return {
+      kind: "stale",
+      message: `"${input.to}" has been used by more than one agent in this conversation; address the one you mean by its canonical address from ListAgents`
+    };
+  }
+  const peersNamed = input.peers.filter((p) => p.name === input.to);
+  const uniqueChild = distinctChildIds.size === 1 ? childrenNamed[0] : undefined;
+  const totalCandidates = (uniqueChild !== undefined ? 1 : 0) + peersNamed.length;
+  if (totalCandidates === 0) {
+    return { kind: "not_found", message: `no agent or session named "${input.to}" is currently reachable` };
+  }
+  if (totalCandidates > 1) {
+    const candidates = [...uniqueChild !== undefined ? [childToListedRuntimeObject2(input.callerParentSessionId, uniqueChild)] : [], ...peersNamed];
+    return { kind: "ambiguous", candidates };
+  }
+  if (uniqueChild !== undefined) {
+    return { kind: "resolved", address: buildChildAddress2(input.callerParentSessionId, uniqueChild.record.id), child: uniqueChild };
+  }
+  const peer = peersNamed[0];
+  if (peer === undefined) {
+    return { kind: "not_found", message: `no agent or session named "${input.to}" is currently reachable` };
+  }
+  const peerAddr = parseRuntimeAddress2(peer.address);
+  if (peerAddr === undefined) {
+    return { kind: "not_found", message: `internal: malformed peer address for "${input.to}"` };
+  }
+  return { kind: "resolved", address: { ...peerAddr, runtimeKind: peer.runtimeKind } };
+}
+// src/messaging/inbound.ts
+var PROMPTING_MODES = new Set(["default", "acceptEdits", "dontAsk", "auto"]);
+function classifyPermissionMode2(mode, opts) {
+  if (mode === "bypassPermissions")
+    return "bypasses";
+  if (mode === "plan")
+    return opts.bypassAvailable ? "bypasses" : "prompts";
+  if (PROMPTING_MODES.has(mode))
+    return "prompts";
+  return "prompts";
+}
+function mapFromModeToPermissionClass2(fromMode) {
+  if (fromMode === "bypass")
+    return "bypasses";
+  if (fromMode === "prompting")
+    return "prompts";
+  return "unknown";
+}
+function defaultInboundResult2(receiverClass, senderClass) {
+  if (receiverClass === "prompts")
+    return senderClass === "bypasses" ? "hold" : "accept";
+  return senderClass === "bypasses" ? "accept" : "hold";
+}
+function resolveInboundDecision2(params) {
+  if (!params.authenticated)
+    return "refuse";
+  if (params.explicitSetting !== undefined)
+    return params.explicitSetting;
+  return defaultInboundResult2(params.receiverClass, params.senderClass);
+}
+function createMailbox2() {
+  const boxes = new Map;
+  function boxFor(key) {
+    let box = boxes.get(key);
+    if (box === undefined) {
+      box = { held: [], acceptedCount: 0 };
+      boxes.set(key, box);
+    }
+    return box;
+  }
+  return {
+    hold(receiverKey, entry) {
+      const box = boxFor(receiverKey);
+      if (box.held.length >= HELD_INBOX_CAP2)
+        return false;
+      box.held.push(entry);
+      return true;
+    },
+    accept(receiverKey) {
+      const box = boxFor(receiverKey);
+      if (box.acceptedCount >= ACCEPTED_QUEUE_CAP2)
+        return false;
+      box.acceptedCount += 1;
+      return true;
+    },
+    releaseAccepted(receiverKey, n = 1) {
+      const box = boxFor(receiverKey);
+      box.acceptedCount = Math.max(0, box.acceptedCount - n);
+    },
+    heldCount(receiverKey) {
+      return boxes.get(receiverKey)?.held.length ?? 0;
+    },
+    acceptedCount(receiverKey) {
+      return boxes.get(receiverKey)?.acceptedCount ?? 0;
+    },
+    listHeld(receiverKey) {
+      return boxes.get(receiverKey)?.held ?? [];
+    },
+    takeHeld(receiverKey, messageId) {
+      const box = boxes.get(receiverKey);
+      if (box === undefined)
+        return;
+      const idx = box.held.findIndex((e) => e.messageId === messageId);
+      if (idx === -1)
+        return;
+      const [removed] = box.held.splice(idx, 1);
+      return removed;
+    },
+    reevaluate(receiverKey, decide) {
+      const box = boxes.get(receiverKey);
+      if (box === undefined)
+        return [];
+      const promoted = [];
+      box.held = box.held.filter((entry) => {
+        if (entry.kind !== "default")
+          return true;
+        const next = decide(entry);
+        if (next === "hold")
+          return true;
+        promoted.push({ entry, next });
+        return false;
+      });
+      return promoted;
+    },
+    sweepExpired(receiverKey, now) {
+      const box = boxes.get(receiverKey);
+      if (box === undefined)
+        return [];
+      const expired = [];
+      box.held = box.held.filter((entry) => {
+        if (entry.kind === "default" && entry.expiresAt !== undefined && entry.expiresAt <= now) {
+          expired.push(entry);
+          return false;
+        }
+        return true;
+      });
+      return expired;
+    }
+  };
+}
+function buildDefaultHoldEntry2(messageId, reason, now) {
+  return { messageId, reason, kind: "default", heldAt: now, expiresAt: now + DEFAULT_HOLD_EXPIRY_MS2 };
+}
+function buildExplicitHoldEntry2(messageId, reason, now) {
+  return { messageId, reason, kind: "explicit", heldAt: now };
+}
+// src/messaging/idle.ts
+function isIdleSubscribeSenderAllowed2(sender) {
+  return !sender.isChild;
+}
+function isIdleSubscribeTargetAllowed2(target) {
+  return target.objectKind === "session" && target.hasReliableIdleSignal;
+}
+function createNotificationQueue2() {
+  const byOwner = new Map;
+  let listeners = [];
+  let counter = 0;
+  return {
+    subscribe(listener) {
+      listeners.push(listener);
+      return () => {
+        listeners = listeners.filter((l) => l !== listener);
+      };
+    },
+    push(ownerKey, rec) {
+      const list = byOwner.get(ownerKey) ?? [];
+      const record = {
+        notification_id: `note-${++counter}`,
+        origin: rec.origin,
+        queued_at: new Date(rec.queuedAtMs).toISOString(),
+        content: rec.content
+      };
+      list.push(record);
+      byOwner.set(ownerKey, list);
+      for (const listener of listeners)
+        listener(ownerKey, record);
+    },
+    drain(ownerKey, max) {
+      const list = byOwner.get(ownerKey) ?? [];
+      const take = max === undefined ? list.length : Math.max(0, Math.min(max, list.length));
+      const notifications = list.splice(0, take);
+      const remaining = list.length;
+      if (list.length === 0)
+        byOwner.delete(ownerKey);
+      else
+        byOwner.set(ownerKey, list);
+      return { notifications, remaining };
+    },
+    pendingCount(ownerKey) {
+      return byOwner.get(ownerKey)?.length ?? 0;
+    }
+  };
+}
+function createIdleSubscriptionStore2() {
+  let pending = [];
+  return {
+    subscribe(sub, now) {
+      pending.push({ ...sub, createdAt: now, expiresAt: now + NOTIFY_IDLE_EXPIRY_MS2 });
+    },
+    fireIdle(targetKey, now, computeReducedStatus, queue, originLabel) {
+      const matches = pending.filter((p) => p.targetKey === targetKey && p.expiresAt > now);
+      pending = pending.filter((p) => p.targetKey !== targetKey);
+      for (const m of matches) {
+        const reducedStatus = computeReducedStatus(m.subscriberKey);
+        queue.push(m.subscriberKey, {
+          origin: originLabel,
+          content: reducedStatus ? `${originLabel} changed state (reduced-status notice: the subscribing session is currently holding cross-session messages from this sender's class)` : `${originLabel} is now idle`,
+          queuedAtMs: now
+        });
+      }
+      return matches.length;
+    },
+    sweepExpired(now) {
+      pending = pending.filter((p) => p.expiresAt > now);
+    },
+    pendingCount(targetKey) {
+      return pending.filter((p) => p.targetKey === targetKey).length;
+    }
+  };
+}
+// src/messaging/attribution.ts
+var AGENT_MESSAGE_TAG2 = "agent-message";
+function escapeAttributionText2(value) {
+  return value.split(`</${AGENT_MESSAGE_TAG2}`).join(`&lt;/${AGENT_MESSAGE_TAG2}`).split(`<${AGENT_MESSAGE_TAG2}`).join(`&lt;${AGENT_MESSAGE_TAG2}`);
+}
+function escapeAttributionAttribute2(value) {
+  return escapeAttributionText2(value).split('"').join("&quot;");
+}
+var RESERVED_NOTIFICATION_KEY_PREFIX2 = "host:";
+function facetNotificationKey2(sessionId) {
+  return `${RESERVED_NOTIFICATION_KEY_PREFIX2}${sessionId}`;
+}
+function isReservedNotificationKey2(key) {
+  return key.startsWith(RESERVED_NOTIFICATION_KEY_PREFIX2);
+}
+// src/messaging/router.ts
+var MAX_TRACKED_MESSAGE_IDS2 = 1e4;
+function rememberBounded2(map, key, value, cap = MAX_TRACKED_MESSAGE_IDS2) {
+  if (map.has(key))
+    map.delete(key);
+  map.set(key, value);
+  while (map.size > cap) {
+    const oldest = map.keys().next();
+    if (oldest.done === true)
+      break;
+    map.delete(oldest.value);
+  }
+}
+function createMessagingRouterSeam2() {
+  const outcomes = new Map;
+  const idsBySenderAndTool = new Map;
+  let sources = [];
+  let counter = 0;
+  return {
+    allocateMessageId(senderSessionId, toolUseId) {
+      const key = JSON.stringify([senderSessionId, toolUseId]);
+      const existing = idsBySenderAndTool.get(key);
+      if (existing !== undefined)
+        return existing;
+      const id = `msg-${++counter}`;
+      rememberBounded2(idsBySenderAndTool, key, id);
+      return id;
+    },
+    recordOutcome(messageId, outcome) {
+      rememberBounded2(outcomes, messageId, outcome);
+    },
+    lookupOutcome(messageId) {
+      return outcomes.get(messageId);
+    },
+    addChildRosterSource(getChildren) {
+      sources.push(getChildren);
+      return () => {
+        sources = sources.filter((s) => s !== getChildren);
+      };
+    },
+    children() {
+      return sources.flatMap((getChildren) => getChildren());
+    }
+  };
+}
+function createSubscriberDirectory2() {
+  const map = new Map;
+  return {
+    remember(messageId, subscriberSessionId) {
+      rememberBounded2(map, messageId, subscriberSessionId);
+    },
+    lookup(messageId) {
+      return map.get(messageId);
+    }
+  };
+}
+function callerAddress2(caller) {
+  if (caller.agentId !== undefined)
+    return buildChildAddress2(caller.sessionId, caller.agentId);
+  return buildSessionAddress2(caller.sessionId);
+}
+var SUCCESS_CLASS_STATUSES = new Set(["delivered", "queued", "resumed_and_delivered"]);
+function outcomeReason(outcome) {
+  return "reason" in outcome ? outcome.reason : outcome.status;
+}
+async function sendMessage2(deps, caller, input) {
+  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) {
+    deps.seam.recordOutcome(messageId, outcome);
+    return notify !== undefined ? { outcome, notify } : { outcome };
+  }
+  const from = callerAddress2(caller);
+  const fromKey = serializeRuntimeAddress2(from);
+  const wantsIdle = input.notify_when_idle === true;
+  const isPureSubscription = input.message.length === 0;
+  if (wantsIdle && !isIdleSubscribeSenderAllowed2({ isChild: caller.agentId !== undefined })) {
+    return settle(refused2(messageId, "notify_when_idle: only a main conversation may subscribe (WS-10 §14)"));
+  }
+  if (!isPureSubscription) {
+    if (messageExceedsMaxSize2(input.message)) {
+      return settle(refused2(messageId, `message exceeds MAX_GLOBAL_MESSAGE_SIZE (${MAX_GLOBAL_MESSAGE_SIZE2} chars)`));
+    }
+    if (deps.loopGuard.check(fromKey, input.to, input.message, now) === "duplicate") {
+      return settle(refused2(messageId, "identical message to the same target was sent moments ago (rapid repeat suppressed, WS-10 §12)"));
+    }
+  }
+  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 === "stale")
+    return settle(refused2(messageId, resolved.message));
+  if (resolved.kind === "ambiguous")
+    return settle(ambiguous2(messageId, resolved.candidates));
+  const to = resolved.address;
+  if (sameAddress2(to, from)) {
+    return settle(refused2(messageId, "cannot SendMessage to your own session (self-target, WS-10 §16)"));
+  }
+  const targetRow = to.objectKind === "agent" && resolved.child !== undefined ? childToListedRuntimeObject2(caller.sessionId, resolved.child) : reachable.find((r) => r.address === serializeRuntimeAddress2(to));
+  if (wantsIdle && (targetRow === undefined || !targetRow.capabilities.notifyWhenIdle)) {
+    return settle(refused2(messageId, "notify_when_idle: target does not support idle notification (subagents, teammates, remote peers, and adapters without a reliable idle signal refuse the WHOLE call, WS-10 §14)"));
+  }
+  if (wantsIdle) {
+    deps.subscribers.remember(messageId, caller.sessionId);
+  }
+  if (isPureSubscription) {
+    return settle(await deps.adapter.subscribeIdle(to, { messageId }));
+  }
+  const hopCount = 0;
+  if (hopCountExceeded2(hopCount))
+    return settle(refused2(messageId, "message exceeds MAX_HOP_COUNT"));
+  const senderPermissionClass = await deps.adapter.senderPermissionClass(from);
+  const envelope = {
+    messageId,
+    from,
+    fromGeneration: 0,
+    to,
+    toGeneration: 0,
+    body: input.message,
+    ...input.summary !== undefined ? { summary: input.summary } : {},
+    notifyWhenIdle: wantsIdle,
+    createdAt: now,
+    expiresAt: now + DEFAULT_MESSAGE_TTL_MS2,
+    hopCount,
+    originToolCallId: caller.toolUseId,
+    senderPermissionClass
+  };
+  const bodyOutcome = await deliverEnvelope(deps, to, resolved.child, envelope, messageId);
+  if (!wantsIdle)
+    return settle(bodyOutcome);
+  if (!SUCCESS_CLASS_STATUSES.has(bodyOutcome.status)) {
+    return settle(bodyOutcome, { refused: `message was not delivered (status: ${bodyOutcome.status}); notify_when_idle was not attempted` });
+  }
+  const idleOutcome = await deps.adapter.subscribeIdle(to, { messageId });
+  return settle(bodyOutcome, idleOutcome.status === "subscribed" ? { subscribed: true } : { refused: outcomeReason(idleOutcome) });
+}
+function describeThrow(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function outcomeForThrow(deps, messageId, err) {
+  if (deps.classifyDeliveryError?.(err) === "refused")
+    return refused2(messageId, describeThrow(err));
+  return deliveryUncertain2(messageId, `unexpected error during delivery: ${describeThrow(err)}`);
+}
+async function deliverEnvelope(deps, to, child, envelope, messageId) {
+  if (to.objectKind === "agent") {
+    if (child === undefined)
+      return notFound2(messageId, "child no longer reachable");
+    try {
+      return child.status() === "running" ? await deps.adapter.steerChild(to, envelope) : await deps.adapter.resumeChild(to, envelope);
+    } catch (err) {
+      return outcomeForThrow(deps, messageId, err);
+    }
+  }
+  try {
+    return await deps.adapter.deliverToSession(to, envelope);
+  } catch (err) {
+    return outcomeForThrow(deps, messageId, err);
+  }
+}
+function formatListing(rows) {
+  if (rows.length === 0)
+    return "No agents or sessions are currently reachable.";
+  return rows.map((r) => {
+    const label = r.name !== undefined ? `${r.name} (${r.address})` : r.address;
+    return `- ${label} [${r.objectKind}/${r.runtimeKind}] status=${r.status} mode=${r.mode}`;
+  }).join(`
+`);
+}
+async function listAgents2(deps, caller, _input) {
+  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 };
+}
+function readNotifications2(deps, caller) {
+  return deps.notifications.drain(caller.sessionId);
+}
+function createMessagingRouter2(deps) {
+  return {
+    deps,
+    sendMessage: (caller, input) => sendMessage2(deps, caller, input),
+    listAgents: (caller, input) => listAgents2(deps, caller, input),
+    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 };