@yanlinglabs/winter-agent-sdk 0.0.1 → 0.0.2

package/dist/messaging/outcomes.d.ts

@@ -0,0 +1,25 @@
+import type { DeliveryOutcome, ListedRuntimeObject } from "./adapter.js";
+export declare const MAX_GLOBAL_MESSAGE_SIZE = 1000000;
+export declare const DEFAULT_MESSAGE_TTL_MS: number;
+export declare const MAX_HOP_COUNT = 10;
+export declare const RAPID_REPEAT_WINDOW_MS = 5000;
+export declare const HELD_INBOX_CAP = 100;
+export declare const ACCEPTED_QUEUE_CAP = 50;
+export declare const DEFAULT_HOLD_EXPIRY_MS: number;
+export declare const NOTIFY_IDLE_EXPIRY_MS: number;
+export declare function messageExceedsMaxSize(body: string): boolean;
+export declare function hopCountExceeded(hopCount: number): boolean;
+export declare function delivered(messageId: string): DeliveryOutcome;
+export declare function queued(messageId: string): DeliveryOutcome;
+export declare function resumedAndDelivered(messageId: string): DeliveryOutcome;
+export declare function held(messageId: string, reason: string): DeliveryOutcome;
+export declare function subscribed(messageId: string): DeliveryOutcome;
+export declare function deliveryUncertain(messageId: string, reason: string): DeliveryOutcome;
+export declare function refused(messageId: string, reason: string): DeliveryOutcome;
+export declare function ambiguous(messageId: string, candidates: ListedRuntimeObject[]): DeliveryOutcome;
+export declare function notFound(messageId: string, reason: string): DeliveryOutcome;
+export declare function unavailable(messageId: string, retryable: boolean, reason: string): DeliveryOutcome;
+export interface LoopGuard {
+    check(from: string, to: string, body: string, now: number): "ok" | "duplicate";
+}
+export declare function createLoopGuard(): LoopGuard;

package/dist/messaging/resolution.d.ts

@@ -0,0 +1,39 @@
+/**
+ * WS-10 §11: the resolution algorithm -- rules 1-6, MUST, in order.
+ *
+ * RUNTIME KIND. A serialized address (`session:<id>` / `agent:<parent>:<child>`) carries NO runtime
+ * kind -- WS-10 §11 puts it in the directory record instead -- so `parseRuntimeAddress` can only ever
+ * stamp a default. Where a `ListedRuntimeObject` row is available, THAT row's declared `runtimeKind`
+ * is authoritative and this function carries it onto the resolved address; a child resolves under
+ * `winter-agent`, since a child of a Winter session is one by construction. A consumer resolving from
+ * its OWN directory (the router) must overlay `runtimeKind` the same way for any address it builds by
+ * hand. `sameAddress` is unaffected -- it compares serializations, which never carry the kind.
+ *
+ * Consumes the `ChildLike` boundary interface and the RuntimeAddress/ListedRuntimeObject/
+ * serializeRuntimeAddress shapes from adapter.ts, and nothing else: resolution is pure, so both the
+ * Winter runtime's in-process adapter and the router package's cross-runtime one get identical
+ * answers.
+ */
+import { type RuntimeAddress, type ListedRuntimeObject, type ChildLike } from "./adapter.js";
+export declare function childToListedRuntimeObject(parentSessionId: string, child: ChildLike): ListedRuntimeObject;
+export interface ResolutionInputs {
+    to: string;
+    callerParentSessionId: string;
+    children: readonly ChildLike[];
+    peers: readonly ListedRuntimeObject[];
+}
+export type ResolutionResult = {
+    kind: "resolved";
+    address: RuntimeAddress;
+    child?: ChildLike;
+} | {
+    kind: "ambiguous";
+    candidates: ListedRuntimeObject[];
+} | {
+    kind: "stale";
+    message: string;
+} | {
+    kind: "not_found";
+    message: string;
+};
+export declare function resolveTarget(input: ResolutionInputs): ResolutionResult;

package/dist/messaging/router.d.ts

