@yanlinglabs/winter-agent-sdk 0.0.2 → 0.0.3

package/dist/messaging/index.js

@@ -56,7 +56,7 @@ import {
   listAgents2,
   readNotifications2,
   createMessagingRouter2
-} from "../index-h1tryj38.js";
+} from "../index-51ysrfm8.js";
 export {
   ACCEPTED_QUEUE_CAP2 as ACCEPTED_QUEUE_CAP,
   AGENT_MESSAGE_TAG2 as AGENT_MESSAGE_TAG,

package/dist/messaging/router.d.ts

@@ -63,6 +63,16 @@ 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;
 }

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;

package/dist/tools/accept.d.ts

@@ -0,0 +1,39 @@
+/** 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>;
+/**
+ * `ReadNotifications` takes the empty object, and only the empty object (ruling P-4).
+ *
+ * The Winter runtime's executor used to accept stray fields on the reasoning that an inert extra is
+ * not a reason to fail an otherwise-harmless call. That reasoning is right about HARM and wrong
+ * about SCHEMAS: a model that got away with `{ limit: 5 }` here has been told, by the runtime's own
+ * silence, that a `limit` exists.
+ */
+export declare function acceptNativeReadNotificationsArgs(input: unknown): NativeArgsResult<Record<string, never>>;
+/**
+ * WS-10 §10.1: "summary?: derived from first message line when absent; truncated when overlong."
+ *
+ * NEVER a validation error — a computed value, or absent when there is nothing to derive from (the
+ * pure-idle-subscription case, whose message is empty by construction).
+ */
+export declare function deriveSendMessageSummary(rawSummary: string | undefined, message: string): string | undefined;

package/dist/tools/advisor.d.ts

