@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/messaging/attribution.d.ts

@@ -0,0 +1,47 @@
+import type { GlobalAgentMessage, RuntimeAddress } from "../seams/messaging-contract.js";
+/** A sender whose `from` cannot be turned into a canonical address cannot be attributed at all. */
+export declare class UnattributableSenderError extends Error {
+    constructor(reason: string);
+}
+/**
+ * THE OWNER CHECK ON ITS OWN — the reason this envelope cannot be attributed here, or `undefined`.
+ *
+ * SEPARATED FROM THE RENDERING (review r1, D1) because it is a DECISION and rendering is an effect,
+ * and the three delivery paths need the decision at a different moment than the string: before any
+ * push, outside every `try`, so that one envelope gets one answer whichever handle shape a host
+ * attached. Evaluated inside a `try` whose `catch` maps to `delivery_uncertain`, the same refusal
+ * became "the delivery may have occurred" for a message that provably never left the router — and
+ * WS-10 §12's recovery contract then forbids retrying it, so a clean side-effect-free "no" turned into
+ * a permanently ambiguous record.
+ *
+ * `owner` is the session whose input stream this is going into. A claimed CHILD sender is only
+ * attributable by the session that owns that child (WS-10 §10.3), so an `agent:` origin from somewhere
+ * else is refused rather than rendered with an address this side cannot vouch for. Pass `undefined` to
+ * skip the check — for the official branch's owner-qualified relay, where the message is deliberately
+ * being handed to a parent that does NOT own the sender.
+ */
+export declare function unattributableReason(message: GlobalAgentMessage, owner?: {
+    winterSessionId: string;
+}): string | undefined;
+/**
+ * The attributed turn, byte-for-byte as the Winter runtime renders it.
+ *
+ * Throws `UnattributableSenderError` on the same condition `unattributableReason` names, so a caller
+ * that renders without checking still cannot produce an unattributable frame — but every caller in
+ * this package checks FIRST, because a throw at this point is an effect-free refusal and must be
+ * reported as one.
+ */
+export declare function renderAttributedTurn(message: GlobalAgentMessage, owner?: {
+    winterSessionId: string;
+}): string;
+/**
+ * The owner-qualified form: the same frame, plus the address the message was actually FOR.
+ *
+ * WS-15 §6.2's official-child rows are the only user: "Native child messaging through the active
+ * owning parent session", and "the public result stays owner-qualified" — the official runtime has no
+ * out-of-band door into a child, so a message for one is delivered to the owning parent, which is a
+ * different fact from a message TO the parent and must not read like one. The `for` attribute is
+ * router-authored (it is the resolved canonical address, not anything a sender wrote), so it is
+ * escaped for the same defensive reason `from` is and can no more be forged than `from` can.
+ */
+export declare function renderOwnerQualifiedTurn(message: GlobalAgentMessage, target: RuntimeAddress): string;

package/dist/messaging/dispatch.d.ts

