@wakeshift/sdk 0.5.2 → 0.7.0

package/dist/host.js

@@ -0,0 +1,380 @@
+// What attach needs of an MCP server, for each MCP TypeScript SDK it takes:
+// @modelcontextprotocol/sdk 1.x and @modelcontextprotocol/server 2.x. The
+// rest of the SDK (events.ts, toolcall.ts, tasks.ts, discover.ts) is
+// written once against Host, and neither MCP SDK is imported here: hostOf
+// tells them apart by the server object it's given.
+//
+// Where the two differ:
+//   - a request's context: 1.x's `extra` (_meta, requestInfo.headers,
+//     authInfo, signal), 2.x's `ctx` (mcpReq._meta without the reserved
+//     io.modelcontextprotocol/* keys, which it lifts into mcpReq.envelope;
+//     http.req's Headers; http.authInfo; mcpReq.signal). req() reads either
+//     into one shape, putting the envelope's keys back into _meta, so
+//     Wakeshift gets the same call from both (test/mcp-tasks-wire.json);
+//   - custom methods (events/*): a zod request schema on 1.x, a method name
+//     and a params schema on 2.x;
+//   - tasks/get and tasks/cancel: 2.x answers them on protocol 2026-07-28
+//     only for a handler registered with a params schema (the tasks
+//     extension's methods), so setTaskMethod registers them that way;
+//   - protocol 2026-07-28: 1.x doesn't speak it, so discover.ts teaches it;
+//     2.x speaks it itself (server/discover, resultType, ttlMs and
+//     cacheScope).
+//
+// Both keep their request handlers in a private Map (_requestHandlers),
+// which tools/list, tools/call, server/discover and tasks/* are wrapped
+// through (neither has public middleware for a method it answers itself),
+// and their tools in _registeredTools, which wrapped tools are checked
+// against. Unit tests pin both against each SDK the CI installs.
+import { z } from "zod";
+import * as z4 from "zod/v4";
+import { normalizeObjectSchema, safeParseAsync } from "./zod.js";
+const VERSION_META = "io.modelcontextprotocol/protocolVersion";
+function lowOf(server) {
+    return server.server;
+}
+/**
+ * @internal The Host for an McpServer from either SDK. 2.x's low-level
+ * Server has projectCallToolResult, which 1.x's lacks.
+ */
+export function hostOf(server) {
+    if (!isMcpServer(server))
+        throw new Error(unsupportedServer(server));
+    const low = server.server;
+    return typeof low.projectCallToolResult === "function" ? new V2Host(server) : new V1Host(server);
+}
+/** Where the docs list the MCP server frameworks Wakeshift works with, and how. */
+export const FRAMEWORKS_DOCS = "https://wakeshift.ai/docs/frameworks";
+// isMcpServer: an McpServer from either MCP SDK (its low-level server, and registerTool).
+function isMcpServer(server) {
+    const low = server?.server;
+    return !!low && typeof low.setRequestHandler === "function" && typeof server.registerTool === "function";
+}
+const TAKES = "wakeshift: attach takes an McpServer, from @modelcontextprotocol/server 2.x or @modelcontextprotocol/sdk 1.x (@modelcontextprotocol/sdk/server/mcp.js)";
+/**
+ * @internal What attach says when it's given something other than an
+ * McpServer: what it got, what it takes, and, for a framework it knows,
+ * what to do instead.
+ */
+export function unsupportedServer(server) {
+    const got = describe(server);
+    const hint = frameworkHint(server);
+    return `${TAKES}, and got ${got}.${hint ? " " + hint : ""} Frameworks Wakeshift works with, and how: ${FRAMEWORKS_DOCS}`;
+}
+function has(o, ...fns) {
+    return !!o && (typeof o === "object" || typeof o === "function") && fns.every((f) => typeof o[f] === "function");
+}
+function ctorName(o) {
+    const name = o?.constructor?.name;
+    return typeof name === "string" && name && name !== "Object" ? name : "";
+}
+// describe names what attach was given: its class, else its type.
+function describe(server) {
+    if (server === null)
+        return "null";
+    if (server === undefined)
+        return "undefined";
+    if (typeof server !== "object")
+        return `a ${typeof server}`;
+    const name = ctorName(server);
+    return name ? `a ${name}` : "an object";
+}
+// frameworkHint says what to do for a server from a framework attach knows
+// but can't take: "" for any other.
+function frameworkHint(server) {
+    if (!server || typeof server !== "object")
+        return "";
+    // Mastra's MCPServer (@mastra/mcp): builds its MCP server per request, inside.
+    if (has(server, "startHTTP", "convertTools") || (has(server, "startHTTP", "startStdio") && "toolActions" in server)) {
+        return "This looks like Mastra's MCPServer (@mastra/mcp), which builds its MCP server inside: use attachMastra from @wakeshift/sdk/mastra.";
+    }
+    // punkpeye's fastmcp: its FastMCP, or a session of it.
+    if (has(server, "addTool", "start") && ctorName(server) === "FastMCP") {
+        return "This looks like fastmcp's FastMCP (punkpeye), which Wakeshift doesn't support: it refuses MCP protocol 2026-07-28.";
+    }
+    if (ctorName(server) === "FastMCPSession") {
+        return "This looks like a fastmcp session (punkpeye), which Wakeshift doesn't support: fastmcp refuses MCP protocol 2026-07-28.";
+    }
+    // A low-level Server, not the McpServer around it.
+    if (has(server, "setRequestHandler", "connect") && !has(server, "registerTool")) {
+        return "This is a low-level MCP Server: pass the McpServer instead (new McpServer(…), whose .server it is).";
+    }
+    // Cloudflare's McpAgent: its server is the McpServer.
+    if ("server" in server && has(server, "init") && isMcpServer(server.server)) {
+        return "This looks like a Cloudflare McpAgent: pass its McpServer (this.server).";
+    }
+    return "";
+}
+/**
+ * @internal attach's error when the server refused Wakeshift's
+ * capabilities: an McpServer already connected to a transport, or
+ * whatever else its MCP SDK said.
+ */
+export function capabilitiesError(host, err) {
+    const low = host.server.server;
+    if (low?.transport)
+        return new Error("wakeshift: call attach before connecting the server to a transport", { cause: err });
+    return new Error(`wakeshift: attach couldn't add Wakeshift's capabilities to this server: ${String(err?.message ?? err)}`, { cause: err });
+}
+// headerOf reads a header from a plain record (1.x's requestInfo.headers).
+function headerOf(headers, name) {
+    if (!headers)
+        return "";
+    const v = headers[name] ?? headers[name.toLowerCase()];
+    return (Array.isArray(v) ? v[0] : v) ?? "";
+}
+/** @internal A context already read (req's output). */
+function isReq(raw) {
+    return !!raw && typeof raw.header === "function" && "meta" in raw;
+}
+/**
+ * @internal A request's context read the 1.x way: extra's _meta,
+ * requestInfo.headers, authInfo and signal. Also what a plain
+ * `{ _meta, requestInfo }` (ToolExtra) reads as.
+ */
+export function v1Req(raw) {
+    if (isReq(raw))
+        return raw;
+    const e = (raw ?? {});
+    return { meta: e._meta, header: (name) => headerOf(e.requestInfo?.headers, name), authInfo: e.authInfo, signal: e.signal };
+}
+/** @internal A request's context read the 2.x way (ctx), putting the envelope's keys back into _meta. */
+export function v2Req(raw) {
+    if (isReq(raw))
+        return raw;
+    const c = (raw ?? {});
+    if (!c.mcpReq)
+        return v1Req(raw);
+    const own = c.mcpReq._meta;
+    const env = c.mcpReq.envelope;
+    const meta = env && Object.keys(env).length > 0 ? { ...env, ...own } : own;
+    const headers = c.http?.req?.headers;
+    return {
+        meta,
+        header: (name) => (headers && typeof headers.get === "function" ? (headers.get(name) ?? "") : ""),
+        authInfo: c.http?.authInfo,
+        signal: c.mcpReq.signal,
+    };
+}
+class BaseHost {
+    server;
+    servesEvents = true;
+    constructor(server) {
+        this.server = server;
+    }
+    get low() {
+        return lowOf(this.server);
+    }
+    registerCapabilities(capabilities) {
+        this.low.registerCapabilities(capabilities);
+    }
+    handlers() {
+        const h = this.low._requestHandlers;
+        return h instanceof Map ? h : null;
+    }
+    clientName() {
+        return this.low.getClientVersion?.()?.name || undefined;
+    }
+    clientCapabilities() {
+        return this.low.getClientCapabilities?.();
+    }
+    onInitialized(fn) {
+        const low = this.low;
+        const prev = low.oninitialized;
+        low.oninitialized = () => {
+            fn();
+            prev?.();
+        };
+    }
+    registeredTool(name) {
+        const tools = this.server._registeredTools;
+        if (!tools || typeof tools !== "object")
+            return null;
+        return Object.prototype.hasOwnProperty.call(tools, name) ? tools[name] : undefined;
+    }
+}
+class V1Host extends BaseHost {
+    version = 1;
+    zod = z;
+    req(raw) {
+        return v1Req(raw);
+    }
+    registerTool(name, config, cb) {
+        return this.server.registerTool(name, config, cb);
+    }
+    setMethod(method, handler) {
+        const schema = z.object({ method: z.literal(method), params: z.any().optional() });
+        this.low.setRequestHandler(schema, (request, extra) => handler(request.params ?? {}, extra));
+    }
+    setTaskMethod(_method) {
+        // Nothing to register: 1.x routes whatever is in its handler map. (Its
+        // setRequestHandler would ask for its own tasks capability, an older
+        // revision's, never advertised.)
+    }
+    async validOutput(outputSchema, result) {
+        // McpServer 1.x's validateToolOutput: an object schema, and structured content that parses.
+        if (!outputSchema)
+            return true;
+        if (typeof result === "string" || !result.structuredContent)
+            return false;
+        const obj = normalizeObjectSchema(outputSchema);
+        if (!obj)
+            return true;
+        return (await safeParseAsync(obj, result.structuredContent)).success;
+    }
+}
+class V2Host extends BaseHost {
+    version = 2;
+    zod = z4;
+    req(raw) {
+        return v2Req(raw);
+    }
+    registerTool(name, config, cb) {
+        // 2.x takes an object schema (a bare shape is deprecated there).
+        return this.server.registerTool(name, { ...config, inputSchema: objectFromV4Shape(config.inputSchema) }, cb);
+    }
+    setMethod(method, handler) {
+        this.low.setRequestHandler(method, { params: z4.looseObject({}) }, (params, ctx) => handler(params ?? {}, ctx));
+    }
+    setTaskMethod(method) {
+        // Registered with a params schema, so 2.x serves it on protocol
+        // 2026-07-28 too, as the tasks extension's method (SEP-2663). The
+        // caller replaces the handler that leaves in the map.
+        this.low.setRequestHandler(method, { params: z4.looseObject({}) }, async () => {
+            throw Object.assign(new Error("Method not found"), { code: -32601 });
+        });
+    }
+    async validOutput(outputSchema, result) {
+        // McpServer 2.x's validateToolOutput: structured content (any JSON
+        // value) that the output schema (a Standard Schema) accepts.
+        if (!outputSchema)
+            return true;
+        if (typeof result === "string" || result.structuredContent === undefined)
+            return false;
+        const std = outputSchema["~standard"];
+        if (!std || typeof std.validate !== "function")
+            return true;
+        const out = (await std.validate(result.structuredContent));
+        return !out.issues;
+    }
+}
+// objectFromV4Shape is a zod 4 object of attach's own tool shapes (written
+// with zod/v4: host.zod).
+function objectFromV4Shape(shape) {
+    const values = Object.values(shape);
+    if (values.length === 0)
+        return z4.object({});
+    return z4.object(shape);
+}
+// ── Framework adapters (mastra.ts, xmcp.ts) ─────────────────────────────
+/**
+ * @internal The Host for a low-level Server from @modelcontextprotocol/server
+ * 2.x, as a framework builds one for each request and fills in itself
+ * (Mastra's MCPServer). It has no McpServer to register attach's own
+ * tools on, so they're kept here and served from its handler map, beneath
+ * every other wrapper attach adds: tools/list lists them after the
+ * framework's own, and tools/call answers them. Everything else is
+ * V2Host's, on the same map.
+ */
+export function lowServerHost(low, framework) {
+    if (!low || typeof low.setRequestHandler !== "function" || !(low._requestHandlers instanceof Map)) {
+        throw new Error(`wakeshift: ${framework} built an MCP server Wakeshift can't serve (no request handlers it can wrap): check for a newer @wakeshift/sdk`);
+    }
+    return new LowV2Host(new ToolRegistry(low), framework);
+}
+// ToolRegistry stands in for an McpServer around a low-level Server: what
+// attach registers on it is listed and called through the server's handlers.
+class ToolRegistry {
+    server;
+    tools = new Map();
+    constructor(server) {
+        this.server = server;
+        const handlers = server._requestHandlers;
+        const list = handlers.get("tools/list");
+        const call = handlers.get("tools/call");
+        if (list) {
+            Map.prototype.set.call(handlers, "tools/list", async (request, raw) => {
+                const out = await list(request, raw);
+                const own = [...this.tools].filter(([, t]) => t.enabled);
+                if (own.length === 0 || !out || !Array.isArray(out.tools))
+                    return out;
+                const listed = new Set(out.tools.map((t) => t?.name));
+                return { ...out, tools: [...out.tools, ...own.filter(([name]) => !listed.has(name)).map(([name, t]) => listedTool(name, t))] };
+            });
+        }
+        if (call) {
+            Map.prototype.set.call(handlers, "tools/call", async (request, raw) => {
+                const t = this.tools.get(request?.params?.name);
+                if (!t || !t.enabled)
+                    return call(request, raw);
+                const parsed = await t.schema.safeParseAsync(request?.params?.arguments ?? {});
+                if (!parsed.success) {
+                    return { isError: true, content: [{ type: "text", text: `Invalid arguments for tool ${request.params.name}: ${parsed.error.message}` }] };
+                }
+                return t.cb(parsed.data, raw);
+            });
+        }
+    }
+    registerTool(name, config, cb) {
+        const t = { description: config.description, annotations: config.annotations, schema: config.inputSchema, cb, enabled: true };
+        this.tools.set(name, t);
+        return {
+            enable: () => void (t.enabled = true),
+            disable: () => void (t.enabled = false),
+        };
+    }
+}
+function listedTool(name, t) {
+    const out = { name, description: t.description, inputSchema: z4.toJSONSchema(t.schema, { io: "input" }) };
+    if (t.annotations)
+        out.annotations = t.annotations;
+    return out;
+}
+class LowV2Host extends V2Host {
+    framework;
+    constructor(registry, framework) {
+        super(registry);
+        this.framework = framework;
+    }
+    registeredTool() {
+        return null; // the framework's own tools are its own
+    }
+}
+/**
+ * @internal The Host for a framework that keeps its MCP server to itself
+ * (xmcp): attach's own tools go to the adapter, the request is read its
+ * way, and there are no handlers to wrap, so no MCP Events, no wait tool
+ * and no tools/list changes. Its tools are on @modelcontextprotocol/server
+ * 2.x, so they're written in zod 4.
+ */
+export function toolsOnlyHost(opts) {
+    const noop = () => { };
+    return {
+        version: 2,
+        framework: opts.framework,
+        servesEvents: false,
+        server: { server: {}, registerTool: noop },
+        zod: z4,
+        req: opts.req,
+        registerCapabilities: noop,
+        registerTool(name, config, cb) {
+            opts.registerTool(name, config, cb);
+            return { enable: noop, disable: noop };
+        },
+        setMethod: noop,
+        setTaskMethod: noop,
+        handlers: () => null,
+        clientName: () => undefined,
+        clientCapabilities: () => undefined,
+        onInitialized: noop,
+        registeredTool: () => null,
+        validOutput: async () => true,
+    };
+}
+/** The protocol revision that has server/discover, MCP Events and the tasks extension. */
+export const STATELESS_VERSION = "2026-07-28";
+/** @internal Whether a request is protocol 2026-07-28: its _meta names it, or its MCP-Protocol-Version header does. */
+export function is2026(req) {
+    if (req.meta?.[VERSION_META] === STATELESS_VERSION)
+        return true;
+    return req.header("mcp-protocol-version") === STATELESS_VERSION;
+}

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export { harnessAgent } from "./harness.js";
 export { WakeshiftError, isCode } from "./errors.js";
 export { parseKey, signAssertion, type AppKey } from "./key.js";
 export { WakeEvent, ArgsError, EVENT_TOOL_TEXT, SUBSCRIBE_TOOL_DESCRIPTION, UNSUBSCRIBE_TOOL_DESCRIPTION, LIST_TOOL_DESCRIPTION, BUILTIN_TOOLS, type BuiltinTool, type EventOptions, type EmitOptions, type EventStatus, type EventSubscriptionStatus, MAX_STATUS_SUBSCRIPTIONS, type EventTypeManifest, type AttachOptions, type Identity, type Subscriber, } from "./events.js";