@@ -0,0 +1,90 @@
+import { type RuntimeAddress, type ListedRuntimeObject, type DeliveryOutcome, type RuntimeMessagingAdapter, type MessagingRouterSeam, type ChildLike } from "./adapter.js";
+import type { NotificationQueue, NotificationRecord } from "./idle.js";
+import { type LoopGuard } from "./outcomes.js";
+export interface MessagingRouterSeamWithRoster extends MessagingRouterSeam {
+    addChildRosterSource(getChildren: () => readonly ChildLike[]): () => void;
+}
+export declare const MAX_TRACKED_MESSAGE_IDS = 10000;
+export declare function rememberBounded<V>(map: Map<string, V>, key: string, value: V, cap?: number): void;
+export declare function createMessagingRouterSeam(): MessagingRouterSeamWithRoster;
+export interface SubscriberDirectory {
+    remember(messageId: string, subscriberSessionId: string): void;
+    lookup(messageId: string): string | undefined;
+}
+export declare function createSubscriberDirectory(): SubscriberDirectory;
+export interface MessagingRuntimeDeps {
+    seam: MessagingRouterSeam;
+    adapter: RuntimeMessagingAdapter;
+    notifications: NotificationQueue;
+    loopGuard: LoopGuard;
+    subscribers: SubscriberDirectory;
+    now(): number;
+    /**
+     * How a THROW out of an adapter delivery call is classified (R-7b-4's one behavioural seam).
+     *
+     * WS-10 §12's crash-window semantics make `delivery_uncertain` the honest default for an
+     * unexplained throw: from here, "the call failed" and "the effect happened and then the call
+     * failed" are indistinguishable. But a POLICY refusal thrown by an adapter is neither -- it is a
+     * clean, side-effect-free "no", and reporting it as uncertain would be a lie in the safe-looking
+     * direction.
+     *
+     * The core cannot recognise those classes itself: they belong to whichever runtime the adapter
+     * drives (the Winter runtime's `ChildResumeModeIncomparableError` under RULING P4-D; the router
+     * package's own official-branch refusals). So the owner supplies the predicate. ABSENT means
+     * "everything is uncertain", which is exactly the conservative reading.
+     */
+    classifyDeliveryError?(err: unknown): "refused" | "uncertain";
+}
+export interface CallerContext {
+    sessionId: string;
+    agentId?: string;
+    toolUseId: string;
+}
+export declare function callerAddress(caller: {
+    sessionId: string;
+    agentId?: string;
+}): RuntimeAddress;
+export interface SendMessageInput {
+    to: string;
+    message: string;
+    summary?: string;
+    notify_when_idle?: boolean;
+}
+export interface NotifyOutcome {
+    subscribed?: true;
+    refused?: string;
+}
+export interface SendMessageResult {
+    outcome: DeliveryOutcome;
+    notify?: NotifyOutcome;
+}
+export declare function sendMessage(deps: MessagingRuntimeDeps, caller: CallerContext, input: SendMessageInput): Promise<SendMessageResult>;
+export interface ListAgentsInput {
+    channel?: string;
+    q?: string;
+}
+export interface SessionCallerContext {
+    sessionId: string;
+}
+export declare function listAgents(deps: MessagingRuntimeDeps, caller: SessionCallerContext, _input: ListAgentsInput): Promise<{
+    listing: string;
+    rows: ListedRuntimeObject[];
+}>;
+export declare function readNotifications(deps: MessagingRuntimeDeps, caller: SessionCallerContext): {
+    notifications: NotificationRecord[];
+    remaining: number;
+};
+export type { RuntimeAddress, ListedRuntimeObject, DeliveryOutcome };
+export interface MessagingRouter {
+    sendMessage(caller: CallerContext, input: SendMessageInput): Promise<SendMessageResult>;
+    listAgents(caller: SessionCallerContext, input: ListAgentsInput): Promise<{
+        listing: string;
+        rows: ListedRuntimeObject[];
+    }>;
+    readNotifications(caller: SessionCallerContext): {
+        notifications: NotificationRecord[];
+        remaining: number;
+    };
+    readonly deps: MessagingRuntimeDeps;
+}
+export declare function createMessagingRouter(deps: MessagingRuntimeDeps): MessagingRouter;

package/dist/protocol/messaging.d.ts