@@ -0,0 +1,78 @@
+import type { RuntimeMessagingAdapter } from "@yanlinglabs/winter-agent-sdk/messaging";
+import type { DirectorySnapshot } from "../directory/directory.js";
+import type { RuntimeDirectoryStore } from "../seams/directory-store.js";
+import type { DeliveryOutcome, RuntimeAddress, RuntimeKind } from "../seams/messaging-contract.js";
+import type { InboundPolicy } from "./inbound.js";
+/**
+ * WS-10 §15's adapter, plus the ONE fact the router must know about a runtime that the interface has
+ * nowhere to put: whether it has a reliable idle signal at all.
+ *
+ * WS-10 §14 requires that "subagents, teammates, cloud/remote targets, AND ADAPTERS WITHOUT A RELIABLE
+ * IDLE SIGNAL MUST refuse the ENTIRE call (including any attached message)". The shared core enforces
+ * that from the target row's `capabilities.notifyWhenIdle` flag — which is a DIRECTORY field, written
+ * by a host. A host that sets it optimistically on an official-runtime row would get the body
+ * delivered and only the subscription refused, which is precisely the "delivered and then
+ * un-delivered" shape §14 exists to prevent. So the adapter declares it, and the dispatcher clears the
+ * flag on every row belonging to a runtime that cannot back it. Absent means "yes" — the honest
+ * default for a host-registered adapter this package knows nothing about.
+ */
+export interface RouterMessagingAdapter extends RuntimeMessagingAdapter {
+    readonly supportsIdleSubscriptions?: boolean;
+    /**
+     * PER ADDRESS, where `supportsIdleSubscriptions` is per RUNTIME (review r2, NEW-2).
+     *
+     * The runtime-wide flag is not fine enough: the Winter branch genuinely has a reliable idle signal
+     * (its engine is the session-status event source), but only for a session this process holds a
+     * FACET for — its own `subscribeIdle` refuses a facet-less one by address. So a row whose
+     * `capabilities.notifyWhenIdle` a host wrote `true` (the ordinary case) attached through a plain
+     * input-stream writer passed the core's eligibility check, the body was DELIVERED, and only the
+     * subscription came back refused — which is exactly what WS-10 §14's "refuse the ENTIRE call
+     * (including any attached message) so the sender can retry without the flag" forbids.
+     *
+     * Absent means "the runtime-wide flag is the whole answer", which is the honest default for a
+     * host-registered adapter this package cannot see inside.
+     */
+    canSubscribeIdle?(address: RuntimeAddress): Promise<boolean> | boolean;
+}
+export interface DispatchDeps {
+    snapshot: DirectorySnapshot;
+    adapters: ReadonlyMap<RuntimeKind, RouterMessagingAdapter>;
+    policy: InboundPolicy;
+    store: RuntimeDirectoryStore;
+    now(): number;
+    /**
+     * Which rows the core is allowed to see through `listReachable`.
+     *
+     * `resolve` is every object this caller may ADDRESS — including an exited session, which WS-15 §6.2
+     * has a routing row for. `list` is WS-10 §10.2's narrower listing eligibility. They are two views of
+     * the same snapshot rather than two reads, so a listing and a resolution can never disagree about a
+     * row that changed in between.
+     */
+    view: "resolve" | "list";
+    /**
+     * WHERE A SUBSCRIBE GOES (review r1, M1). Absent = straight to the owner adapter.
+     *
+     * The shared core calls `adapter.subscribeIdle` for both the pure-subscription and the combined
+     * `SendMessage{notify_when_idle}` call — the MODEL-facing path. Delegating that to the owner adapter
+     * subscribes at the RUNTIME and writes nothing durable, so the router's own `store.subscriptions` —
+     * the only thing `noteIdle()` reads — stayed empty and the one notice WS-10 §14 promises could never
+     * be routed to anyone. The model was told `subscribed: true` and nothing ever arrived.
+     *
+     * So the core's dispatcher is given the ROUTER's own subscription door here, and only the router's
+     * door talks to the owner adapter (with this field absent, which is also what stops the two from
+     * recursing into each other).
+     */
+    subscribeIdleVia?: (target: RuntimeAddress, request: {
+        messageId: string;
+    }) => Promise<DeliveryOutcome>;
+    /**
+     * The inbound decision has ALREADY been made for this envelope (review r1, low 2).
+     *
+     * Set when a HELD message is released: `InboundPolicy.reevaluate` decided it and removed its durable
+     * record, so re-running `decide` on the way out could produce a second, divergent answer that holds
+     * a message whose record is gone — losing it. The accepted-queue slot is still reserved, because
+     * that is the half a release genuinely changes.
+     */
+    inboundDecided?: boolean;
+}
+export declare function createDispatchingAdapter(deps: DispatchDeps): RuntimeMessagingAdapter;

package/dist/messaging/handlers.d.ts

@@ -0,0 +1,56 @@
+import { type GlobalMessagingHandle } from "./router.js";
+/** The MCP result shape both branches return — structurally the descriptor's own (WS-14 §11). */
+export interface MessagingToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export type MessagingToolHandler = (args: unknown, extra?: unknown) => Promise<MessagingToolResult>;
+/**
+ * WS-10 §12's RETRY KEY, on the official branch — and it exists, which was not known until it was
+ * measured (item 15; `test/official/runtime-aliases.test.ts` is the measurement).
+ *
+ * §12 wants a message id derived from (sender session, TOOL-CALL id) so "a retry allocates the SAME
+ * id" and returns the stored outcome instead of starting a second turn. On the Winter branch the
+ * caller binds `toolUseId` at registration. On the official branch the handler is inside the vendor's
+ * in-process MCP server, where the only per-call channel is the second argument the vendor passes —
+ * and the reasonable expectation was that it carries MCP request context (a JSON-RPC request id,
+ * `_meta`) rather than an Anthropic-API `tool_use_id`, which is one layer up.
+ *
+ * THE PINNED RUNTIME BRIDGES THEM. Measured on 0.3.250: `extra._meta["claudecode/toolUseId"]` is the
+ * exact id the model emitted. So the official branch gets a real §12 key rather than depending on the
+ * rapid-repeat guard, and the vendor's own namespaced `_meta` name is read rather than guessed at.
+ *
+ * A VENDOR-NAMESPACED KEY IS NEVER REBRANDED (WS-01 §5): `claudecode/toolUseId` is the vendor's name
+ * for the vendor's field, exactly like `CLAUDE_CONFIG_DIR`. It is read defensively — an absent or
+ * non-string value simply falls back to the bound caller's id — because a future pin may move it, and
+ * losing the key must degrade to today's behaviour rather than to a crash.
+ */
+export declare const VENDOR_TOOL_USE_ID_META_KEY = "claudecode/toolUseId";
+export declare function toolUseIdFromExtra(extra: unknown): string | undefined;
+export interface MessagingToolHandlers {
+    sendMessage: MessagingToolHandler;
+    listAgents: MessagingToolHandler;
+}
+/**
+ * WHO IS CALLING — bound at registration, never read out of the arguments.
+ *
+ * The standing MCP server is materialized per session (WS-14 §11), so the caller is known when the
+ * handler is built. Taking it from the ARGUMENTS instead would make the sender's identity something a
+ * model could write, and every fence in this package — the owning-parent rule, the self-target
+ * refusal, WS-10 §13's sender class, WS-15 §6.2's dedupe key — is keyed on it.
+ *
+ * `toolUseId` is the second half of WS-10 §12's retry key. It is OPTIONAL because on the official
+ * branch it is not available: the in-process MCP server hands a tool handler its arguments, and the
+ * router's own materialization does not forward the vendor's `extra` (which is where a request id
+ * would be). A caller that cannot supply one gets no dedupe — stated at the door rather than faked
+ * with a stable-looking key that would make two different messages one.
+ */
+export interface MessagingToolCaller {
+    sessionId: string;
+    agentId?: string;
+    toolUseId?: string;
+}
+export declare function createMessagingToolHandlers(messaging: GlobalMessagingHandle, caller: MessagingToolCaller | (() => MessagingToolCaller)): MessagingToolHandlers;

