@yanlinglabs/winter-agent-sdk 0.0.1 → 0.0.3

package/dist/messaging/adapter.d.ts

@@ -0,0 +1,119 @@
+import type { PermissionMode } from "../permissions/types.js";
+export type RuntimeKind = "claude-agent" | "winter-agent";
+export type RuntimeObjectKind = "session" | "agent";
+export interface RuntimeAddress {
+    objectKind: RuntimeObjectKind;
+    runtimeKind: RuntimeKind;
+    winterSessionId: string;
+    backendSessionId?: string;
+    parentWinterSessionId?: string;
+    childId?: string;
+}
+export declare function serializeRuntimeAddress(addr: RuntimeAddress): string;
+export interface ListedRuntimeObject {
+    address: string;
+    name?: string;
+    objectKind: RuntimeObjectKind;
+    runtimeKind: RuntimeKind;
+    status: "starting" | "running" | "idle" | "exited" | "unavailable" | "archived";
+    mode: string;
+    cwd?: string;
+    capabilities: {
+        message: boolean;
+        resume: boolean;
+        notifyWhenIdle: boolean;
+        reply: boolean;
+    };
+}
+export type DeliveryOutcome = {
+    status: "delivered";
+    messageId: string;
+} | {
+    status: "queued";
+    messageId: string;
+} | {
+    status: "resumed_and_delivered";
+    messageId: string;
+} | {
+    status: "held";
+    messageId: string;
+    reason: string;
+} | {
+    status: "subscribed";
+    messageId: string;
+} | {
+    status: "delivery_uncertain";
+    messageId: string;
+    deliveryMayHaveOccurred: true;
+    reason: string;
+} | {
+    status: "refused";
+    messageId: string;
+    reason: string;
+} | {
+    status: "ambiguous";
+    messageId: string;
+    candidates: ListedRuntimeObject[];
+} | {
+    status: "not_found";
+    messageId: string;
+    reason: string;
+} | {
+    status: "unavailable";
+    messageId: string;
+    retryable: boolean;
+    reason: string;
+};
+export interface GlobalAgentMessage {
+    messageId: string;
+    from: RuntimeAddress;
+    fromGeneration: number;
+    to: RuntimeAddress;
+    toGeneration: number;
+    body: string;
+    summary?: string;
+    notifyWhenIdle: boolean;
+    createdAt: number;
+    expiresAt: number;
+    hopCount: number;
+    originToolCallId?: string;
+    senderPermissionClass: "prompts" | "bypasses" | "unknown";
+}
+export type ChildLikeStatus = "running" | "completed" | "stopped" | "failed";
+export interface ChildLikeRecord {
+    id: string;
+    parentSessionId: string;
+    name?: string;
+    permission: {
+        effectiveMode: PermissionMode;
+    };
+}
+export interface ChildLike {
+    readonly record: ChildLikeRecord;
+    status(): ChildLikeStatus;
+    steer(msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    resume(msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+}
+export interface RuntimeMessagingAdapter {
+    listReachable(scope: {
+        parent?: RuntimeAddress;
+    }): Promise<ListedRuntimeObject[]>;
+    steerChild(addr: RuntimeAddress, msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    resumeChild(addr: RuntimeAddress, msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    deliverToSession(addr: RuntimeAddress, msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    subscribeIdle(addr: RuntimeAddress, req: {
+        messageId: string;
+    }): Promise<DeliveryOutcome>;
+    senderPermissionClass(addr: RuntimeAddress): Promise<"prompts" | "bypasses" | "unknown">;
+}
+export interface MessagingRouterSeam {
+    allocateMessageId(senderSessionId: string, toolUseId: string): string;
+    recordOutcome(messageId: string, outcome: DeliveryOutcome): void;
+    lookupOutcome(messageId: string): DeliveryOutcome | undefined;
+    children(): ChildLike[];
+}
+export interface FakeMessagingRouterSeam extends MessagingRouterSeam {
+    readonly outcomes: Map<string, DeliveryOutcome>;
+    setChildren(children: ChildLike[]): void;
+}
+export declare function createFakeMessagingRouterSeam(): FakeMessagingRouterSeam;

package/dist/messaging/addressing.d.ts

@@ -0,0 +1,13 @@
+import { type RuntimeAddress, type RuntimeKind } from "./adapter.js";
+export declare const REFERENCE_RUNTIME_KIND: RuntimeKind;
+export type ToFieldValidation = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function validateToField(to: unknown): ToFieldValidation;
+export declare function buildSessionAddress(winterSessionId: string): RuntimeAddress;
+export declare function buildChildAddress(parentWinterSessionId: string, childId: string): RuntimeAddress;
+export declare function parseRuntimeAddress(serialized: string): RuntimeAddress | undefined;
+export declare function sameAddress(a: RuntimeAddress, b: RuntimeAddress): boolean;

package/dist/messaging/attribution.d.ts

@@ -0,0 +1,43 @@
+/** The tag a rendered turn is wrapped in. One literal, so nothing spells it twice. */
+export declare const AGENT_MESSAGE_TAG = "agent-message";
+/**
+ * Fix r2 (N2): the escape that makes the attribution frame mean something.
+ *
+ * THE FINDING. A rendered turn is TEXT in the receiving session's input, and the runtime concatenates
+ * sender-chosen text into it. `body` and `summary` are model-authored on the `SendMessage` path
+ * (straight off the tool input), so a subagent could close the runtime's frame and open a second one
+ * naming an address it does not own with `sender-permission-class="bypasses"` — measured, delivered
+ * intact, and syntactically indistinguishable to the receiving model from the real one. The `from`
+ * field was never forgeable; the FRAME was, which made the label decorative.
+ *
+ * WHAT IS ESCAPED, and nothing more: the two sequences that can end or start a frame (`</tag` and
+ * `<tag`) and the double quote that can close an attribute value. A real message never contains the
+ * first two, and the quote is escaped only inside attribute values, so "a legitimate message arrives
+ * altered" costs a bare `"` in a summary and nothing else. The transformation is VISIBLE rather than
+ * silent (`&lt;` / `&quot;`), so a receiver reading a message that genuinely discusses this syntax
+ * still sees what was written.
+ *
+ * WHAT IT IS NOT. Lexical escaping makes the count of attributions in a turn honest; it does not make
+ * attribution structural. A protocol-level frame kind — where the receiver's DECODER carries the
+ * attribution and a body is inert data whatever it contains — is the real fix, and is recorded as a
+ * carry. Until then this is what keeps the label from being trivially imitable.
+ */
+export declare function escapeAttributionText(value: string): string;
+/** The same, plus the attribute-value quote — for anything interpolated INSIDE the opening tag. */
+export declare function escapeAttributionAttribute(value: string): string;
+/**
+ * Fix r2 (N5): the queue key the FACET files and drains notifications under, built structurally.
+ *
+ * DELIBERATELY NOT the bare session id. A session's own model drains `notifications.drain(sessionId)`
+ * through its `ReadNotifications` tool, and a drain REMOVES — so one key would have whichever side
+ * read first silently eat the other's notices.
+ *
+ * `RESERVED_NOTIFICATION_KEY_PREFIX` is what makes the namespace a rule rather than a coincidence of
+ * string concatenation: a session id that already carries the prefix would otherwise collide back
+ * into the model's bucket. Product ids are `s_<hex>` so it cannot happen today, and
+ * `isReservedNotificationKey` lets a caller assert it instead of assuming it.
+ */
+export declare const RESERVED_NOTIFICATION_KEY_PREFIX = "host:";
+export declare function facetNotificationKey(sessionId: string): string;
+/** True for a key in the facet's reserved namespace — i.e. one the session's own model never drains. */
+export declare function isReservedNotificationKey(key: string): boolean;

package/dist/messaging/idle.d.ts

@@ -0,0 +1,54 @@
+import type { RuntimeObjectKind } from "./adapter.js";
+export declare function isIdleSubscribeSenderAllowed(sender: {
+    isChild: boolean;
+}): boolean;
+export declare function isIdleSubscribeTargetAllowed(target: {
+    objectKind: RuntimeObjectKind;
+    hasReliableIdleSignal: boolean;
+}): boolean;
+export interface NotificationRecord {
+    notification_id: string;
+    origin: string;
+    queued_at: string;
+    content: string;
+}
+export interface NotificationQueue {
+    push(ownerKey: string, rec: {
+        origin: string;
+        content: string;
+        queuedAtMs: number;
+    }): void;
+    /**
+     * PHASE 7B: observe every push, WITHOUT consuming it. Returns an unsubscribe.
+     *
+     * The queue is the DURABLE record a host drains; this is the live signal a host can act on
+     * immediately. They are deliberately the same notice, correlated by `notification_id`: a listener
+     * that never fires (a crashed host, a host that reconnects later) loses nothing, because the entry
+     * is still queued for the drain -- which is what makes WS-15 §6.4's restart recovery possible at
+     * all. A listener must therefore NOT drain in response; the host acknowledges by draining.
+     *
+     * OPTIONAL, so a host that supplies its own `NotificationQueue` implementation still satisfies this
+     * interface. Its absence degrades to "drain only", never to a dropped notice.
+     */
+    subscribe?(listener: (ownerKey: string, rec: NotificationRecord) => void): () => void;
+    drain(ownerKey: string, max?: number): {
+        notifications: NotificationRecord[];
+        remaining: number;
+    };
+    pendingCount(ownerKey: string): number;
+}
+export declare function createNotificationQueue(): NotificationQueue;
+export interface PendingIdleSubscription {
+    messageId: string;
+    subscriberKey: string;
+    targetKey: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface IdleSubscriptionStore {
+    subscribe(sub: Omit<PendingIdleSubscription, "createdAt" | "expiresAt">, now: number): void;
+    fireIdle(targetKey: string, now: number, computeReducedStatus: (subscriberKey: string) => boolean, queue: NotificationQueue, originLabel: string): number;
+    sweepExpired(now: number): void;
+    pendingCount(targetKey: string): number;
+}
+export declare function createIdleSubscriptionStore(): IdleSubscriptionStore;

package/dist/messaging/inbound.d.ts

@@ -0,0 +1,39 @@
+import type { PermissionMode } from "../permissions/types.js";
+export type PermissionClassLabel = "prompts" | "bypasses" | "unknown";
+export type CrossSessionInbound = "accept" | "hold" | "refuse";
+export declare function classifyPermissionMode(mode: PermissionMode, opts: {
+    bypassAvailable: boolean;
+}): PermissionClassLabel;
+export declare function mapFromModeToPermissionClass(fromMode: "bypass" | "prompting" | undefined): PermissionClassLabel;
+export declare function defaultInboundResult(receiverClass: PermissionClassLabel, senderClass: PermissionClassLabel): "accept" | "hold";
+export interface InboundDecisionParams {
+    authenticated: boolean;
+    explicitSetting?: CrossSessionInbound;
+    receiverClass: PermissionClassLabel;
+    senderClass: PermissionClassLabel;
+}
+export declare function resolveInboundDecision(params: InboundDecisionParams): CrossSessionInbound;
+export interface HeldEntry {
+    messageId: string;
+    reason: string;
+    kind: "default" | "explicit";
+    heldAt: number;
+    expiresAt?: number;
+}
+export interface Mailbox {
+    hold(receiverKey: string, entry: HeldEntry): boolean;
+    accept(receiverKey: string): boolean;
+    releaseAccepted(receiverKey: string, n?: number): void;
+    heldCount(receiverKey: string): number;
+    acceptedCount(receiverKey: string): number;
+    listHeld(receiverKey: string): readonly HeldEntry[];
+    takeHeld(receiverKey: string, messageId: string): HeldEntry | undefined;
+    reevaluate(receiverKey: string, decide: (entry: HeldEntry) => CrossSessionInbound): Array<{
+        entry: HeldEntry;
+        next: CrossSessionInbound;
+    }>;
+    sweepExpired(receiverKey: string, now: number): HeldEntry[];
+}
+export declare function createMailbox(): Mailbox;
+export declare function buildDefaultHoldEntry(messageId: string, reason: string, now: number): HeldEntry;
+export declare function buildExplicitHoldEntry(messageId: string, reason: string, now: number): HeldEntry;

package/dist/messaging/index.d.ts

@@ -0,0 +1,15 @@
+export { serializeRuntimeAddress, createFakeMessagingRouterSeam, } from "./adapter.js";
+export type { RuntimeKind, RuntimeObjectKind, RuntimeAddress, ListedRuntimeObject, DeliveryOutcome, GlobalAgentMessage, RuntimeMessagingAdapter, MessagingRouterSeam, FakeMessagingRouterSeam, ChildLike, ChildLikeRecord, ChildLikeStatus, } from "./adapter.js";
+export { REFERENCE_RUNTIME_KIND, validateToField, buildSessionAddress, buildChildAddress, parseRuntimeAddress, sameAddress, } from "./addressing.js";
+export type { ToFieldValidation } from "./addressing.js";
+export { MAX_GLOBAL_MESSAGE_SIZE, DEFAULT_MESSAGE_TTL_MS, MAX_HOP_COUNT, RAPID_REPEAT_WINDOW_MS, HELD_INBOX_CAP, ACCEPTED_QUEUE_CAP, DEFAULT_HOLD_EXPIRY_MS, NOTIFY_IDLE_EXPIRY_MS, messageExceedsMaxSize, hopCountExceeded, delivered, queued, resumedAndDelivered, held, subscribed, deliveryUncertain, refused, ambiguous, notFound, unavailable, createLoopGuard, } from "./outcomes.js";
+export type { LoopGuard } from "./outcomes.js";
+export { childToListedRuntimeObject, resolveTarget } from "./resolution.js";
+export type { ResolutionInputs, ResolutionResult } from "./resolution.js";
+export { classifyPermissionMode, mapFromModeToPermissionClass, defaultInboundResult, resolveInboundDecision, createMailbox, buildDefaultHoldEntry, buildExplicitHoldEntry, } from "./inbound.js";
+export type { PermissionClassLabel, CrossSessionInbound, InboundDecisionParams, HeldEntry, Mailbox } from "./inbound.js";
+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 { 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

@@ -0,0 +1,118 @@
+import {
+  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,
+  listAgents2,
+  readNotifications2,
+  createMessagingRouter2
+} from "../index-51ysrfm8.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,
+  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,
+  NOTIFY_IDLE_EXPIRY_MS2 as NOTIFY_IDLE_EXPIRY_MS,
+  RAPID_REPEAT_WINDOW_MS2 as RAPID_REPEAT_WINDOW_MS,
+  REFERENCE_RUNTIME_KIND2 as REFERENCE_RUNTIME_KIND,
+  RESERVED_NOTIFICATION_KEY_PREFIX2 as RESERVED_NOTIFICATION_KEY_PREFIX,
+  ambiguous2 as ambiguous,
+  buildChildAddress2 as buildChildAddress,
+  buildDefaultHoldEntry2 as buildDefaultHoldEntry,
+  buildExplicitHoldEntry2 as buildExplicitHoldEntry,
+  buildSessionAddress2 as buildSessionAddress,
+  callerAddress2 as callerAddress,
+  childToListedRuntimeObject2 as childToListedRuntimeObject,
+  classifyPermissionMode2 as classifyPermissionMode,
+  createFakeMessagingRouterSeam2 as createFakeMessagingRouterSeam,
+  createIdleSubscriptionStore2 as createIdleSubscriptionStore,
+  createLoopGuard2 as createLoopGuard,
+  createMailbox2 as createMailbox,
+  createMessagingRouter2 as createMessagingRouter,
+  createMessagingRouterSeam2 as createMessagingRouterSeam,
+  createNotificationQueue2 as createNotificationQueue,
+  createSubscriberDirectory2 as createSubscriberDirectory,
+  defaultInboundResult2 as defaultInboundResult,
+  delivered2 as delivered,
+  deliveryUncertain2 as deliveryUncertain,
+  escapeAttributionAttribute2 as escapeAttributionAttribute,
+  escapeAttributionText2 as escapeAttributionText,
+  facetNotificationKey2 as facetNotificationKey,
+  held2 as held,
+  hopCountExceeded2 as hopCountExceeded,
+  isIdleSubscribeSenderAllowed2 as isIdleSubscribeSenderAllowed,
+  isIdleSubscribeTargetAllowed2 as isIdleSubscribeTargetAllowed,
+  isReservedNotificationKey2 as isReservedNotificationKey,
+  listAgents2 as listAgents,
+  mapFromModeToPermissionClass2 as mapFromModeToPermissionClass,
+  messageExceedsMaxSize2 as messageExceedsMaxSize,
+  notFound2 as notFound,
+  parseRuntimeAddress2 as parseRuntimeAddress,
+  queued2 as queued,
+  readNotifications2 as readNotifications,
+  refused2 as refused,
+  rememberBounded2 as rememberBounded,
+  resolveInboundDecision2 as resolveInboundDecision,
+  resolveTarget2 as resolveTarget,
+  resumedAndDelivered2 as resumedAndDelivered,
+  sameAddress2 as sameAddress,
+  sendMessage2 as sendMessage,
+  serializeRuntimeAddress2 as serializeRuntimeAddress,
+  subscribed2 as subscribed,
+  unavailable2 as unavailable,
+  validateToField2 as validateToField
+};

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,100 @@
+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;
+}
+/**
+ * WS-10 §10.2's line format for the one `listing` string.
+ *
+ * `export`ed for `../tools/messaging-handlers.ts` alone — NOT re-exported from this subpath's barrel,
+ * so it stays an internal seam rather than new published surface. The tool handler needs the SAME
+ * renderer this function already is: `listAgents` returns `{ listing, rows }` for a host that owns
+ * the deps, while the tool handler works through the address-centric port and has only rows, and a
+ * second formatter there would be a second answer to "what does the model see".
+ */
+export declare function formatListing(rows: readonly ListedRuntimeObject[]): 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/paths/project-key.d.ts

@@ -1 +1,3 @@
+export declare const TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
+export declare function isVendorCompliantProjectKey(key: string): boolean;
 export declare function transcriptProjectKey(absPath: string): string;