-export { CallEnded, type Attached, type AppArgs, type EventsOptions, type Subscription, type ToolCall, type ToolCallExtra, type ToolSubscribeOptions, type WakeInputs, type WakeKey, type WakeOutputShape, type WakeShape, type WrappedResult, } from "./toolcall.js";
+export { CallEnded, type Attached, type AppArgs, type EventsOptions, type Subscription, type ToolCall, type ToolCallExtra, type ToolSubscribeOptions, type WakeArgs, type WakeInputs, type WakeInputsV3, type WakeInputsV4, type WakeKey, type WakeOutputShape, type WakeOutputV3, type WakeOutputV4, type WakeShape, type WrappedCallback, type WrappedResult, } from "./toolcall.js";
+export type { AuthInfo, CallToolResult, ContentBlock, HostContext, McpServerLike } from "./mcp.js";
 export { EXTENSION_KEY, TEXT_META, REVISION as EVENTS_REVISION } from "./spec.js";

package/dist/index.js

@@ -5,4 +5,3 @@ export { parseKey, signAssertion } from "./key.js";
 export { WakeEvent, ArgsError, EVENT_TOOL_TEXT, SUBSCRIBE_TOOL_DESCRIPTION, UNSUBSCRIBE_TOOL_DESCRIPTION, LIST_TOOL_DESCRIPTION, BUILTIN_TOOLS, MAX_STATUS_SUBSCRIPTIONS, } from "./events.js";
 export { CallEnded, } from "./toolcall.js";
 export { EXTENSION_KEY, TEXT_META, REVISION as EVENTS_REVISION } from "./spec.js";