package/dist/messaging/inbound.d.ts

@@ -0,0 +1,110 @@
+import type { CrossSessionInbound, HeldEntry, Mailbox, PermissionClassLabel } from "@yanlinglabs/winter-agent-sdk/messaging";
+import type { HeldMessageRecord, RuntimeDirectoryEntry, RuntimeDirectoryStore } from "../seams/directory-store.js";
+import type { DeliveryOutcome, GlobalAgentMessage, SerializedRuntimeAddress } from "../seams/messaging-contract.js";
+export interface InboundPolicyHooks {
+    /**
+     * The receiver's own explicit `crossSessionInbound` setting, when the host has one.
+     *
+     * WS-10 §13: an explicit setting ALWAYS WINS over the class matrix. It is a host fact (the settings
+     * hierarchy is the host's), so it is asked for rather than assumed; absent means "no explicit
+     * setting", which is what makes the matrix the default rather than the only rule.
+     */
+    explicitSetting?: (receiver: RuntimeDirectoryEntry) => Promise<CrossSessionInbound | undefined> | CrossSessionInbound | undefined;
+    /**
+     * WS-10 §13: "an unauthenticated route is refused BEFORE the matrix."
+     *
+     * The router's own default answer is "authenticated exactly when the sender is an object this
+     * directory authored" — a canonical address the router itself issued and can still resolve. That is
+     * the strongest claim a library can make on its own; a cross-machine or phone-originated route
+     * "requires an authenticated Winter transport plus its own policy gate", which is the host's, and
+     * this hook is where the host says so.
+     */
+    authenticatedRoute?: (input: {
+        message: GlobalAgentMessage;
+        receiver: RuntimeDirectoryEntry;
+        senderKnown: boolean;
+    }) => Promise<boolean> | boolean;
+    /**
+     * Called when a held message LEAVES THE MAILBOX WITHOUT BEING DELIVERED — swept by the five-minute
+     * dialog expiry, or re-evaluated to `refuse` (review r3, NEW-10).
+     *
+     * The router supplies it and writes the delivery receipt through, because the ledger is the router's.
+     * Without it a sender's durable receipt reads `held` forever for a message that no longer exists —
+     * and "held" reads as "waiting for you".
+     */
+    onHoldTerminal?: (message: GlobalAgentMessage, outcome: DeliveryOutcome) => Promise<void> | void;
+    /** An explicit hold is the receiver's own choice to queue rather than to take; the kind is its own. */
+    holdKind?: (input: {
+        message: GlobalAgentMessage;
+        receiver: RuntimeDirectoryEntry;
+        decision: CrossSessionInbound;
+    }) => "default" | "explicit";
+}
+export interface InboundPolicyDeps extends InboundPolicyHooks {
+    store: RuntimeDirectoryStore;
+    now(): number;
+    /** The receiver's permission class, asked of the runtime that actually holds it (WS-10 §13). */
+    receiverClass(receiver: RuntimeDirectoryEntry): Promise<PermissionClassLabel>;
+}
+/** The two receiver-scoped facts a decision needs, read once per sweep (NEW-9). */
+export interface ReceiverFacts {
+    explicitSetting: CrossSessionInbound | undefined;
+    receiverClass: PermissionClassLabel;
+}
+export type InboundVerdict = 
+/** Deliver. `release()` MUST be called with the eventual outcome so the accepted-queue slot is freed. */
+{
+    kind: "accept";
+    release(outcome: DeliveryOutcome): void;
+} | {
+    kind: "settled";
+    outcome: DeliveryOutcome;
+};
+export interface InboundPolicy {
+    /** Runs the whole of WS-10 §13 for one envelope against one receiver. */
+    decide(receiver: RuntimeDirectoryEntry, message: GlobalAgentMessage, senderKnown: boolean): Promise<InboundVerdict>;
+    /**
+     * The DECISION alone, with no mailbox effect — the matrix, the explicit setting and the
+     * authentication gate, and nothing else.
+     *
+     * WS-10 §14's returning idle notice is the caller that needs this: "inbound policy applies to the
+     * returning notice", and a held subscription "delivers a REDUCED-STATUS notice, not treated as
+     * ordinary delivered text". A notice is therefore never held in the mailbox and never occupies an
+     * accepted slot — it is reduced or dropped — so it needs the verdict without the bookkeeping that
+     * ordinary mail earns.
+     */
+    classify(receiver: RuntimeDirectoryEntry, message: GlobalAgentMessage, senderKnown: boolean): Promise<CrossSessionInbound>;
+    /**
+     * WS-10 §13's "held messages are re-evaluated when the receiver's mode or settings change".
+     *
+     * Sweeps the 5-minute expiry first, then re-runs the decision for every DEFAULT-class hold (an
+     * explicit hold "persists until a later accept/refusal/session end", so it is never auto-promoted),
+     * and hands back the envelopes that are now deliverable. Delivering them is the router's job — this
+     * module never calls an adapter.
+     */
+    reevaluate(receiver: RuntimeDirectoryEntry): Promise<{
+        released: GlobalAgentMessage[];
+        expired: HeldEntry[];
+    }>;
+    /**
+     * Take an accepted-queue slot WITHOUT re-running the decision (review r1, low 2).
+     *
+     * A RELEASED HOLD HAS ALREADY BEEN DECIDED, by `reevaluate`, which removed its durable record when
+     * it promoted it. Re-running `decide` on the way out would let a second, divergent answer hold a
+     * message whose record is gone — losing it — while still costing the host's hooks another call. The
+     * cap is still honoured, because that is the half a release genuinely changes: a held message
+     * occupies no accepted slot, and a delivered one does.
+     */
+    reserveAccepted(receiverKey: SerializedRuntimeAddress, messageId: string): InboundVerdict;
+    /** WS-10 §13's 5-minute dialog expiry, applied on its own. Returns what it swept. */
+    sweepExpired(receiverKey: SerializedRuntimeAddress): Promise<HeldEntry[]>;
+    /** What is held for a receiver right now, durably. */
+    listHeld(receiverKey: SerializedRuntimeAddress): Promise<HeldMessageRecord[]>;
+    readonly caps: {
+        held: number;
+        accepted: number;
+    };
+    /** Exposed for the router's own counters; the mailbox is this module's, not the router's. */
+    readonly mailbox: Mailbox;
+}
+export declare function createInboundPolicy(deps: InboundPolicyDeps): InboundPolicy;