@@ -0,0 +1,111 @@
+import type { DeliveryOutcome, GlobalAgentMessage, ListedRuntimeObject, NotificationRecord, PermissionClassLabel, RuntimeAddress } from "../messaging/index.js";
+/** Every subtype, in one place, so neither side spells a literal the other does not. */
+export declare const MESSAGING_CONTROL_SUBTYPES: {
+    readonly listReachable: "messaging.list_reachable";
+    readonly deliver: "messaging.deliver";
+    readonly steerChild: "messaging.steer_child";
+    readonly resumeChild: "messaging.resume_child";
+    readonly subscribeIdle: "messaging.subscribe_idle";
+    readonly senderClass: "messaging.sender_class";
+    readonly readNotifications: "messaging.read_notifications";
+    readonly idleNotice: "messaging.idle_notice";
+};
+export type MessagingControlSubtype = (typeof MESSAGING_CONTROL_SUBTYPES)[keyof typeof MESSAGING_CONTROL_SUBTYPES];
+/**
+ * The subtypes the RUNTIME serves (host -> runtime). The engine dispatches on exactly this set.
+ *
+ * `idleNotice` is deliberately absent: it travels runtime -> host, is answered by the WRAPPER, and a
+ * runtime that dispatched it would be answering its own request.
+ */
+export declare const MESSAGING_HOST_REQUEST_SUBTYPES: readonly MessagingControlSubtype[];
+/** The subtypes the WRAPPER serves (runtime -> host). */
+export declare const MESSAGING_RUNTIME_REQUEST_SUBTYPES: readonly MessagingControlSubtype[];
+/** Every subtype, both directions. */
+export declare const MESSAGING_CONTROL_SUBTYPE_LIST: readonly MessagingControlSubtype[];
+/** `messaging.list_reachable` and `messaging.sender_class` are payload-free (like the pinned `list_models`). */
+export interface MessagingDeliverRequest {
+    message: GlobalAgentMessage;
+}
+export interface MessagingChildRequest {
+    /** A canonical address, or a bare child id read within the receiving session. */
+    id: string;
+    message: GlobalAgentMessage;
+}
+export interface MessagingSubscribeIdleRequest {
+    /** A canonical address, or a bare child id read within the receiving session. */
+    id: string;
+    /**
+     * The HOST's own message id. The facet never allocates one: allocation is the router's
+     * (WS-10 §12 keys it to the sender session plus tool-call id), and a second allocator on the far
+     * side of a pipe would break the retry idempotency that key exists for.
+     */
+    messageId: string;
+    /**
+     * Whose notification queue an eventual idle notice belongs to. WS-10 §15's `subscribeIdle(addr,
+     * {messageId})` carries no subscriber at all, and the in-process reference answers that gap with a
+     * router-side directory keyed by messageId -- which a REMOTE caller cannot write into. So the
+     * caller names it here; absent means the receiving session itself.
+     */
+    subscriberSessionId?: string;
+}
+export interface MessagingSenderClassResponse {
+    senderClass: PermissionClassLabel;
+}
+/**
+ * `messaging.read_notifications` — the CATCH-UP half of `notify_when_idle` (WS-15 §6.4).
+ *
+ * A bounded page: `max` caps how many records come back and `remaining` says how many are still
+ * queued, so a host recovering after a restart drains in pages rather than in one unbounded frame
+ * whose size nothing governs.
+ */
+export interface MessagingReadNotificationsRequest {
+    /** Whose queue to drain. Absent = the receiving session's own. */
+    subscriberSessionId?: string;
+    /** Page size. Absent = everything queued for that key. */
+    max?: number;
+}
+export interface MessagingNotificationsPage {
+    notifications: NotificationRecord[];
+    remaining: number;
+}
+/**
+ * `messaging.idle_notice` — the LIVE half, and the ONE subtype that travels runtime -> host.
+ *
+ * The SAME notice the drain returns, carrying the same `notification_id`, because the queue is the
+ * durable record and this is a signal derived from it: a host that missed the frame (crashed, not yet
+ * connected) still finds the entry via `read_notifications`, and a host that got both dedupes on the
+ * id. The runtime does NOT wait for a handler — an unanswered or refused notice is a dropped LIVE
+ * signal, never a dropped notice.
+ */
+export interface MessagingIdleNoticePayload {
+    /** The queue key the notice was filed under -- the SUBSCRIBER, not the target that went idle. */
+    subscriberSessionId: string;
+    notice: NotificationRecord;
+}
+export declare function isRuntimeAddress(v: unknown): v is RuntimeAddress;
+export declare function isGlobalAgentMessage(v: unknown): v is GlobalAgentMessage;
+export declare function isDeliveryOutcome(v: unknown): v is DeliveryOutcome;
+export declare function isListedRuntimeObjectArray(v: unknown): v is ListedRuntimeObject[];
+export declare function isPermissionClassLabel(v: unknown): v is PermissionClassLabel;
+export declare function isMessagingDeliverRequest(v: unknown): v is MessagingDeliverRequest;
+export declare function isMessagingChildRequest(v: unknown): v is MessagingChildRequest;
+export declare function isNotificationRecord(v: unknown): v is NotificationRecord;
+export declare function isMessagingNotificationsPage(v: unknown): v is MessagingNotificationsPage;
+export declare function isMessagingIdleNoticePayload(v: unknown): v is MessagingIdleNoticePayload;
+export declare function isMessagingReadNotificationsRequest(v: unknown): v is MessagingReadNotificationsRequest;
+export declare function isMessagingSubscribeIdleRequest(v: unknown): v is MessagingSubscribeIdleRequest;
+/**
+ * Turns a facet `id` into a `RuntimeAddress` within the receiving session.
+ *
+ * TWO forms, and no third:
+ *   1. a CANONICAL address (`session:<id>` / `agent:<parent>:<child>`) -- parsed by WS-10 §11's own
+ *      inverse, so a router that already holds a directory entry addresses it exactly;
+ *   2. a bare stable CHILD id -- read within the receiving session, which is the only scope in which
+ *      a child id means anything (WS-10 §10.3: a child is reachable only through its owning parent).
+ *
+ * It deliberately does NOT fall back to display-name lookup. That is resolution rule 3, and rules
+ * 3/4/5 are inseparable -- a name that resolves here would be a name that never got its ambiguity
+ * and staleness checks, because those need the whole directory the router holds and this side does
+ * not.
+ */
+export declare function resolveFacetTarget(sessionId: string, id: string, parse: (s: string) => RuntimeAddress | undefined, buildChild: (parent: string, childId: string) => RuntimeAddress): RuntimeAddress;