-//# sourceMappingURL=index.js.map

package/dist/key.js

@@ -108,4 +108,3 @@ export function signAssertion(k, core, now = Date.now(), appId) {
     const input = b64({ alg: "EdDSA", typ: "app+jwt", kid: k.kid }) + "." + b64(claims);
     return input + "." + sign(null, Buffer.from(input), k.privateKey).toString("base64url");
 }
-//# sourceMappingURL=key.js.map

package/dist/mastra.d.ts

@@ -0,0 +1,79 @@
+import type * as z3 from "zod/v3";
+import type * as z4 from "zod/v4";
+import type { ToolCallExtra } from "./mcp.js";
+import type { ZodRawShapeCompat } from "./zod.js";
+import { type AttachOptions, type BuiltinTool, type Identity } from "./events.js";
+import { CallEnded, type ToolCall, type WakeArgs, type WakeInputs, type WakeInputsV3, type WakeInputsV4, type WakeOutputShape, type WakeOutputV3, type WakeOutputV4 } from "./toolcall.js";
+import type { Wakeshift } from "./wakeshift.js";
+/** The @mastra/mcp releases serve() is built for: 2.x, from 2.7. */
+export declare const MASTRA_MCP_RANGE = ">=2.7.0 <3.0.0";
+/**
+ * The request context Wakeshift reads in Mastra: the MCP SDK 2.x's
+ * ServerContext (`ctx`) of the request, the verified token in
+ * `ctx.http?.authInfo`. A Mastra tool sees the same as `context.mcp.extra`.
+ */
+export type MastraContext = ToolCallExtra;
+/** attachMastra's options: attach's, with identify and events.native getting the request's ctx. */
+export type MastraAttachOptions = AttachOptions<MastraContext>;
+/** The second argument Mastra passes a tool's execute: what Wakeshift reads of it. */
+export interface MastraToolContext {
+    mcp?: {
+        extra?: {
+            mcpReq?: object;
+            [k: string]: any;
+        };
+        [k: string]: any;
+    };
+    [k: string]: any;
+}
+/** Wakeshift in a Mastra MCPServer: make it with attachMastra, then serve your MCPServer with it. */
+export declare class MastraAttached {
+    private readonly wake;
+    private readonly opts;
+    private readonly wrapped;
+    private readonly scopes;
+    private readonly shapes;
+    private readonly served;
+    /**
+     * A tool's input schema plus Wakeshift's three optional arguments
+     * (session_key, harness and conversation_id), for a wrapped tool's
+     * inputSchema: `inputSchema: attached.inputs(z.object({ … }))`.
+     */
+    inputs<O extends z4.ZodObject>(schema: O): z4.ZodObject<O["shape"] & WakeInputsV4, O["_zod"]["config"]>;
+    inputs<O extends z3.AnyZodObject>(schema: O): z3.ZodObject<O["shape"] & WakeInputsV3, O["_def"]["unknownKeys"], O["_def"]["catchall"]>;
+    inputs<S extends ZodRawShapeCompat>(shape: S): S & WakeInputs;
+    /** A tool's output schema plus an optional wakeshift string, for a wrapped tool's outputSchema. Optional: see attach's. */
+    output<O extends z4.ZodObject>(schema: O): z4.ZodObject<O["shape"] & WakeOutputV4, O["_zod"]["config"]>;
+    output<O extends z3.AnyZodObject>(schema: O): z3.ZodObject<O["shape"] & WakeOutputV3, O["_def"]["unknownKeys"], O["_def"]["catchall"]>;
+    output<S extends ZodRawShapeCompat>(shape: S): S & WakeOutputShape;
+    /**
+     * 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<P extends Record<string, any> = Record<string, any>, R = unknown>(name: string, handler: (args: P, call: ToolCall<MastraContext>, context: MastraToolContext) => R | Promise<R>): (input: P & WakeArgs, context?: any) => Promise<R>;
+    /**
+     * 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<S extends object>(server: S): S;
+    private attachTo;
+    private wrapCalls;
+}
+/**
+ * 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 declare function attachMastra(wake: Wakeshift, opts?: MastraAttachOptions): MastraAttached;
+export { CallEnded, type BuiltinTool, type Identity, type ToolCall, type WakeArgs };