package/dist/messaging/index.d.ts

@@ -0,0 +1,39 @@
+export { createRuntimeDirectory } from "../directory/directory.js";
+export type { DirectorySnapshot, RuntimeDirectoryHandle, RuntimeDirectoryOptions } from "../directory/directory.js";
+export type { RuntimeDirectoryRecoveryHooks, RuntimeDirectoryRetention } from "../directory/recovery.js";
+export { entryToChildLike, entryToListedRuntimeObject, entryToListedRuntimeObjectList, isListableFrom, isLiveStatus, isResolvableFrom, mergeAdapterOwnedFields, owningSessionIdOf, parentAddressOf, sessionAddressOf } from "../directory/entries.js";
+export { createGlobalMessaging, callerAddressOf, deriveMessageId } from "./router.js";
+export type { GlobalMessagingContext, GlobalMessagingHandle, GlobalMessagingOptions, ReplyRequest } from "./router.js";
+export { createWinterMessagingAdapter } from "./winter-adapter.js";
+export type { WinterMessagingAdapter, WinterMessagingAdapterDeps } from "./winter-adapter.js";
+export { createOfficialMessagingAdapter } from "./official-adapter.js";
+export type { OfficialMessagingAdapter, OfficialMessagingAdapterDeps } from "./official-adapter.js";
+export { createDispatchingAdapter } from "./dispatch.js";
+export type { DispatchDeps, RouterMessagingAdapter } from "./dispatch.js";
+export { createInboundPolicy } from "./inbound.js";
+export type { InboundPolicy, InboundPolicyDeps, InboundPolicyHooks, InboundVerdict } from "./inbound.js";
+export { createAttachedSessionRegistry } from "./sessions.js";
+export type { AttachedOfficialSession, AttachedSession, AttachedSessionRegistry, AttachedWinterSession, LiveSessionStatus } from "./sessions.js";
+export { renderAttributedTurn, renderOwnerQualifiedTurn, UnattributableSenderError } from "./attribution.js";
+export { createMessagingToolHandlers, toolUseIdFromExtra, VENDOR_TOOL_USE_ID_META_KEY } from "./handlers.js";
+export type { MessagingToolCaller, MessagingToolHandler, MessagingToolHandlers, MessagingToolResult } from "./handlers.js";
+import { type RuntimeDirectoryHandle, type RuntimeDirectoryOptions } from "../directory/directory.js";
+import type { SeamContext } from "../seams/context.js";
+import { type GlobalMessagingHandle, type GlobalMessagingOptions } from "./router.js";
+export interface RuntimeMessaging {
+    directory: RuntimeDirectoryHandle;
+    messaging: GlobalMessagingHandle;
+}
+/**
+ * The directory and the router, built together and wired to each other.
+ *
+ * THE ONE WIRE THAT IS EASY TO MISS: the directory's `ChildLike` view delivers through the ROUTER, so
+ * a caller that used `ChildLike.steer`/`resume` (the router core never does — see `entryToChildLike`)
+ * reaches the child's own runtime adapter rather than a stub. It is a late binding on purpose: the
+ * router does not exist yet when the directory is constructed, so the hook closes over a variable
+ * that is assigned one line later.
+ */
+export declare function createRuntimeMessaging(context: SeamContext, options?: {
+    directory?: RuntimeDirectoryOptions;
+    messaging?: GlobalMessagingOptions;
+}): RuntimeMessaging;