@@ -0,0 +1,106 @@
+import type { SessionKey, SessionStore } from "../store/session-store.js";
+import type { WinterToolHandler } from "./messaging-handlers.js";
+/**
+ * One raw entry of a session's transcript — deliberately narrower/speech-shaped (who said what) than
+ * any host's own provider message type, which additionally carries structured content blocks for
+ * wire purposes this assembler has no need of.
+ */
+export interface TranscriptEntry {
+    role: "user" | "assistant" | "tool";
+    text: string;
+}
+/**
+ * `getEntries` may be SYNCHRONOUS or async. The Winter runtime's real source is a live in-memory
+ * array captured by reference from the round loop (synchronous, and it must stay that way — a
+ * snapshot taken at wiring time would be empty forever); a host reading a durable transcript off
+ * disk needs the promise. The union is what lets one factory serve both.
+ */
+export interface TranscriptSource {
+    getEntries(): TranscriptEntry[] | Promise<TranscriptEntry[]>;
+}
+export interface AdvisorReviewerRequest {
+    messages: ReadonlyArray<{
+        role: "user" | "assistant" | "tool";
+        content: string;
+    }>;
+}
+export interface AdvisorReviewerTurn {
+    kind: string;
+    text?: string;
+}
+export interface AdvisorReviewer {
+    generate(input: AdvisorReviewerRequest): Promise<AdvisorReviewerTurn>;
+}
+/**
+ * Resolves BOTH the provider to call and the model id the result must report, TOGETHER: WS-06 §4's
+ * result shape pins `model: string` as required, but a provider interface has no `model` field to
+ * read back — whatever backs the reviewer capability must hand back the model id alongside the
+ * provider instance it resolved, in ONE seam, rather than two seams that could disagree.
+ */
+export interface ResolvedReviewer {
+    provider: AdvisorReviewer;
+    model: string;
+}
+/** `undefined` is the "no reviewer resolvable" case — WS-06 §4's ordinary tool error, never a throw. */
+export type ReviewerResolver = () => ResolvedReviewer | undefined;
+export interface AdvisorToolDeps {
+    transcriptSource: TranscriptSource;
+    resolveReviewer: ReviewerResolver;
+    /** Injectable so a host can pin the truncation boundary without a multi-KB fixture transcript. */
+    maxChars?: number;
+}
+export declare const ADVISOR_DEFAULT_MAX_CHARS = 20000;
+/**
+ * RULING R3-3: "the assembler enforces the enforceable floor now — provider-opaque state
+ * (encrypted_content, signatures, reasoning items) is NEVER included."
+ *
+ * `thinking` and `redacted_thinking` are in the list because a probe fed both to a scripted reviewer
+ * as literal transcript text and both reached the wire verbatim, payload included, while the
+ * original three were correctly stripped. WS-06 §4's constraint reads "provider-opaque state", not
+ * "these three keys", and `redacted_thinking.data` is opaque by name.
+ *
+ * THE COST IS REAL AND ACCEPTED: "thinking" is an ordinary English word, so a review line that
+ * merely USES it ("I was thinking about the schema") is dropped along with the ones that carry a
+ * key. That is this function's declared posture — drop the whole line, never partially redact, fail
+ * toward the reviewer seeing less — and the price is one line of context in an advisory channel
+ * against a class of leak the transcript has no other guard for.
+ */
+export declare const OPAQUE_MARKERS: readonly ["encrypted_content", "reasoning_item", "signature", "thinking", "redacted_thinking"];
+export declare function stripOpaqueMarkers(text: string): string;
+/**
+ * Keeps the transcript TAIL (recent turns are what advice needs) and reports `truncated: true` only
+ * when something was actually clipped. Opaque-marker stripping runs PER ENTRY before truncation is
+ * measured, so a kept entry is always a whole, already-cleaned entry — truncation never bisects one,
+ * and a 4-KB `signature:` line never evicts the real conversation that came before it.
+ */
+export declare function assembleReviewerMessages(entries: readonly TranscriptEntry[], maxChars?: number): {
+    messages: Array<{
+        role: "user" | "assistant" | "tool";
+        content: string;
+    }>;
+    truncated: boolean;
+};
+/**
+ * NO CACHE (WS-06 §4's closing line: "the advisor and the auto-mode classifier are separate routes
+ * and MUST NOT share a verdict cache"). Every call re-resolves the reviewer, re-assembles the
+ * transcript, and re-generates from scratch; nothing in this module is memoized, so there is nothing
+ * here that COULD be shared with a classifier's verdict cache even by accident.
+ */
+export declare function createAdvisorToolHandler(deps: AdvisorToolDeps): WinterToolHandler;
+/**
+ * A `TranscriptSource` over the DURABLE transcript of one session.
+ *
+ * For a host that does not hold the live turn array — the router package, or any consumer wiring the
+ * advisor outside an engine's own closure. The Winter runtime keeps its in-memory source (the live
+ * `messages` array, captured by reference), because a resumed session's file and its live turns are
+ * not the same conversation until the turn ends.
+ *
+ * Reads through the pinned `SessionStore` interface so a host may inject an in-memory one; the
+ * default is the filesystem store over the resolved Winter home. A missing transcript is NO ENTRIES,
+ * never a throw: the advisor's whole posture is that an unavailable reviewer context degrades to an
+ * ordinary tool error rather than blocking the turn.
+ */
+export declare function transcriptSourceForSessionKey(key: SessionKey, opts?: {
+    store?: SessionStore;
+    winterHome?: string;
+}): TranscriptSource;

package/dist/tools/definitions.d.ts

@@ -0,0 +1,31 @@
+import { type JsonSchemaObject } from "./schemas.js";
+export interface WinterToolDefinition {
+    /** The BARE tool name: `send_message`, `list_agents`, `read_notifications`, `advisor`. */
+    readonly toolName: string;
+    /** The official SDK's built-in name for the same tool — the alias key a host binds under. */
+    readonly builtinName?: string;
+    readonly description: string;
+    /** Tool-Search terms, for a host that defers this tool. Advertised nowhere when it does not. */
+    readonly searchHint?: string;
+    readonly inputSchema: JsonSchemaObject;
+    readonly outputSchema?: JsonSchemaObject;
+    readonly annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        openWorldHint?: boolean;
+        idempotentHint?: boolean;
+        title?: string;
+    };
+    /**
+     * What the CALL does, not where the descriptor came from. `advisor` is `"mcp"` because it sends
+     * conversation content to a provider in the session's own trust domain (the same class of egress
+     * as the worker model's own requests), even though it registers as a bare built-in name.
+     */
+    readonly permissionClass: "messaging" | "mcp";
+}
+export declare const SEND_MESSAGE_DEFINITION: WinterToolDefinition;
+export declare const LIST_AGENTS_DEFINITION: WinterToolDefinition;
+export declare const READ_NOTIFICATIONS_DEFINITION: WinterToolDefinition;
+export declare const ADVISOR_DEFINITION: WinterToolDefinition;
+/** The four, in the order a host registers them. */
+export declare const WINTER_DEFAULT_TOOL_DEFINITIONS: readonly [typeof SEND_MESSAGE_DEFINITION, typeof LIST_AGENTS_DEFINITION, typeof READ_NOTIFICATIONS_DEFINITION, typeof ADVISOR_DEFINITION];