package/dist/query.d.ts

@@ -2,6 +2,8 @@ import type { SdkMessage as RuntimeSdkMessage } from "./protocol/frames.js";
 import type { AccountInfo, ModelInfo, ModelFamilyListing, RewindFilesResult } from "./protocol/config.js";
 import { type Options } from "./options.js";
 import type { PermissionMode, PermissionResult } from "./permissions/types.js";
+import { type DeliveryOutcome, type GlobalAgentMessage, type ListedRuntimeObject, type PermissionClassLabel } from "./messaging/index.js";
+import { type MessagingNotificationsPage, type MessagingIdleNoticePayload } from "./protocol/messaging.js";
 export type SdkMessage = Extract<RuntimeSdkMessage, {
     type: "system";
 } | {
@@ -24,6 +26,88 @@ export interface QueryInternal {
     registerControlRequestHandler(subtype: string, handler: ControlRequestHandler): void;
     respondPermission(requestId: string, result: PermissionResult): void;
 }
+/**
+ * R-7b-4: the per-session MESSAGING FACET -- `RuntimeMessagingAdapter` (WS-10 §15) reached over this
+ * session's own control channel.
+ *
+ * WHO CALLS IT: `@yanlinglabs/winter-runtime-sdk`, from the HOST process. A spawned Winter session's
+ * children live inside that session's process, behind a pipe; without this facet the router owns a
+ * RuntimeDirectory that can address the session and nothing inside it, so WS-15 §6.2's "running
+ * Winter child" and "terminal Winter child" rows have no mechanism at all.
+ *
+ * WHAT IT IS NOT: the router. Every rule that needs the whole directory -- WS-10 §11's resolution
+ * order, ambiguity, staleness, §12's dedupe/retry ledger and loop guard, §13's hold/refuse policy --
+ * runs ABOVE this, in the host, once, for both runtimes. This is the six owner-specific operations
+ * the router delegates to whichever runtime actually holds the object.
+ *
+ * WINTER-ONLY, disclosed: the pinned official SDK has no messaging surface of any kind (its `Query`
+ * declares none), so there is no counterpart to mirror and nothing here is a divergence FROM one.
+ *
+ * FOUR THINGS A CONSUMER MUST KNOW, because none of them is visible in the signatures:
+ *
+ *  1. NO DELIVERY METHOD REJECTS. `deliver`, `steerChild`, `resumeChild` and `subscribeIdle` always
+ *     RESOLVE with a typed `DeliveryOutcome` -- a caller that must record an outcome for every
+ *     message (WS-10 §12's ledger) is never left with nothing to write down. A refusal the runtime
+ *     could name arrives as `refused`; an unregistered messaging runtime as non-retryable
+ *     `unavailable`; every other failure, including a transport fault, as `delivery_uncertain`,
+ *     because from the host's side that is genuinely indistinguishable from "it already happened".
+ *  2. THIS FACET SERVES ONE SESSION -- its own, and its own children. A target naming another session
+ *     is refused, even though the runtime could reach it in a shared process: cross-session delivery
+ *     belongs to the router, through its directory, which is the one party that holds every session's
+ *     entry and can pick the right adapter for it.
+ *  3. THE RECEIVER RE-RUNS INBOUND POLICY on the `senderPermissionClass` YOU stamped (WS-10 §13), so
+ *     a caller-side decision to deliver can still come back `held` or `refused`. The envelope's class
+ *     is an input to the receiver's matrix, never a verdict.
+ *  4. NOTIFICATIONS ARE NAMESPACED. `subscribeIdle` and `readNotifications` default to the FACET's own
+ *     queue key (`host:<sessionId>`), deliberately separate from the one the session's own model
+ *     drains with its `ReadNotifications` tool -- a drain REMOVES, so a shared key would have
+ *     whichever side read first silently eat the other's notices. Passing
+ *     `subscriberSessionId: <the session's own id>` opts into the model's bucket on purpose.
+ */
+export interface SessionMessagingFacet {
+    /** Every object this session can currently reach: its own children, plus the reachable live peers its adapter knows (WS-10 §10.2 -- never exited transcripts). */
+    listReachable(): Promise<ListedRuntimeObject[]>;
+    /** Deliver a fully-addressed envelope. The target is `msg.to`; the receiver's inbound policy (WS-10 §13) runs inside. */
+    deliver(msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    /** Steer a RUNNING child (WS-10 §10.3). `id` is a canonical address or a bare child id within this session. */
+    steerChild(id: string, msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    /** Resume a TERMINAL, addressable child (WS-10 §10.3). Never the reverse of `steerChild`. */
+    resumeChild(id: string, msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    /**
+     * Subscribe to a target going idle (WS-10 §14). `opts.messageId` is the CALLER's -- the facet never
+     * allocates one, because allocation is keyed to the sender session plus tool-call id (§12) and a
+     * second allocator across the pipe would break the retry idempotency that key exists for.
+     * `subscriberSessionId` names whose notification queue the eventual notice belongs to; absent means
+     * the receiving session itself.
+     */
+    subscribeIdle(id: string, opts: {
+        messageId: string;
+        subscriberSessionId?: string;
+    }): Promise<DeliveryOutcome>;
+    /** This session's own sender permission class (WS-10 §13's matrix input), from its LIVE permission mode. */
+    senderClass(): Promise<PermissionClassLabel>;
+    /**
+     * Drain a bounded page of queued notifications -- the CATCH-UP half of `notify_when_idle`
+     * (WS-15 §6.4's restart recovery). `remaining` says how many are still queued, so a host that
+     * reconnects drains in pages rather than in one frame whose size nothing governs.
+     *
+     * A drain is the ACKNOWLEDGEMENT: a record it returns is removed. `onIdleNotice` below carries the
+     * same notice live, with the same `notification_id`, so a host that got both dedupes on the id.
+     */
+    readNotifications(opts?: {
+        subscriberSessionId?: string;
+        max?: number;
+    }): Promise<MessagingNotificationsPage>;
+    /**
+     * Subscribe to LIVE idle notices for this session. Returns an unsubscribe.
+     *
+     * A handler-plus-unsubscribe rather than an async iterator, because a notice is a fire-and-forget
+     * SIGNAL, not a stream a consumer may fall behind on: an iterator would need a buffer, and the
+     * durable buffer already exists on the runtime side (`readNotifications`). A handler that is never
+     * registered, or that throws, loses no notice -- the entry stays queued for the drain.
+     */
+    onIdleNotice(handler: (payload: MessagingIdleNoticePayload) => void): () => void;
+}
 export interface Query extends AsyncGenerator<SdkMessage> {
     interrupt(): Promise<void>;
     setModel(model?: string): Promise<void>;
@@ -73,6 +157,13 @@ export interface Query extends AsyncGenerator<SdkMessage> {
         dryRun?: boolean;
     }): Promise<RewindFilesResult>;
     setPermissionMode(mode: PermissionMode): Promise<void>;
+    /**
+     * R-7b-4: this session's messaging facet, backed by the six `messaging.*` control subtypes.
+     *
+     * ADDITIVE and Winter-only: the pinned `Query` contract loses nothing, and the official SDK has no
+     * member this could collide with. See `SessionMessagingFacet` for what it is and is not.
+     */
+    messaging: SessionMessagingFacet;
     __internal?: QueryInternal;
 }
 export declare function query(args: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanlinglabs/winter-agent-sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -21,6 +21,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./messaging": {
+      "types": "./dist/messaging/index.d.ts",
+      "default": "./dist/messaging/index.js"
     }
   },
   "files": [
@@ -37,15 +41,15 @@
     }
   },
   "dependencies": {
-    "@yanlinglabs/winter-provider-catalog": "0.0.1"
+    "@yanlinglabs/winter-provider-catalog": "0.0.2"
   },
   "optionalDependencies": {
-    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.1"
+    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.2"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
-    "@yanlinglabs/winter-conformance": "0.0.1",
-    "winter-agent-runtime": "0.0.1"
+    "@yanlinglabs/winter-conformance": "0.0.2",
+    "winter-agent-runtime": "0.0.2"
   },
   "scripts": {}
 }