package/dist/messaging/official-adapter.d.ts

@@ -0,0 +1,36 @@
+import type { RuntimeDirectory } from "../seams/directory.js";
+import type { RuntimeDirectoryEntry } from "../seams/directory-store.js";
+import type { PermissionClassLabel } from "../seams/messaging-contract.js";
+import type { RouterMessagingAdapter } from "./dispatch.js";
+import type { AttachedOfficialSession, AttachedSessionRegistry } from "./sessions.js";
+export interface OfficialMessagingAdapterDeps {
+    directory: RuntimeDirectory;
+    sessions: AttachedSessionRegistry<AttachedOfficialSession>;
+    /**
+     * WS-15 §6.2's "exited official Claude session → explicitly resume by `backendSessionId`,
+     * re-establish the adapter, then deliver".
+     *
+     * INJECTED, because everything that resume needs — WS-14 §2's Options template, §1's launch profile
+     * and observed config dir, §3's child environment, §12's credential fetch — belongs to the official
+     * ADAPTER lane, and duplicating any of it here would be a second, drifting copy of the branch's
+     * hardest-won configuration. This lane owns only the delivery half: it hands back a live handle, and
+     * this module pushes into it.
+     *
+     * Absent: an exited official session is `unavailable`, non-retryable, with the reason naming what is
+     * missing — never a silent `not_found`, because the session exists and is resumable by a host that
+     * wires this.
+     */
+    resumeExited?: (entry: RuntimeDirectoryEntry) => Promise<AttachedOfficialSession | undefined>;
+    /**
+     * The receiver/sender permission class for an official object, when the host tracks one.
+     *
+     * The pinned runtime exposes no live permission mode to read, so the honest default is `unknown` —
+     * which WS-10 §13's matrix handles explicitly rather than by guessing (`prompts × unknown → accept`,
+     * `bypasses × unknown → hold`). A host that knows the mode it launched a session with can say so.
+     */
+    permissionClass?: (entry: RuntimeDirectoryEntry) => Promise<PermissionClassLabel> | PermissionClassLabel;
+}
+export interface OfficialMessagingAdapter extends RouterMessagingAdapter {
+    readonly sessions: AttachedSessionRegistry<AttachedOfficialSession>;
+}
+export declare function createOfficialMessagingAdapter(deps: OfficialMessagingAdapterDeps): OfficialMessagingAdapter;

package/dist/messaging/router.d.ts