package/dist/tools/index.d.ts

@@ -0,0 +1,14 @@
+export { SEND_MESSAGE_TO_MAX, SEND_MESSAGE_SUMMARY_MAX, LIST_AGENTS_FIELD_MAX, NATIVE_SEND_MESSAGE_SCHEMA, NATIVE_LIST_AGENTS_SCHEMA, NATIVE_LIST_AGENTS_OUTPUT_SCHEMA, NATIVE_READ_NOTIFICATIONS_SCHEMA, NATIVE_READ_NOTIFICATIONS_OUTPUT_SCHEMA, NATIVE_ADVISOR_SCHEMA, NATIVE_ADVISOR_OUTPUT_SCHEMA, } from "./schemas.js";
+export type { JsonSchemaObject } from "./schemas.js";
+export { SEND_MESSAGE_DEFINITION, LIST_AGENTS_DEFINITION, READ_NOTIFICATIONS_DEFINITION, ADVISOR_DEFINITION, WINTER_DEFAULT_TOOL_DEFINITIONS } from "./definitions.js";
+export type { WinterToolDefinition } from "./definitions.js";
+export { acceptNativeSendMessageArgs, acceptNativeListAgentsArgs, acceptNativeReadNotificationsArgs, deriveSendMessageSummary } from "./accept.js";
+export type { NativeSendMessageArgs, NativeListAgentsArgs, NativeArgsResult } from "./accept.js";
+export { messagingToolPortFromRuntimeDeps, callerAddress } from "./port.js";
+export type { MessagingToolPort } from "./port.js";
+export { createMessagingToolHandlers, toolUseIdFromExtra, VENDOR_TOOL_USE_ID_META_KEY } from "./messaging-handlers.js";
+export type { WinterToolCaller, WinterToolResult, WinterToolHandler, MessagingToolHandlers } from "./messaging-handlers.js";
+export { ADVISOR_DEFAULT_MAX_CHARS, OPAQUE_MARKERS, stripOpaqueMarkers, assembleReviewerMessages, createAdvisorToolHandler, transcriptSourceForSessionKey } from "./advisor.js";
+export type { TranscriptEntry, TranscriptSource, AdvisorReviewerRequest, AdvisorReviewerTurn, AdvisorReviewer, ResolvedReviewer, ReviewerResolver, AdvisorToolDeps } from "./advisor.js";
+export type { RuntimeAddress, ListedRuntimeObject, SendMessageResult, NotificationRecord, MessagingRuntimeDeps } from "../messaging/index.js";
+export type { SessionKey, SessionStore } from "../store/session-store.js";

package/dist/tools/index.js

