@wakeshift/sdk 0.5.2 → 0.7.0

package/dist/mastra.js

@@ -0,0 +1,248 @@
+// @wakeshift/sdk/mastra: Wakeshift in a Mastra MCPServer (@mastra/mcp 2.x).
+//
+// MCPServer builds a low-level MCP Server (@modelcontextprotocol/server
+// 2.x) for each request and fills it in itself; it never hands it to the
+// app, and its public extension points (Mastra tools, its own events) can't
+// carry what Wakeshift needs: a tool's result is Mastra's conversion of
+// what the tool returned, without _meta, which Codex's and Claude Code's
+// hooks read Wakeshift's beacon from; and there's no way to add a method
+// (tasks/get for the wait tool) or answer a tool's call another way.
+//
+// So serve() takes the one seam there is: MCPServer's createServerInstance,
+// a private method every transport (HTTP, stdio) builds its servers with.
+// Each server it builds gets what attach gives an McpServer, on that
+// server's request handlers (host.ts's lowServerHost): attach's own tools,
+// MCP Events, the wait tool and the 2026-07-28 tools/list changes; and the
+// tools wrapped with attached.events get Wakeshift's block in their results.
+// serve() checks @mastra/mcp's version and that the seam is there, and the
+// compatibility suite (sdk/compat, ts-mastra) runs it against Mastra's
+// newest release nightly, so a Mastra release that moves it shows up there.
+//
+// Mastra's own MCP Events (MCPServer's events option) keep working beside
+// Wakeshift's: events/list lists both, and every other events/* request
+// goes to whichever serves the event it names (Wakeshift's, if both do).
+//
+//   const attached = attachMastra(wake, { identify: (ctx) => ({ user: userOf(ctx.http?.authInfo) }) })
+//   const watchCi = createTool({
+//     id: "watch_ci",
+//     description: "Watch CI on a repo",
+//     inputSchema: attached.inputs(z.object({ owner: z.string(), repo: z.string() })),
+//     execute: attached.events("watch_ci", async ({ owner, repo }, call) => {
+//       await call.subscribe(ciFinished, { owner, repo })
+//       return `Watching CI on ${owner}/${repo}.`
+//     }),
+//   })
+//   const server = attached.serve(new MCPServer({ id: "ci", name: "CI", version: "1.0.0", tools: { watch_ci: watchCi } }))
+import { createRequire } from "node:module";
+import { attachHost, checkAttach } from "./events.js";
+import { lowServerHost, toolsOnlyHost, v2Req } from "./host.js";
+import { Attached, CallEnded } from "./toolcall.js";
+/** The @mastra/mcp releases serve() is built for: 2.x, from 2.7. */
+export const MASTRA_MCP_RANGE = ">=2.7.0 <3.0.0";
+const EVENTS_METHODS = ["events/list", "events/subscribe", "events/unsubscribe", "events/poll", "events/stream"];
+/** @internal Whether a version of @mastra/mcp is one serve() is built for. */
+export function supportedMastra(version) {
+    const m = /^(\d+)\.(\d+)\./.exec(version);
+    return !!m && Number(m[1]) === 2 && Number(m[2]) >= 7;
+}
+// installedMastra is the @mastra/mcp version this process loads, if it can
+// tell (a bundled app may not ship package.json files).
+function installedMastra() {
+    try {
+        return createRequire(import.meta.url)("@mastra/mcp/package.json").version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Wakeshift in a Mastra MCPServer: make it with attachMastra, then serve your MCPServer with it. */
+export class MastraAttached {
+    wake;
+    opts;
+    wrapped = new Set();
+    // The call each wrapped tool's execute belongs to, by its request (ctx.mcpReq,
+    // which Mastra passes the tool as context.mcp.extra.mcpReq).
+    scopes = new WeakMap();
+    // Only for inputs and output, which need no server.
+    shapes;
+    served = new WeakSet();
+    /** @internal Use attachMastra. */
+    constructor(wake, opts) {
+        this.wake = wake;
+        this.opts = opts;
+        const host = toolsOnlyHost({ framework: "mastra", req: v2Req, registerTool: () => { } });
+        this.shapes = new Attached({ wake, host, identify: () => undefined, clientOf: () => "", events: {}, warnOnce: () => { } });
+    }
+    inputs(schema) {
+        return this.shapes.inputs(schema);
+    }
+    output(schema) {
+        return this.shapes.output(schema);
+    }
+    /**
+     * Wraps a Mastra tool's execute, for the tool your MCPServer serves under
+     * the same name (its key in `tools`): `execute: attached.events("watch_ci",
+     * async (args, call) => …)`. handler gets your own arguments, a ToolCall
+     * and Mastra's tool context, and returns what a Mastra tool returns (a
+     * string, or your output). The reply an MCP client gets carries what
+     * Wakeshift adds for the conversation; a call that fails ends the
+     * subscriptions it made. Its inputSchema must come from attached.inputs.
+     * Run outside an MCP request (by an agent, a workflow or Studio), the
+     * handler gets a call whose subscribe throws.
+     */
+    events(name, handler) {
+        if (!name || typeof name !== "string")
+            throw new Error("wakeshift: attached.events needs the tool's name, as your MCPServer serves it");
+        if (typeof handler !== "function")
+            throw new Error("wakeshift: attached.events needs a handler");
+        this.wrapped.add(name);
+        return async (input, context) => {
+            const key = context?.mcp?.extra?.mcpReq;
+            const scope = key && typeof key === "object" ? this.scopes.get(key) : undefined;
+            const args = {};
+            for (const [k, v] of Object.entries((input ?? {}))) {
+                if (k !== "session_key" && k !== "harness" && k !== "conversation_id")
+                    args[k] = v;
+            }
+            const call = scope && scope.call.tool === name ? scope.call : detachedCall(name, context);
+            return handler(args, call, context ?? {});
+        };
+    }
+    /**
+     * Serves Wakeshift from your MCPServer (@mastra/mcp 2.7 or later, 2.x),
+     * after your last defineEvent: attach's own tools, MCP Events for clients
+     * that speak it, the wait tool, and your wrapped tools' blocks. Returns
+     * the server. Call it once, before the server takes requests.
+     */
+    serve(server) {
+        const version = installedMastra();
+        if (version && !supportedMastra(version)) {
+            throw new Error(`wakeshift: attachMastra serves @mastra/mcp ${MASTRA_MCP_RANGE}, and this is ${version}: check for an @wakeshift/sdk that supports it`);
+        }
+        const s = server;
+        if (typeof s.createServerInstance !== "function") {
+            throw new Error(`wakeshift: attached.serve takes Mastra's MCPServer (@mastra/mcp ${MASTRA_MCP_RANGE}), and this one has no createServerInstance${version ? ` (@mastra/mcp ${version})` : ""}: check for a newer @wakeshift/sdk`);
+        }
+        if (this.served.has(server))
+            return server;
+        this.served.add(server);
+        const build = s.createServerInstance;
+        const self = this;
+        s.createServerInstance = function (...args) {
+            const low = build.apply(this, args);
+            self.attachTo(low);
+            return low;
+        };
+        return server;
+    }
+    // attachTo gives one server MCPServer built what attach gives an McpServer.
+    // A failure leaves the request served without Wakeshift, and says why once.
+    attachTo(low) {
+        try {
+            const host = lowServerHost(low, "Mastra's MCPServer");
+            const handlers = host.handlers();
+            const theirs = new Map();
+            for (const m of EVENTS_METHODS) {
+                const h = handlers.get(m);
+                if (h)
+                    theirs.set(m, h);
+            }
+            const events = this.wake.serveEvents();
+            const attached = attachHost(this.wake, host, events, this.opts);
+            for (const name of this.wrapped)
+                attached.markWrapped(name);
+            if (theirs.size > 0)
+                shareEvents(handlers, theirs, new Set(events.map((e) => e.name)));
+            this.wrapCalls(handlers, attached);
+        }
+        catch (err) {
+            this.wake.warnOnce("mastra-attach", `wakeshift: couldn't attach to the server Mastra's MCPServer built, so its requests are served without Wakeshift: ${String(err?.message ?? err)}`);
+        }
+    }
+    // wrapCalls runs each wrapped tool's call in a scope its execute finds, and
+    // adds Wakeshift's block to the result Mastra makes of what it returned.
+    wrapCalls(handlers, attached) {
+        const inner = handlers.get("tools/call");
+        if (!inner)
+            return;
+        Map.prototype.set.call(handlers, "tools/call", async (request, ctx) => {
+            const name = request?.params?.name;
+            if (typeof name !== "string" || !this.wrapped.has(name))
+                return inner(request, ctx);
+            const { call } = attached.begin(name, (request?.params?.arguments ?? {}), ctx);
+            const key = ctx?.mcpReq && typeof ctx.mcpReq === "object" ? ctx.mcpReq : undefined;
+            if (key)
+                this.scopes.set(key, { call });
+            let result;
+            try {
+                result = await inner(request, ctx);
+            }
+            catch (err) {
+                await attached.fail(call);
+                throw err;
+            }
+            finally {
+                if (key)
+                    this.scopes.delete(key);
+            }
+            if (!result || typeof result !== "object" || !Array.isArray(result.content)) {
+                // Not a tool's answer (a task handle, an input request): no block to
+                // add, so nothing the call subscribed stays.
+                await attached.fail(call);
+                this.wake.warnOnce("mastra-result:" + name, `wakeshift: ${name} answered with something other than a tool result (a Mastra task, or a request for input), so what it subscribed was rolled back: a wrapped tool must answer in one call`);
+                return result;
+            }
+            return attached.finish(call, result, undefined);
+        });
+    }
+}
+// shareEvents serves Mastra's own MCP Events beside Wakeshift's: events/list
+// lists both (Wakeshift's first, on the first page), and every other method
+// goes to whichever serves the event it names.
+function shareEvents(handlers, theirs, ours) {
+    for (const [method, their] of theirs) {
+        const mine = handlers.get(method);
+        if (!mine || mine === their)
+            continue;
+        if (method === "events/list") {
+            Map.prototype.set.call(handlers, method, async (request, ctx) => {
+                if (request?.params?.cursor !== undefined)
+                    return their(request, ctx);
+                const [a, b] = await Promise.all([mine(request, ctx), their(request, ctx)]);
+                const listed = [...(a?.events ?? []), ...(b?.events ?? []).filter((e) => !ours.has(e?.name ?? ""))];
+                return { ...b, ...a, events: listed, ...(b?.nextCursor !== undefined ? { nextCursor: b.nextCursor } : {}) };
+            });
+            continue;
+        }
+        Map.prototype.set.call(handlers, method, (request, ctx) => (ours.has(request?.params?.name) ? mine(request, ctx) : their(request, ctx)));
+    }
+}
+// detachedCall is the call a wrapped tool's handler gets outside an MCP
+// tools/call (an agent, a workflow or Studio ran the tool): nothing to subscribe.
+function detachedCall(tool, context) {
+    const refuse = () => Promise.reject(new Error(`wakeshift: ${tool} ran outside an MCP client's call to a server attachMastra serves (from an agent, a workflow or Studio?), so there's no conversation to subscribe`));
+    return {
+        user: undefined,
+        tool,
+        native: false,
+        nativeConversation: null,
+        session: null,
+        recognized: null,
+        extra: (context?.mcp?.extra ?? {}),
+        subscribe: refuse,
+        unsubscribe: refuse,
+        resolveSession: refuse,
+    };
+}
+/**
+ * Wakeshift for a Mastra MCPServer (@mastra/mcp 2.7 or later). Returns the
+ * handle your tools use (attached.inputs, attached.events) and that serves
+ * your MCPServer (attached.serve). Options are attach's; identify and
+ * events.native get the request's MCP context (ctx: the verified token is
+ * ctx.http?.authInfo).
+ */
+export function attachMastra(wake, opts = {}) {
+    checkAttach(wake.serveEvents(), opts, "attachMastra");
+    return new MastraAttached(wake, opts);
+}
+export { CallEnded };

package/dist/mcp.d.ts

@@ -0,0 +1,92 @@
+/** An MCP content block: text, or anything else the protocol carries. */
+export type ContentBlock = {
+    type: "text";
+    text: string;
+    [k: string]: unknown;
+} | {
+    type: "image" | "audio" | "resource_link" | "resource";
+    [k: string]: unknown;
+};
+/** A tools/call result, as either MCP SDK types one. */
+export interface CallToolResult {
+    content: ContentBlock[];
+    /** An object on protocol 2025-11-25; any JSON value on 2026-07-28. */
+    structuredContent?: unknown;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** A verified access token, as an MCP SDK's auth middleware passes it to handlers. */
+export interface AuthInfo {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt?: number;
+    resource?: URL;
+    extra?: Record<string, unknown>;
+}
+/**
+ * A JSON-RPC error a handler throws: both MCP SDKs answer with its code,
+ * message and data (1.x calls its own McpError, 2.x ProtocolError).
+ */
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/**
+ * An McpServer from either MCP SDK: @modelcontextprotocol/sdk 1.x's
+ * (`@modelcontextprotocol/sdk/server/mcp.js`) or
+ * @modelcontextprotocol/server 2.x's.
+ */
+export interface McpServerLike {
+    readonly server: object;
+    registerTool(...args: any[]): unknown;
+}
+type LowOf<S> = S extends {
+    server: infer L;
+} ? L : never;
+/**
+ * The context a server's request handlers get, read from the server's own
+ * type: @modelcontextprotocol/server 2.x's ServerContext (`ctx`), or
+ * @modelcontextprotocol/sdk 1.x's RequestHandlerExtra (`extra`).
+ */
+export type HostContext<S> = LowOf<S> extends {
+    projectCallToolResult: unknown;
+} ? LowOf<S> extends {
+    setRequestHandler(method: string, schemas: any, handler: (params: any, ctx: infer C) => any): void;
+} ? C : ToolCallExtra : S extends {
+    registerTool(name: string, config: any, cb: (args: any, extra: infer E) => any): any;
+} ? E : ToolCallExtra;
+/**
+ * The parts of a tool call's context Wakeshift reads, whichever MCP SDK
+ * serves it: 1.x's RequestHandlerExtra (`_meta`, `authInfo`,
+ * `requestInfo`), 2.x's ServerContext (`mcpReq`, `http`). A wrapped tool's
+ * `call.extra` is typed as your MCP SDK's own.
+ */
+export interface ToolCallExtra {
+    _meta?: Record<string, unknown>;
+    authInfo?: AuthInfo;
+    requestInfo?: {
+        headers?: Record<string, string | string[] | undefined>;
+    };
+    signal?: AbortSignal;
+    sessionId?: string;
+    mcpReq?: {
+        _meta?: Record<string, unknown>;
+        envelope?: Record<string, unknown>;
+        signal?: AbortSignal;
+        id?: string | number;
+    };
+    http?: {
+        authInfo?: AuthInfo;
+        req?: {
+            headers: {
+                get(name: string): string | null;
+            };
+        };
+    };
+    /** The rest of the SDK's own context (1.x: requestId, sendNotification…; 2.x: mcpReq.send…). */
+    [k: string]: any;
+}
+export {};

package/dist/mcp.js

@@ -0,0 +1,21 @@
+// The MCP types the SDK's API names, written out here rather than imported,
+// so its published types load with either MCP TypeScript SDK installed and
+// the other missing: @modelcontextprotocol/sdk 1.x or
+// @modelcontextprotocol/server 2.x (host.ts tells them apart at run time).
+// Each is what both SDKs' own types have in common, so a value of either's
+// type fits.
+/**
+ * A JSON-RPC error a handler throws: both MCP SDKs answer with its code,
+ * message and data (1.x calls its own McpError, 2.x ProtocolError).
+ */
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "RpcError";
+        this.code = code;
+        if (data !== undefined)
+            this.data = data;
+    }
+}

package/dist/retry.js

@@ -55,4 +55,3 @@ function pause(ms, signal) {
         signal?.addEventListener("abort", stop, { once: true });
     });
 }