@@ -0,0 +1,101 @@
+import type { NotificationRecord, SendMessageResult } from "@yanlinglabs/winter-agent-sdk/messaging";
+import type { RuntimeDirectoryHandle } from "../directory/directory.js";
+import type { SeamContext } from "../seams/context.js";
+import type { GlobalMessaging, SendMessageRequest } from "../seams/global-messaging.js";
+import type { DeliveryOutcome, GlobalAgentMessage, RuntimeAddress, SerializedRuntimeAddress } from "../seams/messaging-contract.js";
+import { type InboundPolicyHooks } from "./inbound.js";
+import { type OfficialMessagingAdapter, type OfficialMessagingAdapterDeps } from "./official-adapter.js";
+import { type AttachedOfficialSession, type AttachedWinterSession } from "./sessions.js";
+import { type WinterMessagingAdapter, type WinterMessagingAdapterDeps } from "./winter-adapter.js";
+/** The context this factory needs: the seam's, with the directory as the concrete handle. */
+export interface GlobalMessagingContext extends SeamContext {
+    directory: RuntimeDirectoryHandle;
+}
+export interface GlobalMessagingOptions extends InboundPolicyHooks {
+    now?: () => number;
+    /** Passed to the Winter adapter this factory builds (cold-resume options, child resume context). */
+    winter?: Omit<WinterMessagingAdapterDeps, "peers" | "directory" | "sessions">;
+    /** Passed to the official adapter this factory builds (the resume collaborator, the class hook). */
+    official?: Omit<OfficialMessagingAdapterDeps, "directory" | "sessions">;
+    /**
+     * R-7b-4's one behavioural seam, forwarded to the core: how a THROW out of an adapter is classified.
+     *
+     * ABSENT MEANS EVERYTHING IS UNCERTAIN, which is the conservative reading and the core's own default
+     * — `refused` asserts the effect did NOT happen, and from this side "the call failed" and "the
+     * effect happened and then the call failed" are indistinguishable (WS-10 §12).
+     */
+    classifyDeliveryError?: (error: unknown) => "refused" | "uncertain";
+}
+export interface ReplyRequest {
+    /** The envelope being replied to. Its `to` becomes the reply's `from`, and its `from` the target. */
+    original: GlobalAgentMessage;
+    body: string;
+    summary?: string;
+}
+/** The seam, plus the doors a host and this package's own tool handlers need. */
+export interface GlobalMessagingHandle extends GlobalMessaging {
+    readonly winterAdapter: WinterMessagingAdapter;
+    readonly officialAdapter: OfficialMessagingAdapter;
+    /** Register a live Winter session AND bridge its idle notices. Returns the detach function. */
+    attachWinterSession(address: SerializedRuntimeAddress, handle: AttachedWinterSession): () => void;
+    attachOfficialSession(address: SerializedRuntimeAddress, handle: AttachedOfficialSession): () => void;
+    /**
+     * `send()`, keeping the shared core's SUPPLEMENTARY fact about a combined call.
+     *
+     * The seam pins `send(): Promise<DeliveryOutcome>`, and the delivery outcome is rightly primary —
+     * but a call that carried both a message AND `notify_when_idle` has a second, separate result (was
+     * the subscription honoured?), and WS-10 §10.1's own result text allows for it. The core reports it
+     * beside the outcome rather than inventing an eleventh status; this door is where that survives, and
+     * `send()` is exactly `(await sendDetailed(...)).outcome`.
+     */
+    sendDetailed(request: SendMessageRequest): Promise<SendMessageResult>;
+    /** WS-10 §13's re-evaluation door: sweep, re-decide, deliver what is now acceptable. */
+    releaseHeld(receiver: SerializedRuntimeAddress): Promise<DeliveryOutcome[]>;
+    /** Reply routing — the one path on which `hopCount` grows, and therefore the one the bound binds. */
+    reply(request: ReplyRequest): Promise<DeliveryOutcome>;
+    /** WS-06 §3.6's `ReadNotifications` page for one session's own queue. */
+    readNotifications(sessionId: string): {
+        notifications: NotificationRecord[];
+        remaining: number;
+    };
+    /**
+     * "This target has gone idle" — WS-10 §14's firing edge, from whatever noticed it.
+     *
+     * Called by the Winter facet bridge for every live notice and every drained one; a host that detects
+     * idleness some other way calls it too. Returns how many notices were pushed.
+     */
+    noteIdle(target: SerializedRuntimeAddress, notice?: {
+        notificationId?: string;
+        content?: string;
+    }): Promise<number>;
+    /** The caps and windows this router enforces, so a host can render them without re-deriving them. */
+    readonly bounds: {
+        heldCap: number;
+        acceptedCap: number;
+        holdExpiryMs: number;
+        idleSubscriptionMs: number;
+        messageTtlMs: number;
+    };
+}
+/**
+ * WS-10 §12's message id: "derived/persisted from the sender session plus tool-call ID", so that "a
+ * retry with the same ID returns the stored outcome".
+ *
+ * DERIVED, NOT COUNTED, and that is the whole point: the shared core allocates `msg-1`, `msg-2` from
+ * an in-process counter, which is stable within one process and COLLIDES across a restart — two
+ * different messages would share an id, and the second would be answered with the first's stored
+ * outcome. Both components are percent-encoded so the pair can never be ambiguous.
+ */
+export declare function deriveMessageId(senderSessionId: string, toolUseId: string): string;
+export declare function createGlobalMessaging(context: GlobalMessagingContext, options?: GlobalMessagingOptions): GlobalMessagingHandle;
+/**
+ * The canonical address a `SendMessage`/`ListAgents` handler runs AS (see `handlers.ts`).
+ *
+ * The subpath's own `callerAddress` builds `agent:<parent>:<child>` for a child caller and
+ * `session:<id>` for a top-level one — the same rule the resolution fence reads, so the handler and
+ * the router can never disagree about who is asking.
+ */
+export declare function callerAddressOf(caller: {
+    sessionId: string;
+    agentId?: string;
+}): RuntimeAddress;