@@ -0,0 +1,438 @@
+import {
+  validateToField2,
+  callerAddress2,
+  sendMessage2,
+  formatListing,
+  listAgents2
+} from "../index-51ysrfm8.js";
+import {
+  resolveWinterHome2,
+  WinterCompatibilitySessionStore2
+} from "../index-9e98bg1r.js";
+
+// src/tools/schemas.ts
+var SEND_MESSAGE_TO_MAX = 300;
+var SEND_MESSAGE_SUMMARY_MAX = 200;
+var LIST_AGENTS_FIELD_MAX = 256;
+var NATIVE_SEND_MESSAGE_SCHEMA = {
+  type: "object",
+  properties: {
+    to: { type: "string", maxLength: SEND_MESSAGE_TO_MAX, description: 'no newline, no "*" broadcast' },
+    message: { type: "string", description: 'required; defaults "" for pure idle subscription' },
+    summary: { type: "string", maxLength: SEND_MESSAGE_SUMMARY_MAX },
+    notify_when_idle: { type: "boolean", description: "one-shot; main conversation -> same-machine session only" }
+  },
+  required: ["to", "message"]
+};
+var NATIVE_LIST_AGENTS_SCHEMA = {
+  type: "object",
+  properties: {
+    channel: { type: "string", maxLength: LIST_AGENTS_FIELD_MAX, description: "reserved" },
+    q: { type: "string", maxLength: LIST_AGENTS_FIELD_MAX, description: "reserved" }
+  }
+};
+var NATIVE_LIST_AGENTS_OUTPUT_SCHEMA = {
+  type: "object",
+  properties: { listing: { type: "string" } },
+  required: ["listing"],
+  additionalProperties: false
+};
+var NATIVE_READ_NOTIFICATIONS_SCHEMA = {
+  type: "object",
+  properties: {},
+  additionalProperties: false
+};
+var NATIVE_READ_NOTIFICATIONS_OUTPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    notifications: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          notification_id: { type: "string" },
+          origin: { type: "string" },
+          queued_at: { type: "string" },
+          content: { type: "string" }
+        }
+      }
+    },
+    remaining: { type: "number" }
+  }
+};
+var NATIVE_ADVISOR_SCHEMA = {
+  type: "object",
+  properties: {}
+};
+var NATIVE_ADVISOR_OUTPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    advice: { type: "string" },
+    model: { type: "string" },
+    truncated: { type: "boolean" }
+  },
+  required: ["advice", "model"]
+};
+// src/tools/definitions.ts
+var SEND_MESSAGE_DEFINITION = {
+  toolName: "send_message",
+  builtinName: "SendMessage",
+  description: "Resolves `to` against child registry, teammates, live peer registry; steers a running child, resumes an addressable completed/stopped child, wakes an idle live peer, queues for a running peer; never cold-resumes an arbitrary exited transcript.",
+  searchHint: "send message agent session peer child steer resume notify idle",
+  inputSchema: NATIVE_SEND_MESSAGE_SCHEMA,
+  permissionClass: "messaging"
+};
+var LIST_AGENTS_DEFINITION = {
+  toolName: "list_agents",
+  builtinName: "ListAgents",
+  description: "Names/refs, activity/status, addressing identity for children, teammates, eligible live peers; never an enumeration of exited transcripts.",
+  searchHint: "list agents sessions peers children roster reachable",
+  inputSchema: NATIVE_LIST_AGENTS_SCHEMA,
+  outputSchema: NATIVE_LIST_AGENTS_OUTPUT_SCHEMA,
+  permissionClass: "messaging"
+};
+var READ_NOTIFICATIONS_DEFINITION = {
+  toolName: "read_notifications",
+  builtinName: "ReadNotifications",
+  description: "Drains Winter's own global-messaging notification queue ([WS-10]).",
+  inputSchema: NATIVE_READ_NOTIFICATIONS_SCHEMA,
+  outputSchema: NATIVE_READ_NOTIFICATIONS_OUTPUT_SCHEMA,
+  permissionClass: "messaging"
+};
+var ADVISOR_DEFINITION = {
+  toolName: "advisor",
+  builtinName: "advisor",
+  description: "Consults a stronger reviewer model over this session's own conversation/tool history (provider-opaque state such as encrypted_content is never included). Reviewer unavailable/timeout -> ordinary tool error; never blocks the turn.",
+  inputSchema: NATIVE_ADVISOR_SCHEMA,
+  outputSchema: NATIVE_ADVISOR_OUTPUT_SCHEMA,
+  permissionClass: "mcp"
+};
+var WINTER_DEFAULT_TOOL_DEFINITIONS = [
+  SEND_MESSAGE_DEFINITION,
+  LIST_AGENTS_DEFINITION,
+  READ_NOTIFICATIONS_DEFINITION,
+  ADVISOR_DEFINITION
+];
+// src/tools/accept.ts
+var SEND_MESSAGE_FIELDS = new Set(Object.keys(NATIVE_SEND_MESSAGE_SCHEMA.properties ?? {}));
+var LIST_AGENTS_FIELDS = new Set(Object.keys(NATIVE_LIST_AGENTS_SCHEMA.properties ?? {}));
+function unknownFields(record, allowed) {
+  return Object.keys(record).filter((key) => !allowed.has(key));
+}
+function asRecord(input) {
+  return typeof input === "object" && input !== null && !Array.isArray(input) ? input : undefined;
+}
+function acceptNativeSendMessageArgs(input) {
+  const record = asRecord(input);
+  if (record === undefined)
+    return { ok: false, reason: "expected an object of SendMessage arguments" };
+  const extra = unknownFields(record, SEND_MESSAGE_FIELDS);
+  if (extra.length > 0)
+    return { ok: false, reason: `unknown argument(s): ${extra.join(", ")}` };
+  const to = record["to"];
+  const validated = validateToField2(to);
+  if (!validated.ok)
+    return { ok: false, reason: validated.message };
+  const message = record["message"];
+  if (typeof message !== "string")
+    return { ok: false, reason: "`message` is required and must be a string (an empty string is a pure idle subscription)" };
+  const notify = record["notify_when_idle"];
+  if (notify !== undefined && typeof notify !== "boolean")
+    return { ok: false, reason: "`notify_when_idle` must be a boolean" };
+  if (message.length === 0 && notify !== true) {
+    return { ok: false, reason: "`message` may only be empty when `notify_when_idle` is true (a pure idle subscription, WS-10 §10.1)" };
+  }
+  const summary = record["summary"];
+  if (summary !== undefined && typeof summary !== "string")
+    return { ok: false, reason: "`summary` must be a string" };
+  const capped = summary === undefined ? undefined : summary.slice(0, SEND_MESSAGE_SUMMARY_MAX);
+  return {
+    ok: true,
+    args: {
+      to,
+      message,
+      ...capped === undefined ? {} : { summary: capped },
+      ...notify === undefined ? {} : { notify_when_idle: notify }
+    }
+  };
+}
+function acceptNativeListAgentsArgs(input) {
+  if (input === undefined || input === null)
+    return { ok: true, args: {} };
+  const record = asRecord(input);
+  if (record === undefined)
+    return { ok: false, reason: "expected an object of ListAgents arguments" };
+  const extra = unknownFields(record, LIST_AGENTS_FIELDS);
+  if (extra.length > 0)
+    return { ok: false, reason: `unknown argument(s): ${extra.join(", ")}` };
+  for (const field of ["channel", "q"]) {
+    const value = record[field];
+    if (value !== undefined && (typeof value !== "string" || value.length > LIST_AGENTS_FIELD_MAX)) {
+      return { ok: false, reason: `\`${field}\` must be a string of at most ${LIST_AGENTS_FIELD_MAX} characters` };
+    }
+  }
+  return {
+    ok: true,
+    args: {
+      ...typeof record["channel"] === "string" ? { channel: record["channel"] } : {},
+      ...typeof record["q"] === "string" ? { q: record["q"] } : {}
+    }
+  };
+}
+function acceptNativeReadNotificationsArgs(input) {
+  if (input === undefined || input === null)
+    return { ok: true, args: {} };
+  const record = asRecord(input);
+  if (record === undefined)
+    return { ok: false, reason: "expected an empty object of ReadNotifications arguments" };
+  const extra = Object.keys(record);
+  if (extra.length > 0)
+    return { ok: false, reason: `unknown argument(s): ${extra.join(", ")} (ReadNotifications takes no arguments)` };
+  return { ok: true, args: {} };
+}
+function deriveSendMessageSummary(rawSummary, message) {
+  if (rawSummary !== undefined)
+    return rawSummary.slice(0, SEND_MESSAGE_SUMMARY_MAX);
+  const firstLine = (message.split(`
+`)[0] ?? "").trim();
+  if (firstLine.length === 0)
+    return;
+  return firstLine.slice(0, SEND_MESSAGE_SUMMARY_MAX);
+}
+// src/tools/port.ts
+var fallbackCounter = 0;
+function fallbackToolUseId() {
+  return `no-tool-use-id-${++fallbackCounter}-${Date.now()}`;
+}
+function callerFromAddress(from, originToolCallId) {
+  return {
+    sessionId: from.parentWinterSessionId ?? from.winterSessionId,
+    ...from.objectKind === "agent" && from.childId !== undefined ? { agentId: from.childId } : {},
+    toolUseId: originToolCallId ?? fallbackToolUseId()
+  };
+}
+function messagingToolPortFromRuntimeDeps(deps) {
+  return {
+    async sendDetailed(request) {
+      const caller = callerFromAddress(request.from, request.originToolCallId);
+      return sendMessage2(deps, caller, {
+        to: request.to,
+        message: request.body,
+        ...request.summary === undefined ? {} : { summary: request.summary },
+        ...request.notifyWhenIdle === undefined ? {} : { notify_when_idle: request.notifyWhenIdle }
+      });
+    },
+    async listReachable(scope) {
+      const { rows } = await listAgents2(deps, { sessionId: scope.from.parentWinterSessionId ?? scope.from.winterSessionId }, {});
+      return rows;
+    },
+    readNotifications(sessionId) {
+      return deps.notifications.drain(sessionId);
+    }
+  };
+}
+// src/tools/messaging-handlers.ts
+var VENDOR_TOOL_USE_ID_META_KEY = "claudecode/toolUseId";
+function toolUseIdFromExtra(extra) {
+  if (typeof extra !== "object" || extra === null)
+    return;
+  const meta = extra._meta;
+  if (typeof meta !== "object" || meta === null)
+    return;
+  const id = meta[VENDOR_TOOL_USE_ID_META_KEY];
+  return typeof id === "string" && id.length > 0 ? id : undefined;
+}
+var MODEL_FACING_FAILURES = new Set(["refused", "ambiguous", "not_found", "unavailable"]);
+function text(body, isError = false) {
+  return { text: body, ...isError ? { isError: true } : {} };
+}
+function describe(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function guarded(what, run) {
+  try {
+    return await run();
+  } catch (err) {
+    return text(`Error: ${what}: ${describe(err)}`, true);
+  }
+}
+function createMessagingToolHandlers(port, caller) {
+  const identity = () => typeof caller === "function" ? caller() : caller;
+  return {
+    async sendMessage(rawArgs, extra) {
+      const accepted = acceptNativeSendMessageArgs(rawArgs);
+      if (!accepted.ok)
+        return text(accepted.reason, true);
+      const bound = identity();
+      const perCall = toolUseIdFromExtra(extra);
+      const who = perCall === undefined ? bound : { ...bound, toolUseId: perCall };
+      const summary = deriveSendMessageSummary(accepted.args.summary, accepted.args.message);
+      return guarded("SendMessage could not reach the messaging system", async () => {
+        const result = await port.sendDetailed({
+          from: callerAddress2(who),
+          to: accepted.args.to,
+          body: accepted.args.message,
+          ...summary === undefined ? {} : { summary },
+          ...accepted.args.notify_when_idle === undefined ? {} : { notifyWhenIdle: accepted.args.notify_when_idle },
+          ...who.toolUseId === undefined ? {} : { originToolCallId: who.toolUseId }
+        });
+        const payload = result.notify === undefined ? result.outcome : { ...result.outcome, notify: result.notify };
+        return text(JSON.stringify(payload), MODEL_FACING_FAILURES.has(result.outcome.status));
+      });
+    },
+    async listAgents(rawArgs) {
+      const accepted = acceptNativeListAgentsArgs(rawArgs);
+      if (!accepted.ok)
+        return text(accepted.reason, true);
+      return guarded("ListAgents could not reach the messaging system", async () => {
+        const rows = await port.listReachable({ from: callerAddress2(identity()) });
+        return text(JSON.stringify({ listing: formatListing(rows) }));
+      });
+    },
+    async readNotifications(rawArgs) {
+      const accepted = acceptNativeReadNotificationsArgs(rawArgs);
+      if (!accepted.ok)
+        return text(accepted.reason, true);
+      return guarded("ReadNotifications could not drain the notification queue", () => {
+        const { notifications, remaining } = port.readNotifications(identity().sessionId);
+        return text(JSON.stringify({ notifications, remaining }));
+      });
+    }
+  };
+}
+// src/tools/advisor.ts
+var ADVISOR_DEFAULT_MAX_CHARS = 20000;
+var OPAQUE_MARKERS = ["encrypted_content", "reasoning_item", "signature", "thinking", "redacted_thinking"];
+function stripOpaqueMarkers(text) {
+  return text.split(`
+`).filter((line) => !OPAQUE_MARKERS.some((marker) => line.toLowerCase().includes(marker))).join(`
+`);
+}
+function assembleReviewerMessages(entries, maxChars = ADVISOR_DEFAULT_MAX_CHARS) {
+  const cleaned = entries.map((e) => ({ role: e.role, text: stripOpaqueMarkers(e.text) }));
+  const kept = [];
+  let total = 0;
+  let truncated = false;
+  for (let i = cleaned.length - 1;i >= 0; i--) {
+    const entry = cleaned[i];
+    if (!entry)
+      continue;
+    if (total + entry.text.length > maxChars) {
+      if (kept.length === 0) {
+        kept.unshift({ role: entry.role, text: entry.text.slice(Math.max(0, entry.text.length - maxChars)) });
+      }
+      truncated = true;
+      break;
+    }
+    kept.unshift(entry);
+    total += entry.text.length;
+  }
+  return { messages: kept.map((e) => ({ role: e.role, content: e.text })), truncated };
+}
+function error(body) {
+  return { text: body, isError: true };
+}
+function describe2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function createAdvisorToolHandler(deps) {
+  return async () => {
+    let reviewer;
+    try {
+      reviewer = deps.resolveReviewer();
+    } catch (err) {
+      return error(`Error: advisor failed to resolve a reviewer model: ${describe2(err)}`);
+    }
+    if (!reviewer) {
+      return error(`Error: advisor is unavailable -- no reviewer model is resolvable in this session's provider catalog (WS-06 §4: "Reviewer unavailable/timeout -> ordinary tool error; never blocks the turn").`);
+    }
+    let entries;
+    try {
+      entries = await deps.transcriptSource.getEntries();
+    } catch (err) {
+      return error(`Error: advisor failed to assemble the session transcript: ${describe2(err)}`);
+    }
+    const { messages, truncated } = assembleReviewerMessages(entries, deps.maxChars ?? ADVISOR_DEFAULT_MAX_CHARS);
+    let turn;
+    try {
+      turn = await reviewer.provider.generate({ messages });
+    } catch (err) {
+      return error(`Error: advisor's reviewer model failed: ${describe2(err)}`);
+    }
+    if (turn.kind !== "text" || typeof turn.text !== "string") {
+      return error(`Error: advisor's reviewer model returned a non-text response (kind: "${turn.kind}"); advisor has no tool-execution loop to act on it.`);
+    }
+    return { text: JSON.stringify({ advice: turn.text, model: reviewer.model, ...truncated ? { truncated: true } : {} }) };
+  };
+}
+function entryText(content) {
+  if (typeof content === "string")
+    return content;
+  if (!Array.isArray(content))
+    return;
+  const parts = content.flatMap((block) => {
+    if (typeof block !== "object" || block === null)
+      return [];
+    const record = block;
+    return record.type === "text" && typeof record.text === "string" ? [record.text] : [];
+  });
+  return parts.length === 0 ? undefined : parts.join(`
+`);
+}
+function toTranscriptEntry(entry) {
+  if (entry.type !== "user" && entry.type !== "assistant")
+    return;
+  const message = entry["message"];
+  if (typeof message !== "object" || message === null)
+    return;
+  const text = entryText(message.content);
+  if (text === undefined || text.length === 0)
+    return;
+  return { role: entry.type, text };
+}
+function transcriptSourceForSessionKey(key, opts = {}) {
+  const store = opts.store ?? new WinterCompatibilitySessionStore2({ winterHome: opts.winterHome ?? resolveWinterHome2() });
+  return {
+    async getEntries() {
+      const entries = await store.load(key);
+      if (entries === null)
+        return [];
+      return entries.flatMap((entry) => {
+        const mapped = toTranscriptEntry(entry);
+        return mapped === undefined ? [] : [mapped];
+      });
+    }
+  };
+}
+export {
+  ADVISOR_DEFAULT_MAX_CHARS,
+  ADVISOR_DEFINITION,
+  LIST_AGENTS_DEFINITION,
+  LIST_AGENTS_FIELD_MAX,
+  NATIVE_ADVISOR_OUTPUT_SCHEMA,
+  NATIVE_ADVISOR_SCHEMA,
+  NATIVE_LIST_AGENTS_OUTPUT_SCHEMA,
+  NATIVE_LIST_AGENTS_SCHEMA,
+  NATIVE_READ_NOTIFICATIONS_OUTPUT_SCHEMA,
+  NATIVE_READ_NOTIFICATIONS_SCHEMA,
+  NATIVE_SEND_MESSAGE_SCHEMA,
+  OPAQUE_MARKERS,
+  READ_NOTIFICATIONS_DEFINITION,
+  SEND_MESSAGE_DEFINITION,
+  SEND_MESSAGE_SUMMARY_MAX,
+  SEND_MESSAGE_TO_MAX,
+  VENDOR_TOOL_USE_ID_META_KEY,
+  WINTER_DEFAULT_TOOL_DEFINITIONS,
+  acceptNativeListAgentsArgs,
+  acceptNativeReadNotificationsArgs,
+  acceptNativeSendMessageArgs,
+  assembleReviewerMessages,
+  callerAddress2 as callerAddress,
+  createAdvisorToolHandler,
+  createMessagingToolHandlers,
+  deriveSendMessageSummary,
+  messagingToolPortFromRuntimeDeps,
+  stripOpaqueMarkers,
+  toolUseIdFromExtra,
+  transcriptSourceForSessionKey
+};