@wakeshift/sdk 0.3.0 → 0.4.0

package/dist/events.js

@@ -11,8 +11,9 @@ import { McpError } from "@modelcontextprotocol/sdk/types.js";
 import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
 import { objectFromShape, safeParse } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import { WakeshiftError } from "./errors.js";
-import { EXTENSION_KEY, HEADER_MISMATCH, INTERNAL_ERROR, INVALID_PARAMS, LEGACY_KEY, NAME_HEADER, RESULT_TYPE, codesFor, dialectOf, headerValue, } from "./spec.js";
-import { applyAddition } from "./wakeshift.js";
+import { EXTENSION_KEY, HEADER_MISMATCH, INTERNAL_ERROR, INVALID_PARAMS, TOP_LEVEL_KEY, NAME_HEADER, RESULT_TYPE, codesFor, dialectOf, headerValue, } from "./spec.js";
+import { toolCallOf } from "./wakeshift.js";
+import { Attached, toolArgs } from "./toolcall.js";
 const nameRE = /^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*){0,4}$/;
 const argNameRE = /^[a-z][a-z0-9_]{0,63}$/;
 // jsonSchemaOf is a zod schema as JSON Schema, without $schema (Wakeshift
@@ -115,7 +116,7 @@ export class WakeEvent {
             // ev/<name>/{a}/{b}: one segment per required scalar argument; an
             // optional one filters on the payload field of its name.
             const segs = ["ev", name];
-            filter = filter ?? {};
+            filter = { ...filter }; // the caller's object stays as it was
             for (const arg of Object.keys(props).sort()) {
                 if (!argNameRE.test(arg))
                     throw new Error(`wakeshift: event ${name}: argument ${JSON.stringify(arg)}: lowercase letters, digits and _`);
@@ -127,6 +128,9 @@ export class WakeEvent {
                     segs.push(`{${arg}}`);
                 }
                 else if (scalar && arg in payloadProps) {
+                    // Both on the same field is refused: neither can quietly win.
+                    if (opts.filter && Object.prototype.hasOwnProperty.call(opts.filter, arg))
+                        throw new Error(`wakeshift: event ${name}: filter on ${arg} conflicts with optional argument ${arg}, which already filters that payload field (remove it from filter, or pass topic and filter)`);
                     filter[arg] = `{${arg}}`;
                 }
                 else {
@@ -173,24 +177,65 @@ export class WakeEvent {
             d.title = this.title;
         return d;
     }
+    /** @internal The client the event was defined on. */
+    owner() {
+        return this.wake;
+    }
     /**
      * Sends one occurrence: to everyone subscribed with these arguments, or,
-     * for a personal event, to the one subscriber `to` names. The payload is
+     * for a personal event, to the recipients `to` names. The payload is
      * checked against the event's schema first.
      */
     async emit(args, payload, opts = {}) {
         const a = this.parseArgs(args);
         const p = safeParse(this.payloadSchema, payload);
         if (!p.success)
-            throw new WakeshiftError(400, "bad_payload", `payload for ${this.name}: ${issues(p.error)}`);
-        const to = opts.to?.trim();
+            throw new ArgsError(`payload for ${this.name}: ${issues(p.error)}`);
+        const to = this.wireTo(opts.to);
         if (this.personal && !to)
-            throw new WakeshiftError(400, "bad_arguments", `${this.name} is personal: pass { to }, the one subscriber it's for`);
+            throw new WakeshiftError(400, "bad_arguments", `${this.name} is personal: pass { to }, the subscribers it's for`);
         if (!this.personal && to)
             throw new WakeshiftError(400, "bad_arguments", `${this.name} isn't personal: it goes to everyone subscribed with these arguments, so it takes no to`);
         const text = this.opts.text(p.data, a);
         return this.wake.emitEvent({ name: this.name, arguments: a, payload: p.data, text, id: opts.id, to });
     }
+    // wireTo is what the core takes for to: one plain user as a string,
+    // anything else as a list of "user", { user, subscription } and
+    // { native: user }, each name trimmed of the whitespace around it, as every
+    // SDK does (test/emit-recipients.json). undefined: no recipients.
+    wireTo(to) {
+        if (to === undefined)
+            return undefined;
+        const empty = (what) => new WakeshiftError(400, "bad_arguments", `${this.name}: a recipient's ${what} is empty`);
+        const out = [];
+        for (const r of Array.isArray(to) ? to : [to]) {
+            if (typeof r === "string") {
+                if (!r.trim())
+                    throw empty("user");
+                out.push(r.trim());
+            }
+            else if (r && typeof r === "object" && "native" in r && typeof r.native === "string") {
+                if (!r.native.trim())
+                    throw empty("user");
+                out.push({ native: r.native.trim() });
+            }
+            else if (r && typeof r === "object" && "user" in r && typeof r.user === "string" && typeof r.subscription === "string") {
+                if (!r.user.trim())
+                    throw empty("user");
+                if (!r.subscription.trim())
+                    throw empty("subscription");
+                out.push({ user: r.user.trim(), subscription: r.subscription.trim() });
+            }
+            else {
+                throw new WakeshiftError(400, "bad_arguments", `${this.name}: a recipient is a user, { user, subscription } or { native: user }`);
+            }
+        }
+        if (out.length === 0)
+            return undefined;
+        if (out.length === 1 && typeof out[0] === "string")
+            return out[0];
+        return out;
+    }
     /**
      * A capability URL that emits this event with these arguments (a personal
      * event: to the one subscriber `to` names), for services that can only
@@ -201,6 +246,9 @@ export class WakeEvent {
      */
     async publishUrl(args, opts = {}) {
         const a = this.parseArgs(args);
+        if (opts.to !== undefined && typeof opts.to !== "string") {
+            throw new WakeshiftError(400, "bad_arguments", `${this.name}: a publish URL's to is exactly one user`);
+        }
         const to = opts.to?.trim();
         if (this.personal && !to)
             throw new WakeshiftError(400, "bad_arguments", `${this.name} is personal: pass { to }, the one subscriber it's for`);
@@ -212,64 +260,86 @@ export class WakeEvent {
         return this.wake.requestApp("POST", "/events/publish-urls", body);
     }
     /**
-     * Subscribes the conversation calling your tool, the way subscribe_events
-     * would, so a tool like "join" can set up its own wakes in one step. For
-     * clients that subscribe through Wakeshift's wake paths; native MCP Events
-     * clients subscribe themselves. Your tool decides who may: authorize isn't
-     * consulted here. user is the app's ID for the person (required for a
-     * personal event); wakeArgs are your tool's wake.args (session_key,
-     * harness, conversation_id); tool is your tool's name (Wakeshift's hooks
-     * act on a connector beacon only from the result of the tool it names).
+     * How many conversations are subscribed to this event with these
+     * arguments (a personal event: those of the one user `to` names), how
+     * many are connected now, and how. Only reads.
      */
-    async subscribe(extra, args, opts) {
+    async status(args, opts = {}) {
         const a = this.parseArgs(args);
-        if (this.personal && !opts.user) {
-            throw new WakeshiftError(400, "bad_arguments", `${this.name} is personal: pass user, who the subscription belongs to`);
+        if (opts.to !== undefined && typeof opts.to !== "string") {
+            throw new WakeshiftError(400, "bad_arguments", `${this.name}: status's to is exactly one user`);
         }
-        const out = await this.wake.requestApp("POST", "/event-subscriptions", {
-            call: this.wake.call(extra, { server: opts.server, client: opts.client, user: opts.user, args: opts.wakeArgs ?? {}, tool: opts.tool }),
-            name: this.name,
-            arguments: a,
-        });
-        const addition = out.addition ?? {};
-        return {
-            id: out.event_subscription.id,
-            created: out.event_subscription.created,
-            session: out.session,
-            agent: out.agent ?? { harness: null, via: null, claimed: null },
-            result: (text) => applyAddition(addition, text),
-        };
+        const to = opts.to?.trim();
+        if (this.personal && !to)
+            throw new WakeshiftError(400, "bad_arguments", `${this.name} is personal: pass { to }, the one user to count for`);
+        if (!this.personal && to)
+            throw new WakeshiftError(400, "bad_arguments", `${this.name} isn't personal: status takes no to`);
+        const body = { name: this.name, arguments: a };
+        if (to)
+            body.to = to;
+        const out = await this.wake.requestApp("POST", "/events/status", body);
+        return { subscriptions: out.subscriptions, connected: out.connected, via: { stream: 0, poll: 0, hooks: 0, webhook: 0, ...out.via } };
     }
     /**
-     * Ends the calling conversation's subscription with these arguments, the
-     * way unsubscribe_events would: for a tool like "unwatch". False if it
-     * wasn't subscribed.
+     * Reads subscriptions to this event by ID, each with the user
+     * `call.subscribe` made it for, up to 1,000 at once: whether each is live
+     * and its conversation connected now, and how. Only reads.
      */
-    async unsubscribe(extra, args, opts) {
-        const a = this.parseArgs(args);
-        const out = await this.wake.requestApp("POST", "/event-subscriptions/unsubscribe", {
-            call: this.wake.call(extra, { server: opts.server, client: opts.client, user: opts.user, args: opts.wakeArgs ?? {}, tool: opts.tool }),
-            name: this.name,
-            arguments: a,
+    async statusOf(subs) {
+        if (subs.length === 0)
+            return [];
+        if (subs.length > MAX_STATUS_SUBSCRIPTIONS) {
+            throw new WakeshiftError(400, "bad_request", `${this.name}: at most ${MAX_STATUS_SUBSCRIPTIONS} subscriptions in one statusOf`);
+        }
+        const refs = subs.map((s) => {
+            if (!s || typeof s.user !== "string" || !s.user.trim() || typeof s.subscription !== "string" || !s.subscription.trim()) {
+                throw new WakeshiftError(400, "bad_request", `${this.name}: statusOf needs each subscription's user and subscription`);
+            }
+            return { user: s.user.trim(), id: s.subscription.trim() };
+        });
+        const out = await this.wake.requestApp("POST", "/events/status", { name: this.name, subscriptions: refs });
+        return (out.subscriptions ?? []).map((s) => {
+            const r = { id: s.id, user: s.user, live: !!s.live, connected: !!s.connected };
+            if (s.via)
+                r.via = s.via;
+            return r;
         });
-        return !!out.ended;
     }
-    /** Ends one of user's subscriptions to this app's events, by its ID (from subscribe or list_subscriptions). False if there was none. */
+    /**
+     * Ends one of user's subscriptions to this app's events, by its ID (a
+     * Subscription's id from call.subscribe, or list_subscriptions'), outside
+     * a tool: a player who timed out, a member removed. False if there was none.
+     */
     async end(user, id) {
         const out = await this.wake.requestApp("POST", "/event-subscriptions/end", { user, id });
         return !!out.ended;
     }
 }
-/** A subscriber's arguments don't match the event's schema. */
-export class ArgsError extends Error {
+/** The most subscriptions one `statusOf` reads. */
+export const MAX_STATUS_SUBSCRIPTIONS = 1000;
+/**
+ * An event's arguments or payload don't match its schema: a WakeshiftError
+ * with code bad_arguments (status 400), as Wakeshift answers the same
+ * mistake, thrown before asking it.
+ */
+export class ArgsError extends WakeshiftError {
+    constructor(message) {
+        super(400, "bad_arguments", message);
+        this.name = "ArgsError";
+    }
 }
-// What a client says about itself on initialize, or a request's _meta.
-function clientInfoName(server, meta) {
+/** The tools attach adds, unless AttachOptions.tools names fewer. */
+export const BUILTIN_TOOLS = ["subscribe_events", "unsubscribe_events", "list_subscriptions"];
+// What a client says about itself on initialize, or a request's _meta;
+// else the name identify gave (identified).
+function clientInfoName(server, meta, identified) {
     const fromInit = server.server.getClientVersion()?.name;
     if (fromInit)
         return fromInit;
     const info = meta?.["io.modelcontextprotocol/clientInfo"];
-    return typeof info?.name === "string" ? info.name : "";
+    if (typeof info?.name === "string" && info.name)
+        return info.name;
+    return identified ?? "";
 }
 function header(extra, name) {
     const h = extra?.requestInfo?.headers;
@@ -279,9 +349,10 @@ function header(extra, name) {
     return (Array.isArray(v) ? v[0] : v) ?? "";
 }
 /** A client that speaks MCP Events: it declared the extension, or it's one known to (ChatGPT). */
+/** @internal */
 export function speaksEvents(capabilities, clientName) {
     const ext = capabilities?.extensions?.[EXTENSION_KEY];
-    return !!ext || !!capabilities?.[LEGACY_KEY] || clientName.toLowerCase() === "openai-mcp";
+    return !!ext || clientName.toLowerCase() === "openai-mcp";
 }
 // The fixed wording of the tools attach adds (tested: bench S1–S9 run
 // through them), and of the refusals of a native subscribe. The Go SDK
@@ -334,11 +405,29 @@ const MAX_LISTED_EVENTS = 20;
 export function attachEvents(wake, server, events, opts = {}) {
     if (events.length === 0)
         throw new Error("wakeshift: attach needs at least one event (wake.defineEvent) defined first");
-    const userOf = (extra) => opts.identify?.(extra)?.user;
+    for (const t of opts.tools ?? []) {
+        if (!BUILTIN_TOOLS.includes(t))
+            throw new Error(`wakeshift: attach's tools names "${t}": its own tools are ${BUILTIN_TOOLS.join(", ")}`);
+    }
+    const tools = new Set(opts.tools ?? BUILTIN_TOOLS);
+    const identityOf = (extra) => opts.identify?.(extra) ?? undefined;
+    // Who's calling: the user, and the client's name (the request's, else identify's).
+    const callerOf = (extra) => {
+        const id = extra ? identityOf(extra) : undefined;
+        return { user: id?.user, client: clientInfoName(server, extra?._meta, id?.client) };
+    };
+    const attached = new Attached({
+        wake,
+        server,
+        identify: (extra) => identityOf(extra),
+        clientOf: (meta, identified) => clientInfoName(server, meta, identified),
+        events: opts.events ?? {},
+        warnOnce: (key, message) => wake.warnOnce(key, message),
+    });
     const byName = new Map(events.map((e) => [e.name, e]));
     const low = server.server;
     try {
-        low.registerCapabilities({ [LEGACY_KEY]: { listChanged: false }, extensions: { [EXTENSION_KEY]: { listChanged: false } } });
+        low.registerCapabilities({ [TOP_LEVEL_KEY]: { listChanged: false }, extensions: { [EXTENSION_KEY]: { listChanged: false } } });
     }
     catch (err) {
         throw new Error("wakeshift: call attach before connecting the server to a transport", { cause: err });
@@ -355,7 +444,8 @@ export function attachEvents(wake, server, events, opts = {}) {
     const native = async (req, extra, unsubscribe) => {
         const p = (req.params ?? {});
         const meta = (p._meta ?? {});
-        const client = clientInfoName(server, meta);
+        const id = identityOf(extra);
+        const client = clientInfoName(server, meta, id?.client);
         const ua = header(extra, "user-agent");
         const dialect = dialectOf(client, ua);
         const codes = codesFor(dialect);
@@ -374,9 +464,9 @@ export function attachEvents(wake, server, events, opts = {}) {
             args = ev.parseArgs(p.arguments ?? {});
         }
         catch (err) {
-            throw new McpError(INVALID_PARAMS, err.message);
+            throw new McpError(INVALID_PARAMS, err instanceof WakeshiftError ? err.detail : err.message);
         }
-        const user = userOf(extra);
+        const user = id?.user;
         if (!user)
             throw new McpError(codes.forbidden, fill("native_no_user"));
         const call = { user, client, meta, ...(ua ? { user_agent: ua } : {}) };
@@ -427,11 +517,13 @@ export function attachEvents(wake, server, events, opts = {}) {
         .join("\n");
     const more = events.length > MAX_LISTED_EVENTS ? fill("more", { n: events.length - MAX_LISTED_EVENTS }) : "";
     const argsInput = z.record(z.string(), z.any()).optional().describe(EVENT_TOOL_TEXT.arguments_argument);
-    const result = (text, addition) => applyAddition(addition ?? {}, text);
+    const result = (text, addition) => withAddition(text, addition ?? {});
     const fail = (text) => ({ isError: true, content: [{ type: "text", text }] });
-    const subscribeTool = server.registerTool("subscribe_events", {
+    // register adds one of the tools, if the app wants it (attach's tools).
+    const register = (name, config, cb) => (tools.has(name) ? server.registerTool(name, config, cb) : undefined);
+    const subscribeTool = register("subscribe_events", {
         description: `${EVENT_TOOL_TEXT.subscribe_description}${EVENT_TOOL_TEXT.events_heading}${listed}${more}`,
-        inputSchema: { event: z.enum(names).describe(EVENT_TOOL_TEXT.event_argument), arguments: argsInput, ...wake.args },
+        inputSchema: { event: z.enum(names).describe(EVENT_TOOL_TEXT.event_argument), arguments: argsInput, ...toolArgs },
     }, async (input, extra) => {
         const { event, arguments: raw, ...rest } = input;
         const ev = byName.get(event);
@@ -442,17 +534,17 @@ export function attachEvents(wake, server, events, opts = {}) {
             args = ev.parseArgs(raw ?? {});
         }
         catch (err) {
-            return fail(err.message);
+            return fail(err instanceof WakeshiftError ? err.detail : err.message);
         }
-        const user = userOf(extra);
+        const { user, client } = callerOf(extra);
         if (ev.personal && !user)
             return fail(fill("personal_no_user", { event: ev.name }));
-        if (!(await ev.allows({ user, client: clientInfoName(server, extra?._meta), native: false }, args))) {
+        if (!(await ev.allows({ user, client, native: false }, args))) {
             return fail(fill("refused", { event: ev.name }));
         }
         try {
             const out = await wake.requestApp("POST", "/event-subscriptions", {
-                call: wake.call(extra, { server, user, args: rest, tool: "subscribe_events" }),
+                call: toolCallOf(extra, client, user, rest, "subscribe_events"),
                 name: ev.name,
                 arguments: args,
             });
@@ -464,17 +556,17 @@ export function attachEvents(wake, server, events, opts = {}) {
             return fail(fill("subscribe_failed", { detail: detailOf(err) }));
         }
     });
-    server.registerTool("unsubscribe_events", {
+    register("unsubscribe_events", {
         description: EVENT_TOOL_TEXT.unsubscribe_description,
         inputSchema: {
             event: z.enum(names).optional().describe(EVENT_TOOL_TEXT.event_argument),
             arguments: argsInput,
             id: z.string().optional().describe(EVENT_TOOL_TEXT.id_argument),
-            ...wake.args,
+            ...toolArgs,
         },
     }, async (input, extra) => {
         const { event, arguments: raw, id, ...rest } = input;
-        const user = userOf(extra);
+        const { user, client } = callerOf(extra);
         try {
             if (id) {
                 if (!user)
@@ -487,18 +579,21 @@ export function attachEvents(wake, server, events, opts = {}) {
                 return fail(fill("need"));
             const args = ev.parseArgs(raw ?? {});
             const out = await wake.requestApp("POST", "/event-subscriptions/unsubscribe", {
-                call: wake.call(extra, { server, user, args: rest, tool: "unsubscribe_events" }),
+                call: toolCallOf(extra, client, user, rest, "unsubscribe_events"),
                 name: ev.name,
                 arguments: args,
             });
             return result(fill(out.ended ? "unsubscribed" : "not_subscribed", { event: ev.name, arguments: canonical(args) }));
         }
         catch (err) {
-            return fail(err instanceof ArgsError ? err.message : fill("unsubscribe_failed", { detail: detailOf(err) }));
+            return fail(err instanceof ArgsError ? err.detail : fill("unsubscribe_failed", { detail: detailOf(err) }));
         }
     });
-    server.registerTool("list_subscriptions", { description: EVENT_TOOL_TEXT.list_description, inputSchema: { ...wake.args } }, async (_input, extra) => {
-        const user = userOf(extra);
+    // list_subscriptions only reads: marked so (readOnlyHint), clients that
+    // approve read-only tools without asking (Codex, by default) don't ask; and
+    // idempotent, as in every SDK (test/events-list.json).
+    register("list_subscriptions", { description: EVENT_TOOL_TEXT.list_description, inputSchema: { ...toolArgs }, annotations: { readOnlyHint: true, idempotentHint: true } }, async (_input, extra) => {
+        const user = identityOf(extra)?.user;
         if (!user)
             return fail(fill("list_no_user"));
         try {
@@ -522,23 +617,34 @@ export function attachEvents(wake, server, events, opts = {}) {
     low.oninitialized = () => {
         // Set both ways: a server reconnected to another client decides again.
         if (speaksEvents(low.getClientCapabilities(), low.getClientVersion()?.name ?? ""))
-            subscribeTool.disable();
+            subscribeTool?.disable();
         else
-            subscribeTool.enable();
+            subscribeTool?.enable();
         prev?.();
     };
+    return attached;
+}
+// withAddition is one of attach's own tools' results: its text, then
+// Wakeshift's, with Wakeshift's _meta.
+function withAddition(base, a) {
+    const text = (base.trim() + "\n\n" + (a.text ?? "")).trim();
+    const out = { content: text ? [{ type: "text", text }] : [] };
+    if (a.meta && Object.keys(a.meta).length > 0)
+        out._meta = { ...a.meta };
+    return out;
 }
 // rpcErrorOf is the JSON-RPC error for a failed native call, in the
 // client's dialect's codes. A conversation that isn't the caller's is
 // Forbidden, whether it exists or not.
-function rpcErrorOf(err, codes) {
+/** @internal */
+export function rpcErrorOf(err, codes) {
     if (err instanceof McpError)
         return err;
-    if (!(err instanceof WakeshiftError))
+    if (!(err instanceof WakeshiftError) || err.code === "unreachable")
         return new McpError(INTERNAL_ERROR, "Wakeshift couldn't be reached");
     switch (err.code) {
         case "callback_failed":
-            return new McpError(codes.callbackEndpoint, err.detail, { reason: err.reason });
+            return new McpError(codes.callbackEndpoint, err.detail, { reason: err.reason ?? "" });
         case "unknown_event":
             return new McpError(codes.notFound, err.detail, { kind: "event" });
         case "unsupported":