package/dist/messaging/sessions.d.ts

@@ -0,0 +1,49 @@
+import type { SessionMessagingFacet } from "@yanlinglabs/winter-agent-sdk";
+import type { ListedRuntimeObject, SerializedRuntimeAddress } from "../seams/messaging-contract.js";
+/** The live status a handle can report, when it can. Same vocabulary as the directory's own. */
+export type LiveSessionStatus = ListedRuntimeObject["status"];
+export interface AttachedSession {
+    /**
+     * Push one turn into this session's input stream.
+     *
+     * The text is ALREADY RENDERED (attributed, escaped) by the time it gets here — a handle is a pipe,
+     * not a policy. Absent on a Winter handle that only carries a facet: the facet's own `deliver` is
+     * the runtime-side push, and it renders on the far side.
+     */
+    push?(text: string): void | Promise<void>;
+    /** The live status, when the host tracks one. Absent falls back to the durable row's `status`. */
+    status?(): LiveSessionStatus;
+}
+export interface AttachedWinterSession extends AttachedSession {
+    /**
+     * `Query.messaging` (R-7b-4). The ONLY door into a spawned Winter session's children — a child
+     * engine has no facet surface of its own, so `steer_child`/`resume_child` on the PARENT's facet is
+     * how a child is reached, never a session address (Task 0 fix r2, concern 4).
+     */
+    readonly messaging?: SessionMessagingFacet;
+}
+export interface AttachedOfficialSession extends AttachedSession {
+    /**
+     * REQUIRED on this branch, because there is no alternative. The pinned official SDK exposes no
+     * messaging surface of any kind (its `Query` declares none), so an input-stream push is the whole
+     * mechanism — for the session itself and, owner-qualified, for its children.
+     */
+    push(text: string): void | Promise<void>;
+}
+export interface AttachedSessionRegistry<T extends AttachedSession> {
+    /** Register a handle for a canonical address. Returns the detach function. */
+    attach(address: SerializedRuntimeAddress, handle: T): () => void;
+    detach(address: SerializedRuntimeAddress): void;
+    get(address: SerializedRuntimeAddress): T | undefined;
+    addresses(): SerializedRuntimeAddress[];
+}
+/**
+ * A registry, and deliberately nothing more: no liveness inference, no reaping, no ordering.
+ *
+ * ATTACHING IS THE HOST'S CALL, not something this package can discover. `RuntimeSdk.query()` is
+ * where a session is created, and until that door routes to both branches (spine-owned, Task 6) a
+ * host attaches what it launched. `attach` returning its own detach — rather than the caller
+ * remembering the address — is what keeps a handle from outliving the session in the one case that
+ * matters, a re-launch of the same address: the OLD detach then removes only the handle it added.
+ */
+export declare function createAttachedSessionRegistry<T extends AttachedSession>(): AttachedSessionRegistry<T>;

package/dist/messaging/winter-adapter.d.ts

