@yanlinglabs/winter-agent-sdk 0.0.2 → 0.0.3

package/dist/tools/messaging-handlers.d.ts

@@ -0,0 +1,52 @@
+import { type MessagingToolPort } from "./port.js";
+/**
+ * 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 the messaging core — 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, and it is OPTIONAL because a host that
+ * cannot supply one exists: it gets no dedupe, stated at the door rather than faked with a
+ * stable-looking key that would make two different messages one.
+ */
+export interface WinterToolCaller {
+    sessionId: string;
+    agentId?: string;
+    toolUseId?: string;
+}
+/** The host-neutral tool result: one text body, plus whether the model should read it as a failure. */
+export interface WinterToolResult {
+    text: string;
+    isError?: boolean;
+}
+export type WinterToolHandler = (args: unknown, extra?: unknown) => Promise<WinterToolResult>;
+export interface MessagingToolHandlers {
+    sendMessage: WinterToolHandler;
+    listAgents: WinterToolHandler;
+    readNotifications: WinterToolHandler;
+}
+/**
+ * WS-10 §12's RETRY KEY, on the official branch — and it exists, which was not known until it was
+ * measured.
+ *
+ * §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.
+ *
+ * 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 declare function createMessagingToolHandlers(port: MessagingToolPort, caller: WinterToolCaller | (() => WinterToolCaller)): MessagingToolHandlers;

package/dist/tools/port.d.ts

@@ -0,0 +1,39 @@
+import { callerAddress, type ListedRuntimeObject, type MessagingRuntimeDeps, type NotificationRecord, type RuntimeAddress, type SendMessageResult } from "../messaging/index.js";
+export interface MessagingToolPort {
+    sendDetailed(request: {
+        from: RuntimeAddress;
+        to: string;
+        body: string;
+        summary?: string;
+        notifyWhenIdle?: boolean;
+        originToolCallId?: string;
+    }): Promise<SendMessageResult>;
+    listReachable(scope: {
+        from: RuntimeAddress;
+    }): Promise<ListedRuntimeObject[]>;
+    readNotifications(sessionId: string): {
+        notifications: NotificationRecord[];
+        remaining: number;
+    };
+}
+/**
+ * The Winter-runtime side of the port: `MessagingRuntimeDeps` in, `MessagingToolPort` out.
+ *
+ * `listReachable` goes through the core's own `listAgents` rather than straight to
+ * `deps.adapter.listReachable`, because the core is where the self-exclusion rule lives (WS-10
+ * §10.2) — so the handlers never filter again (they are the layer least able to know the caller's
+ * real address).
+ *
+ * WHAT THAT FILTER ACTUALLY EXCLUDES, stated precisely rather than as "never yourself" (whole-branch
+ * fix wave). The `from` address is resolved to its OWNING SESSION before the core is asked, and the
+ * core drops the row matching that session address. For a top-level caller those are the same thing
+ * and the rule reads as written. For a CHILD caller (`agent:<parent>:<child>`) they are not: the
+ * scope collapses to `session:<parent>`, so the child's OWN `agent:` row can still appear in the
+ * listing it gets back. The router's handle filters the same way, by the address it was scoped with.
+ *
+ * Pre-existing on both branches and left alone here deliberately — this round changed no behaviour,
+ * and the fix belongs where the resolution happens, not in a re-filter bolted onto the port.
+ * Ledgered for the 0.0.4 patch wave.
+ */
+export declare function messagingToolPortFromRuntimeDeps(deps: MessagingRuntimeDeps): MessagingToolPort;
+export { callerAddress };

package/dist/tools/schemas.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The self-describing shape a tool schema is stored and served as.
+ *
+ * Deliberately structural and permissive rather than a full JSON Schema type: neither host validates
+ * model input against these at all (the Winter registry's own type is explicitly "self-describing…
+ * not a validator" — the ACCEPTORS in `accept.ts` are what enforce the contract). What matters is
+ * that the advertised bytes are one object, in one place.
+ */
+export interface JsonSchemaObject {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: readonly string[];
+    additionalProperties?: boolean;
+}
+/** WS-10 §10.1's bounds. `to`'s own limit is the messaging 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: JsonSchemaObject;
+export declare const NATIVE_LIST_AGENTS_SCHEMA: JsonSchemaObject;
+/**
+ * WS-10 §10.2: "`ListAgents` output is EXACTLY `{ listing: string }`."
+ *
+ * "Exactly" is spelled `additionalProperties: false` here, which neither former copy said out loud
+ * (both merely listed the one property). It is the whole content of §10.2's sentence, and it is the
+ * half a reader of the schema alone would otherwise have to take on trust.
+ */
+export declare const NATIVE_LIST_AGENTS_OUTPUT_SCHEMA: JsonSchemaObject;
+/** WS-06 §3.6: the ordinary call is `{}` and nothing else. */
+export declare const NATIVE_READ_NOTIFICATIONS_SCHEMA: JsonSchemaObject;
+/**
+ * The drained PAGE, not one notification: the pinned vendor shape is an ARRAY per call plus what is
+ * left behind, so a model that drains knows whether to drain again.
+ */
+export declare const NATIVE_READ_NOTIFICATIONS_OUTPUT_SCHEMA: JsonSchemaObject;
+/**
+ * WS-06 §4: input is `{}` — the runtime forwards the session's own history; no model-supplied
+ * parameters.
+ *
+ * NO `additionalProperties` KEY, DELIBERATELY. Neither host validates model input against a JSON
+ * Schema, so the keyword would be decorative — and the posture is applied uniformly across the
+ * parameterless tools rather than declared on one and not the others. The ACCEPTOR is where "no
+ * more" is actually enforced (ruling P-4), and it is enforced for `read_notifications` too, whose
+ * schema does carry the keyword because its pinned vendor shape does.
+ */
+export declare const NATIVE_ADVISOR_SCHEMA: JsonSchemaObject;
+export declare const NATIVE_ADVISOR_OUTPUT_SCHEMA: JsonSchemaObject;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION: string;

package/package.json

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