-//# sourceMappingURL=retry.js.map

package/dist/spec.js

@@ -42,4 +42,3 @@ export function headerValue(h) {
         return null;
     }
 }
-//# sourceMappingURL=spec.js.map

package/dist/tasks.js

@@ -14,9 +14,9 @@
 // tool, and a wrapped tool's call from it tells Wakeshift so (call.tasks),
 // which then gives the wait tool's instructions instead of its harness's
 // zero-install path (Claude Code's Monitor). Everything else is unchanged.
-import { McpError } from "@modelcontextprotocol/sdk/types.js";
 import { WakeshiftError } from "./errors.js";
 import { TASKS_EXTENSION, takesTasks } from "./discover.js";
+import { RpcError } from "./mcp.js";
 import { WAKE_ARG_DESCRIPTIONS } from "./toolcall.js";
 import { toolCallOf } from "./wakeshift.js";
 /** The wait tool's name. */
@@ -48,19 +48,22 @@ export { TASKS_EXTENSION, takesTasks };
  * in tools/list for a request that takes tasks, and its calls and task
  * requests passed to Wakeshift.
  */
-export function serveTasks(wake, server, callerOf) {
-    const low = server.server;
-    const handlers = low._requestHandlers;
-    if (!(handlers instanceof Map))
+export function serveTasks(wake, host, callerOf) {
+    const handlers = host.handlers();
+    if (!handlers)
         return; // a future SDK: nothing to hook (no wait tool)
-    const call = (extra, args) => {
-        const { user, client } = callerOf(extra);
-        return toolCallOf(extra, client, user, args, WAIT_TOOL);
+    const call = (raw, args) => {
+        const { user, client } = callerOf(raw);
+        return toolCallOf(host.req(raw), client, user, args, WAIT_TOOL);
     };
-    const waitCall = async (request, extra) => {
+    const takes = (raw) => {
+        const req = host.req(raw);
+        return takesTasks(req.meta, req);
+    };
+    const waitCall = async (request, raw) => {
         const args = (request?.params?.arguments ?? {});
         try {
-            const out = await wake.requestApp("POST", "/calls/task", { call: call(extra, args) });
+            const out = await wake.requestApp("POST", "/calls/task", { call: call(raw, args) });
             if (out.result)
                 return out.result;
         }
@@ -69,74 +72,83 @@ export function serveTasks(wake, server, callerOf) {
         }
         return { isError: true, content: [{ type: "text", text: `Wakeshift didn't answer the wait. Call ${WAIT_TOOL} again.` }] };
     };
-    const taskRequest = (path, hold) => async (request, extra) => {
+    const taskRequest = (path, hold) => async (request, raw) => {
         const task = request?.params?.taskId;
-        const body = { task: typeof task === "string" ? task : "", call: call(extra, {}) };
+        const body = { task: typeof task === "string" ? task : "", call: call(raw, {}) };
         if (hold)
             body.hold_seconds = TASK_HOLD_SECONDS;
+        const signal = host.req(raw).signal;
         let out;
         try {
-            out = await wake.requestApp("POST", path, body, { timeoutMs: (TASK_HOLD_SECONDS + 15) * 1000, signal: extra?.signal });
+            out = await wake.requestApp("POST", path, body, { timeoutMs: (TASK_HOLD_SECONDS + 15) * 1000, signal });
         }
         catch (err) {
-            if (extra?.signal?.aborted)
-                throw new McpError(-32603, "canceled by the client");
-            throw new McpError(-32603, `Wakeshift: ${detailOf(err)}`);
+            if (signal?.aborted)
+                throw new RpcError(-32603, "canceled by the client");
+            throw new RpcError(-32603, `Wakeshift: ${detailOf(err)}`);
         }
         if (out.rpc_error)
-            throw new McpError(out.rpc_error.code, out.rpc_error.message);
+            throw new RpcError(out.rpc_error.code, out.rpc_error.message);
         if (!out.result)
-            throw new McpError(-32603, "Wakeshift didn't answer for this task");
+            throw new RpcError(-32603, "Wakeshift didn't answer for this task");
         return out.result;
     };
-    // server/discover (discover.ts) gets the tasks extension.
-    const wrapDiscover = (h) => async (request, extra) => {
-        const out = await h(request, extra);
+    // server/discover gets the tasks extension (1.x: discover.ts's handler;
+    // 2.x: its own). initialize doesn't: older revisions' clients never see it.
+    const wrapDiscover = (h) => async (request, raw) => {
+        const out = await h(request, raw);
         if (out && typeof out === "object") {
-            const caps = (out.capabilities ??= {});
+            const caps = { ...(out.capabilities ?? {}) };
             caps.extensions = { ...(caps.extensions ?? {}), [TASKS_EXTENSION]: {} };
+            return { ...out, capabilities: caps };
         }
         return out;
     };
     // tools/list lists the wait tool for a request that takes tasks; tools/call
     // answers it. McpServer sets these when the first tool is registered,
     // perhaps after attach, so a later set is wrapped too.
-    const wrapList = (h) => async (request, extra) => {
-        const out = await h(request, extra);
-        if (takesTasks(request?.params?._meta, extra) && out && Array.isArray(out.tools) && !out.tools.some((t) => t?.name === WAIT_TOOL)) {
-            out.tools = [...out.tools, WAIT_TOOL_DEFINITION];
+    const wrapList = (h) => async (request, raw) => {
+        const out = await h(request, raw);
+        if (takes(raw) && out && Array.isArray(out.tools) && !out.tools.some((t) => t?.name === WAIT_TOOL)) {
+            return { ...out, tools: [...out.tools, WAIT_TOOL_DEFINITION] };
         }
         return out;
     };
-    const wrapCall = (h) => async (request, extra) => (request?.params?.name === WAIT_TOOL ? waitCall(request, extra) : h(request, extra));
+    const wrapCall = (h) => async (request, raw) => (request?.params?.name === WAIT_TOOL ? waitCall(request, raw) : h(request, raw));
     // tasks/get and tasks/cancel: Wakeshift's own tasks (their IDs start
     // wkt1_) go to Wakeshift; any other goes to the app's own handler, if it
     // has one.
     const wrapTask = (path, hold) => (h) => {
         const ours = taskRequest(path, hold);
-        return async (request, extra) => {
+        return async (request, raw) => {
             const id = request?.params?.taskId;
             if (typeof id === "string" && id.startsWith(TASK_ID_PREFIX))
-                return ours(request, extra);
+                return ours(request, raw);
             if (h)
-                return h(request, extra);
-            throw new McpError(-32601, "Method not found");
+                return h(request, raw);
+            throw new RpcError(-32601, "Method not found");
         };
     };
     const wrappers = {
-        "server/discover": wrapDiscover,
-        "tools/list": wrapList,
-        "tools/call": wrapCall,
+        "server/discover": (h) => wrapDiscover(h),
+        "tools/list": (h) => wrapList(h),
+        "tools/call": (h) => wrapCall(h),
         "tasks/get": wrapTask("/calls/task/get", true),
         "tasks/cancel": wrapTask("/calls/task/cancel", false),
     };
-    // Set directly, not through the MCP SDK's setRequestHandler, which would
-    // ask for its own tasks capability (an older revision's), never advertised;
-    // and once only (serveStateless wraps what's set through handlers.set).
     for (const [method, wrap] of Object.entries(wrappers)) {
         const h = handlers.get(method);
-        if (h || method.startsWith("tasks/"))
+        if (method.startsWith("tasks/")) {
+            // Routed by the SDK on every protocol revision (host.setTaskMethod),
+            // then answered by the wrapper, which hands anything that isn't
+            // Wakeshift's to the app's own handler, if it had one.
+            host.setTaskMethod(method);
+            Map.prototype.set.call(handlers, method, wrap(h));
+        }
+        else if (h) {
+            // Set once (serveStateless wraps what's set through handlers.set).
             Map.prototype.set.call(handlers, method, wrap(h));
+        }
     }
     const set = handlers.set.bind(handlers);
     handlers.set = (method, h) => set(method, wrappers[method] ? wrappers[method](h) : h);
@@ -144,4 +156,3 @@ export function serveTasks(wake, server, callerOf) {
 function detailOf(err) {
     return err instanceof WakeshiftError ? err.detail : String(err?.message ?? err);
 }
-//# sourceMappingURL=tasks.js.map