@@ -0,0 +1,47 @@
+import type { Options } from "@yanlinglabs/winter-agent-sdk";
+import type { RuntimeSdkPeers } from "../sdk.js";
+import type { RuntimeDirectory } from "../seams/directory.js";
+import type { RuntimeDirectoryEntry } from "../seams/directory-store.js";
+import type { PermissionClassLabel } from "../seams/messaging-contract.js";
+import type { RouterMessagingAdapter } from "./dispatch.js";
+import type { ChildSelectionInput } from "../selection/runtime-selection.js";
+import type { AttachedSessionRegistry, AttachedWinterSession } from "./sessions.js";
+export interface WinterMessagingAdapterDeps {
+    peers: RuntimeSdkPeers;
+    directory: RuntimeDirectory;
+    sessions: AttachedSessionRegistry<AttachedWinterSession>;
+    /**
+     * The `Options` a COLD RESUME is opened with, beside the `resume` the adapter supplies itself.
+     *
+     * A resume needs a cwd, a model, a permission mode — session facts the messaging layer does not
+     * hold and must not invent. Absent means an empty options object, which is a legitimate resume (the
+     * transcript carries the session's own configuration) and is what the hermetic tests use.
+     */
+    resumeOptions?: (entry: RuntimeDirectoryEntry) => Options | Promise<Options>;
+    /**
+     * WS-13c §8 / WS-10's Phase 6.6 amendment: the catalogue a RESUMED CHILD re-resolves against.
+     *
+     * `resumeChildSelection` answers "is the row this child is RECORDED on still servable?" — and a
+     * refusal is `{ status: "unavailable", retryable: false, reason: "child-provider-unavailable: …" }`
+     * WITH NO GENERATION STARTED, which is why the check runs before the parent's facet is touched.
+     * Absent: nothing re-resolves, and the child's own persisted record stands — which is the correct
+     * fallback rather than a silent skip, because WS-13c §8 makes that record authoritative anyway; the
+     * check only detects DRIFT, and a host with no catalogue has nothing to detect it against.
+     */
+    childResumeContext?: (entry: RuntimeDirectoryEntry) => Omit<ChildSelectionInput, "slot" | "model" | "provider"> | undefined;
+    /**
+     * The permission class of a session this process holds no FACET for — the host's own declaration.
+     *
+     * A live facet answers from the session's live permission mode and always wins. This is the fallback
+     * for a session the router drives through a plain input-stream writer, or one it has a record of and
+     * no handle at all: without it every such receiver is `unknown`, and since review r1's D2 made an
+     * unknown receiver FAIL CLOSED (its mail is held until the class is known), a host would have no way
+     * to say what it launched the session with.
+     */
+    permissionClass?: (entry: RuntimeDirectoryEntry) => Promise<PermissionClassLabel> | PermissionClassLabel;
+}
+/** The adapter plus the one thing the router attaches to it: the live-session registry. */
+export interface WinterMessagingAdapter extends RouterMessagingAdapter {
+    readonly sessions: AttachedSessionRegistry<AttachedWinterSession>;
+}
+export declare function createWinterMessagingAdapter(deps: WinterMessagingAdapterDeps): WinterMessagingAdapter;

package/dist/native-args.d.ts

@@ -0,0 +1,76 @@
+/** WS-10 §10.1's bounds. `to`'s own limit is the subpath's; this is the copy the SCHEMA advertises. */
+export declare const SEND_MESSAGE_TO_MAX = 300;
+export declare const SEND_MESSAGE_SUMMARY_MAX = 200;
+/** WS-10 §10.2's bound on both reserved `ListAgents` fields. */
+export declare const LIST_AGENTS_FIELD_MAX = 256;
+export declare const NATIVE_SEND_MESSAGE_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly to: {
+            readonly type: "string";
+            readonly maxLength: 300;
+            readonly description: "no newline, no \"*\" broadcast";
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly description: "required; defaults \"\" for pure idle subscription";
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly maxLength: 200;
+        };
+        readonly notify_when_idle: {
+            readonly type: "boolean";
+            readonly description: "one-shot; main conversation -> same-machine session only";
+        };
+    };
+    readonly required: readonly ["to", "message"];
+};
+export declare const NATIVE_LIST_AGENTS_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly channel: {
+            readonly type: "string";
+            readonly maxLength: 256;
+            readonly description: "reserved";
+        };
+        readonly q: {
+            readonly type: "string";
+            readonly maxLength: 256;
+            readonly description: "reserved";
+        };
+    };
+};
+/** WS-10 §10.2: "`ListAgents` output is EXACTLY `{ listing: string }`." */
+export declare const NATIVE_LIST_AGENTS_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly listing: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["listing"];
+};
+/** The native `SendMessage` arguments (WS-10 §10.1), after validation. */
+export interface NativeSendMessageArgs {
+    to: string;
+    message: string;
+    summary?: string;
+    notify_when_idle?: boolean;
+}
+/** The native `ListAgents` arguments (WS-10 §10.2). Both fields are reserved in the pinned build. */
+export interface NativeListAgentsArgs {
+    channel?: string;
+    q?: string;
+}
+export type NativeArgsResult<T> = {
+    ok: true;
+    args: T;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Accepts the native `SendMessage` arguments EXACTLY — no more, no less. */
+export declare function acceptNativeSendMessageArgs(input: unknown): NativeArgsResult<NativeSendMessageArgs>;
+/** The same treatment for `ListAgents`: two reserved optional fields, both capped, nothing else. */
+export declare function acceptNativeListAgentsArgs(input: unknown): NativeArgsResult<NativeListAgentsArgs>;