@wakeshift/sdk 0.5.2 → 0.7.0

package/dist/toolcall.d.ts

@@ -1,15 +1,14 @@
 import { z } from "zod";
-import type { CallToolResult, ServerNotification, ServerRequest } from "@modelcontextprotocol/sdk/types.js";
-import type { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
-import { type AnySchema, type SchemaInput, type ShapeOutput, type ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import * as z3 from "zod/v3";
+import * as z4 from "zod/v4";
+import type { CallToolResult, ToolCallExtra } from "./mcp.js";
+import { type AnySchema, type SchemaInput, type ShapeOutput, type ZodRawShapeCompat } from "./zod.js";
 import type { WakeEvent } from "./events.js";
 import { type Duration, type Recognized } from "./wakeshift.js";
 declare const SESSION_ARG = "session_key";
 declare const HARNESS_ARG = "harness";
 declare const CONVERSATION_ARG = "conversation_id";
-/** MCP's own extra for a tool call: the request's signal, auth, _meta, HTTP request. */
-export type ToolCallExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+export type { ToolCallExtra };
 declare const wakeInputs: {
     session_key: z.ZodOptional<z.ZodString>;
     harness: z.ZodOptional<z.ZodString>;
@@ -18,10 +17,50 @@ declare const wakeInputs: {
 declare const wakeOutput: {
     wakeshift: z.ZodOptional<z.ZodString>;
 };
+declare const byVersion: {
+    v3: {
+        inputs: {
+            session_key: z3.ZodOptional<z3.ZodString>;
+            harness: z3.ZodOptional<z3.ZodString>;
+            conversation_id: z3.ZodOptional<z3.ZodString>;
+        };
+        output: {
+            wakeshift: z3.ZodOptional<z3.ZodString>;
+        };
+    };
+    v4: {
+        inputs: {
+            session_key: z.ZodOptional<z.ZodString>;
+            harness: z.ZodOptional<z.ZodString>;
+            conversation_id: z.ZodOptional<z.ZodString>;
+        };
+        output: {
+            wakeshift: z.ZodOptional<z.ZodString>;
+        };
+    };
+};
 /** Wakeshift's three arguments, as attached.inputs adds them. */
 export type WakeInputs = typeof wakeInputs;
 /** The optional wakeshift string attached.output adds. */
 export type WakeOutputShape = typeof wakeOutput;
+/** Wakeshift's three arguments in zod 4, as attached.inputs adds them to a zod 4 object. */
+export type WakeInputsV4 = typeof byVersion.v4.inputs;
+/** Wakeshift's three arguments in zod 3, as attached.inputs adds them to a zod 3 object. */
+export type WakeInputsV3 = typeof byVersion.v3.inputs;
+/** The optional wakeshift string in zod 4, as attached.output adds it to a zod 4 object. */
+export type WakeOutputV4 = typeof byVersion.v4.output;
+/** The optional wakeshift string in zod 3, as attached.output adds it to a zod 3 object. */
+export type WakeOutputV3 = typeof byVersion.v3.output;
+/** What a wrapped tool's arguments must include: Wakeshift's three (attached.inputs adds them). */
+export type WakeArgs = {
+    [K in WakeKey]?: string | undefined;
+};
+/**
+ * The callback attached.events returns, for `server.registerTool`: it takes
+ * the tool's arguments (A, Wakeshift's three included) and your MCP SDK's
+ * request context (C).
+ */
+export type WrappedCallback<A, C> = (args: A, extra: C) => Promise<any>;
 /** The names of Wakeshift's three arguments. */
 export type WakeKey = typeof SESSION_ARG | typeof HARNESS_ARG | typeof CONVERSATION_ARG;
 /** An input shape with Wakeshift's three arguments in it (attached.inputs'). */
@@ -63,7 +102,7 @@ export interface ToolSubscribeOptions {
  * calls that subscribe the calling conversation. Only the wrapper makes
  * one, and it works until the handler returns (then CallEnded).
  */
-export interface ToolCall {
+export interface ToolCall<C = any> {
     /** Who attach's identify says is calling (undefined for none). */
     readonly user: string | undefined;
     /** The tool being called. */
@@ -80,8 +119,8 @@ export interface ToolCall {
     readonly session: string | null;
     /** What Wakeshift recognized the agent's program as: null until a subscribe or resolveSession. */
     readonly recognized: Recognized | null;
-    /** MCP's own extra for the call. */
-    readonly extra: ToolCallExtra;
+    /** The call's request context, as your MCP SDK passes it to the tool's callback: 2.x's ctx, 1.x's extra. */
+    readonly extra: C;
     /**
      * Subscribes the calling conversation to event with args, or renews its
      * subscription. The reply then carries what the conversation needs to be
@@ -105,14 +144,14 @@ export declare class CallEnded extends Error {
     constructor();
 }
 /** attach's event options. */
-export interface EventsOptions {
+export interface EventsOptions<C = any> {
     /**
      * Asked first whether a wrapped tool's call comes from a client that
      * subscribes to the app's events itself (call.native), for callers the
      * SDK can't tell (an app's own house agents). False leaves it to the
-     * SDK's own checks.
+     * SDK's own checks. It gets the call's request context, as identify does.
      */
-    native?: (extra: ToolCallExtra) => boolean;
+    native?(extra: C): boolean;
 }
 /** /calls/addition's answer. */
 export interface CallAddition {
@@ -125,24 +164,33 @@ export declare const WAKESHIFT_FIELD = "wakeshift";
 /**
  * Wakeshift attached to an MCP server: the handle `wake.attach` returns.
  * Wrap a tool's callback with events, and give its input schema
- * Wakeshift's three arguments with inputs.
+ * Wakeshift's three arguments with inputs. C is your MCP SDK's request
+ * context (2.x's ctx, 1.x's extra), which a wrapped call carries as
+ * `call.extra`.
  */
-export declare class Attached {
+export declare class Attached<C = any> {
     private readonly at;
     /**
-     * shape plus Wakeshift's three optional arguments (session_key, harness
-     * and conversation_id), for a wrapped tool's inputSchema:
+     * A tool's input schema plus Wakeshift's three optional arguments
+     * (session_key, harness and conversation_id), for a wrapped tool's
+     * inputSchema: a zod object, `inputSchema: attached.inputs(z.object({ table: z.string() }))`
+     * (as @modelcontextprotocol/server 2.x takes it), or a shape,
      * `inputSchema: attached.inputs({ table: z.string() })`.
      */
+    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;
     /**
-     * shape plus an optional wakeshift string, for a wrapped tool's
-     * outputSchema. Optional: every structured result of a wrapped tool gets
-     * the block's text (without the beacon line) in wakeshift, for hosts that
-     * show the model only structuredContent, and tools/list names it in the
-     * tool's output schema; this declares it in your own schema and types.
-     * The block stays in the content too.
+     * A tool's output schema plus an optional wakeshift string, for a wrapped
+     * tool's outputSchema (a zod object or a shape, as inputs takes).
+     * Optional: every structured result of a wrapped tool gets the block's
+     * text (without the beacon line) in wakeshift, for hosts that show the
+     * model only structuredContent, and tools/list names it in the tool's
+     * output schema; this declares it in your own schema and types. The
+     * block stays in the content too.
      */
+    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 tool's callback, for `server.registerTool(name, …)` with the
@@ -152,8 +200,8 @@ export declare class Attached {
      * inputSchema must come from attached.inputs (a type error otherwise).
      * Register it on the server passed to attach.
      */
-    events<S extends WakeShape>(name: string, handler: (args: AppArgs<S>, call: ToolCall) => WrappedResult | Promise<WrappedResult>): ToolCallback<S>;
+    events<A extends WakeArgs>(name: string, handler: (args: Omit<A, WakeKey>, call: ToolCall<C>) => WrappedResult | Promise<WrappedResult>): WrappedCallback<A, C>;
     private run;
+    amendToolsList(): void;
     private amendTools;
 }
-export {};

package/dist/toolcall.js

@@ -18,11 +18,12 @@
 import { z } from "zod";
 import * as z3 from "zod/v3";
 import * as z4 from "zod/v4";
-import { getObjectShape, isZ4Schema, normalizeObjectSchema, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import * as z4mini from "zod/v4-mini";
+import { getObjectShape, isSchema, isZ4Schema, normalizeObjectSchema } from "./zod.js";
 import { WakeshiftError } from "./errors.js";
 import { EXTENSION_KEY, dialectOf } from "./spec.js";
 import { takesTasks } from "./discover.js";
-import { packCall } from "./wakeshift.js";
+import { packCall, userAgentOf } from "./wakeshift.js";
 // Wakeshift's three arguments (wakeshift.ts's SESSION_ARG, HARNESS_ARG and
 // CONVERSATION_ARG, repeated: that module imports this one).
 const SESSION_ARG = "session_key";
@@ -66,12 +67,26 @@ const byVersion = {
     },
 };
 // fieldsFor is Wakeshift's fields in the zod API shape's own fields use
-// (the default import's for an empty shape).
-function fieldsFor(shape, kind) {
+// (for an empty shape, the default import's, or zod 4's for the MCP SDK
+// 2.x, which takes only zod 4).
+function fieldsFor(shape, kind, host) {
     const first = Object.values(shape ?? {})[0];
-    const fields = !first ? (kind === "inputs" ? wakeInputs : wakeOutput) : byVersion[isZ4Schema(first) ? "v4" : "v3"][kind];
+    const version = first ? (isZ4Schema(first) ? "v4" : "v3") : host?.version === 2 ? "v4" : null;
+    const fields = version ? byVersion[version][kind] : kind === "inputs" ? wakeInputs : wakeOutput;
     return fields;
 }
+/** @internal Wakeshift's three arguments as attach's own tools take them, in the zod the host's MCP SDK takes. */
+export function wakeInputsFor(host) {
+    return host.version === 2 ? byVersion.v4.inputs : wakeInputs;
+}
+// withFields is an object schema with fields added, in the schema's own zod
+// API (zod 3, zod 4 classic or mini).
+function withFields(schema, fields) {
+    const s = schema;
+    if (typeof s.extend === "function")
+        return s.extend(fields);
+    return z4mini.extend(schema, fields);
+}
 const WAKE_KEYS = [SESSION_ARG, HARNESS_ARG, CONVERSATION_ARG];
 /**
  * @internal The tools/call _meta keys a harness names its conversation in
@@ -209,14 +224,8 @@ function sameJSON(a, b) {
 function detailOf(err) {
     return err instanceof WakeshiftError ? err.detail : String(err?.message ?? err);
 }
-function registeredTool(server, name) {
-    const tools = server._registeredTools;
-    if (!tools || typeof tools !== "object")
-        return null; // an MCP SDK that keeps them elsewhere
-    return tools[name];
-}
-/** One tools/call of a wrapped tool: what its handler subscribed, for the block and the rollback. */
-class CallScope {
+/** @internal One tools/call of a wrapped tool: what its handler subscribed, for the block and the rollback. */
+export class CallScope {
     at;
     args;
     user;
@@ -252,17 +261,18 @@ class CallScope {
     // User-Agent, the agent's harness and conversation_id arguments, the
     // conversation's session, and who's calling.
     wire(session = this.session) {
-        const meta = this.extra._meta;
+        const req = this.at.host.req(this.extra);
+        const meta = req.meta;
         return packCall({
             meta,
             clientName: this.at.clientOf(meta, this.identified),
             user: this.user,
             session: session ?? undefined,
-            userAgent: userAgentOf(this.extra),
+            userAgent: userAgentOf(req),
             harness: this.args.harness,
             conversation: this.args.conversation,
             tool: this.tool,
-            tasks: takesTasks(meta, this.extra),
+            tasks: takesTasks(meta, req),
         });
     }
     // request runs one request of the call to Wakeshift, after any before it
@@ -415,19 +425,12 @@ class CallScope {
 function recognizedOf(a) {
     return { harness: a?.harness ?? null, via: a?.via ?? null, claimed: a?.claimed ?? null };
 }
-function headerOf(extra, name) {
-    const h = extra?.requestInfo?.headers;
-    if (!h)
-        return "";
-    const v = h[name] ?? h[name.toLowerCase()];
-    return (Array.isArray(v) ? v[0] : v) ?? "";
-}
-function userAgentOf(extra) {
-    return headerOf(extra, "user-agent") || headerOf(extra, "User-Agent");
-}
 function hasKey(o, key) {
     return !!o && typeof o === "object" && !Array.isArray(o) && o[key] !== undefined;
 }
+function isRecord(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
 /**
  * @internal Whether a call comes from a client that subscribes to the app's
  * events itself, on stateless servers too (which never see initialize), in
@@ -438,15 +441,19 @@ function hasKey(o, key) {
  * _meta's). conversation is ChatGPT's conversation, when it names one.
  */
 export function nativeOf(at, extra, identified) {
-    const meta = (extra._meta ?? {});
+    // A server that doesn't serve MCP Events (an xmcp app's) has no native callers.
+    if (!at.host.servesEvents)
+        return { native: false, conversation: null };
+    const req = at.host.req(extra);
+    const meta = (req.meta ?? {});
     const conversation = typeof meta["openai/session"] === "string" && meta["openai/session"] ? meta["openai/session"] : null;
     if (at.events.native?.(extra))
         return { native: true, conversation };
     if (conversation)
         return { native: true, conversation };
-    if (dialectOf(at.clientOf(meta, identified), userAgentOf(extra)) === "chatgpt")
+    if (dialectOf(at.clientOf(meta, identified), userAgentOf(req)) === "chatgpt")
         return { native: true, conversation: null };
-    const caps = at.server.server.getClientCapabilities();
+    const caps = at.host.clientCapabilities();
     if (hasKey(caps?.extensions, EXTENSION_KEY))
         return { native: true, conversation: null };
     const metaCaps = meta["io.modelcontextprotocol/clientCapabilities"];
@@ -457,7 +464,9 @@ export function nativeOf(at, extra, identified) {
 /**
  * Wakeshift attached to an MCP server: the handle `wake.attach` returns.
  * Wrap a tool's callback with events, and give its input schema
- * Wakeshift's three arguments with inputs.
+ * Wakeshift's three arguments with inputs. C is your MCP SDK's request
+ * context (2.x's ctx, 1.x's extra), which a wrapped call carries as
+ * `call.extra`.
  */
 export class Attached {
     at;
@@ -467,29 +476,33 @@ export class Attached {
     constructor(at) {
         this.at = at;
     }
-    /**
-     * shape plus Wakeshift's three optional arguments (session_key, harness
-     * and conversation_id), for a wrapped tool's inputSchema:
-     * `inputSchema: attached.inputs({ table: z.string() })`.
-     */
     inputs(shape) {
+        if (isSchema(shape)) {
+            const own = getObjectShape(shape);
+            if (!own)
+                throw new Error("wakeshift: attached.inputs takes a zod object or a shape");
+            for (const k of WAKE_KEYS)
+                if (k in own)
+                    throw new Error(`wakeshift: attached.inputs adds ${k} itself: leave it out of the schema`);
+            return withFields(shape, byVersion[isZ4Schema(shape) ? "v4" : "v3"].inputs);
+        }
         for (const k of WAKE_KEYS)
             if (k in (shape ?? {}))
                 throw new Error(`wakeshift: attached.inputs adds ${k} itself: leave it out of the shape`);
-        return { ...shape, ...fieldsFor(shape, "inputs") };
+        return { ...shape, ...fieldsFor(shape, "inputs", this.at.host) };
     }
-    /**
-     * shape plus an optional wakeshift string, for a wrapped tool's
-     * outputSchema. Optional: every structured result of a wrapped tool gets
-     * the block's text (without the beacon line) in wakeshift, for hosts that
-     * show the model only structuredContent, and tools/list names it in the
-     * tool's output schema; this declares it in your own schema and types.
-     * The block stays in the content too.
-     */
     output(shape) {
+        if (isSchema(shape)) {
+            const own = getObjectShape(shape);
+            if (!own)
+                throw new Error("wakeshift: attached.output takes a zod object or a shape");
+            if (WAKESHIFT_FIELD in own)
+                throw new Error("wakeshift: attached.output adds wakeshift itself: leave it out of the schema");
+            return withFields(shape, byVersion[isZ4Schema(shape) ? "v4" : "v3"].output);
+        }
         if ("wakeshift" in (shape ?? {}))
             throw new Error("wakeshift: attached.output adds wakeshift itself: leave it out of the shape");
-        return { ...shape, ...fieldsFor(shape, "output") };
+        return { ...shape, ...fieldsFor(shape, "output", this.at.host) };
     }
     /**
      * Wraps a tool's callback, for `server.registerTool(name, …)` with the
@@ -509,7 +522,8 @@ export class Attached {
         return cb;
     }
     async run(name, cb, handler, input, extra) {
-        const tool = registeredTool(this.at.server, name);
+        const host = this.at.host;
+        const tool = host.registeredTool(name);
         if (tool === undefined || (tool && (tool.handler ?? tool.callback) !== cb)) {
             throw new Error(`wakeshift: attached.events("${name}", …) isn't the tool named ${name} on the server passed to attach: register it with the same name, on that server`);
         }
@@ -521,24 +535,49 @@ export class Attached {
             }
             outputSchema = tool.outputSchema;
         }
-        else {
+        else if (!host.framework) {
             this.at.warnOnce("internals", "wakeshift: this MCP SDK keeps its tools where Wakeshift can't read them, so wrapped tools' registration and output aren't checked");
         }
-        const str = (k) => (typeof input[k] === "string" && input[k] ? input[k] : undefined);
-        const call = new CallScope(this.at, name, extra, { session: str(SESSION_ARG), harness: str(HARNESS_ARG), conversation: str(CONVERSATION_ARG) });
-        const appArgs = {};
-        for (const [k, v] of Object.entries(input))
-            if (!WAKE_KEYS.includes(k))
-                appArgs[k] = v;
+        const { call, appArgs } = this.begin(name, input, extra);
         let result;
         try {
             result = await handler(appArgs, call);
         }
         catch (err) {
-            await call.end();
-            await call.rollback();
+            await this.fail(call);
             throw err;
         }
+        return this.finish(call, result, outputSchema);
+    }
+    /**
+     * @internal The first half of a wrapped call: the call's scope, from the
+     * tool's arguments (Wakeshift's three among them) and the request's
+     * context, and the app's own arguments. finish (or fail) ends it.
+     */
+    begin(name, input, extra) {
+        const str = (k) => (typeof input[k] === "string" && input[k] ? input[k] : undefined);
+        const call = new CallScope(this.at, name, extra, { session: str(SESSION_ARG), harness: str(HARNESS_ARG), conversation: str(CONVERSATION_ARG) });
+        const appArgs = {};
+        for (const [k, v] of Object.entries(input ?? {}))
+            if (!WAKE_KEYS.includes(k))
+                appArgs[k] = v;
+        return { call, appArgs };
+    }
+    /** @internal Ends a call whose handler threw: what it subscribed is rolled back. */
+    async fail(call) {
+        await call.end();
+        await call.rollback();
+    }
+    /**
+     * @internal The second half of a wrapped call: the handler's result with
+     * Wakeshift's block, or rolled back (a failed result, a canceled call, an
+     * output its schema refuses). outputSchema is the tool's, as its MCP SDK
+     * checks it (undefined: not checked here).
+     */
+    async finish(call, result, outputSchema) {
+        const host = this.at.host;
+        const name = call.tool;
+        const extra = call.extra;
         await call.end();
         // Rollback is decided from the final result, the one the client would
         // receive: MCP validates the output after this callback returns, so
@@ -547,7 +586,7 @@ export class Attached {
             await call.rollback();
             return result;
         }
-        if ((typeof result === "object" && result.isError) || extra?.signal?.aborted || !(await validOutput(outputSchema, result))) {
+        if ((typeof result === "object" && result.isError) || host.req(extra).signal?.aborted || !(await host.validOutput(outputSchema, result))) {
             await call.rollback();
             return typeof result === "string" ? { content: [{ type: "text", text: result }] } : result;
         }
@@ -563,7 +602,7 @@ export class Attached {
             return { isError: true, content: [{ type: "text", text: `Wakeshift couldn't finish setting up this conversation's wakes (${detailOf(err)}). Try again.` }] };
         }
         const out = mergeBlock(result, add ?? {});
-        if (out.structuredContent && WAKESHIFT_FIELD in out.structuredContent && !(await validOutput(outputSchema, out))) {
+        if (isRecord(out.structuredContent) && WAKESHIFT_FIELD in out.structuredContent && !(await host.validOutput(outputSchema, out))) {
             // A schema that refuses fields it doesn't name (a strict object):
             // MCP would refuse the result, so it goes without the field.
             const { [WAKESHIFT_FIELD]: _dropped, ...own } = out.structuredContent;
@@ -578,9 +617,14 @@ export class Attached {
      * sets the handler when the first tool is registered, perhaps after
      * attach, so a later set is wrapped too (as tasks.ts does).
      */
+    /** @internal Marks name as a wrapped tool, for tools/list (a framework adapter's tool, wrapped outside this handle). */
+    markWrapped(name) {
+        if (!this.wrapped.has(name))
+            this.wrapped.set(name, true);
+    }
     amendToolsList() {
-        const handlers = this.at.server.server._requestHandlers;
-        if (!(handlers instanceof Map))
+        const handlers = this.at.host.handlers();
+        if (!handlers)
             return; // a future SDK: schemas stay as registered
         const wrap = (h) => async (request, extra) => {
             const out = await h(request, extra);
@@ -605,16 +649,3 @@ export class Attached {
         }
     }
 }
-// validOutput mirrors McpServer's own check of a result against the tool's
-// outputSchema (validateToolOutput): one it would refuse fails the call.
-async function validOutput(outputSchema, result) {
-    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;
-}
-//# sourceMappingURL=toolcall.js.map

package/dist/wakeshift.d.ts

@@ -1,5 +1,5 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { AnySchema } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import type { AnySchema } from "./zod.js";
+import type { HostContext, McpServerLike } from "./mcp.js";
 import { WakeEvent, type AttachOptions, type EventOptions, type EventTypeManifest } from "./events.js";
 import type { Attached } from "./toolcall.js";
 /** Wakeshift's production core, the default for every key but an older wst_test_ one. Override with `core` or WAKESHIFT_CORE. */
@@ -231,8 +231,12 @@ export declare class Wakeshift {
      * It returns the handle your own tools use to subscribe the conversation
      * calling them: wrap a tool's callback with attached.events, and give it
      * Wakeshift's arguments with attached.inputs.
+     *
+     * server is an McpServer from @modelcontextprotocol/server 2.x or
+     * @modelcontextprotocol/sdk 1.x; identify gets that SDK's own request
+     * context (2.x's ctx, 1.x's extra).
      */
-    attach(server: McpServer, opts?: AttachOptions): Attached;
+    attach<S extends McpServerLike>(server: S, opts?: AttachOptions<HostContext<S>>): Attached<HostContext<S>>;
     /**
      * The workspace Wakeshift keeps for one of the app's users (user: the
      * app's own ID for them, as attach's identify gives it), created on first

package/dist/wakeshift.js

@@ -1,4 +1,5 @@
 import { WakeshiftError } from "./errors.js";
+import { v1Req } from "./host.js";
 import { WakeEvent, attachEvents } from "./events.js";
 import { parseKey, signAssertion, isTestKey } from "./key.js";
 import { retryRefused } from "./retry.js";
@@ -33,14 +34,9 @@ function recipientsOf(raw) {
     }
     return out;
 }
-// userAgentOf is the User-Agent of the HTTP request a tool call came in
-// ("" if there's none, e.g. over stdio).
-function userAgentOf(extra) {
-    const headers = extra?.requestInfo?.headers;
-    if (!headers)
-        return "";
-    const v = headers["user-agent"] ?? headers["User-Agent"];
-    return (Array.isArray(v) ? v[0] : v) ?? "";
+/** @internal The User-Agent of the HTTP request a tool call came in ("" if there's none, e.g. over stdio). */
+export function userAgentOf(req) {
+    return req.header("user-agent") || req.header("User-Agent");
 }
 /** @internal Packs a tool call as Wakeshift takes it: empty fields left out, the agent's claims trimmed. */
 export function packCall(c) {
@@ -69,16 +65,17 @@ export function packCall(c) {
  * session_key, harness and conversation_id from its arguments.
  */
 export function toolCallOf(extra, client, user, args, tool) {
+    const req = v1Req(extra); // a request already read passes through
     return packCall({
-        meta: extra?._meta,
+        meta: req.meta,
         clientName: client,
         user,
         session: str(args, SESSION_ARG),
-        userAgent: userAgentOf(extra),
+        userAgent: userAgentOf(req),
         harness: str(args, HARNESS_ARG),
         conversation: str(args, CONVERSATION_ARG),
         tool,
-        tasks: takesTasks(extra?._meta, extra),
+        tasks: takesTasks(req.meta, req),
     });
 }
 // str is a tool argument's value if it's a string.
@@ -297,12 +294,25 @@ export class Wakeshift {
      * It returns the handle your own tools use to subscribe the conversation
      * calling them: wrap a tool's callback with attached.events, and give it
      * Wakeshift's arguments with attached.inputs.
+     *
+     * server is an McpServer from @modelcontextprotocol/server 2.x or
+     * @modelcontextprotocol/sdk 1.x; identify gets that SDK's own request
+     * context (2.x's ctx, 1.x's extra).
      */
     attach(server, opts = {}) {
         const attached = attachEvents(this, server, [...this.events.values()], opts);
         this.serving = true; // the manifest is sent automatically from now on
         return attached;
     }
+    /**
+     * @internal For a framework adapter (@wakeshift/sdk/mastra, /xmcp): the
+     * defined events, and from now on this process serves the app's tools,
+     * so the manifest is sent automatically, as after attach.
+     */
+    serveEvents() {
+        this.serving = true;
+        return [...this.events.values()];
+    }
     /**
      * @internal Sends the manifest with the defined events, once (again after
      * a defineEvent), from a process that serves the app's tools (attach). A
@@ -409,4 +419,3 @@ export class Wakeshift {
         return new WakeshiftError(0, "unreachable", `can't reach Wakeshift at ${this.core} (${why}). Check that WAKESHIFT_CORE, or the core option, is the address of the console your key came from`, { cause: err });
     }
 }
-//# sourceMappingURL=wakeshift.js.map

package/dist/xmcp.d.ts

@@ -0,0 +1,73 @@
+import type { AuthInfo, CallToolResult } from "./mcp.js";
+import type { ZodRawShapeCompat } from "./zod.js";
+import { BUILTIN_TOOLS, type BuiltinTool, type Identity } from "./events.js";
+import { type ToolCall, type WakeArgs, type WakeInputs, type WrappedResult } from "./toolcall.js";
+import type { Wakeshift } from "./wakeshift.js";
+/** The request context xmcp passes a tool's handler, its second argument: what Wakeshift reads of it. */
+export interface XmcpExtra {
+    signal?: AbortSignal;
+    authInfo?: AuthInfo;
+    sessionId?: string;
+    _meta?: Record<string, unknown>;
+    requestId?: string | number;
+    requestInfo?: {
+        headers?: Record<string, string | string[] | undefined>;
+    };
+    clientInfo?: {
+        name?: string;
+        version?: string;
+    };
+    [k: string]: any;
+}
+/** attachXmcp's options. */
+export interface XmcpAttachOptions {
+    /**
+     * Who is behind a request: { user }, your own ID for the person, from your
+     * own sign-in (the verified token is extra.authInfo). Without it, requests
+     * have no user, so personal events and list_subscriptions refuse.
+     */
+    identify?(extra: XmcpExtra): Identity | undefined;
+    /** Which of attach's own tools attached.tool gives (default: all three). */
+    tools?: readonly BuiltinTool[];
+}
+/** One of attach's own tools as an xmcp tool file exports it. */
+export interface XmcpTool {
+    /** The tool's input, a zod 4 shape: `export const schema = tool.schema`. */
+    schema: ZodRawShapeCompat;
+    /** Its name, description and annotations: `export const metadata = tool.metadata`. */
+    metadata: {
+        name: string;
+        description: string;
+        annotations?: Record<string, unknown>;
+    };
+    /** Its handler: `export default tool.handler`. */
+    handler: (args: Record<string, unknown>, extra: XmcpExtra) => Promise<CallToolResult>;
+}
+/** Wakeshift in an xmcp app: what your tool files use. Make it with attachXmcp. */
+export declare class XmcpAttached {
+    private readonly attached;
+    private readonly own;
+    /**
+     * A tool's schema plus Wakeshift's three optional arguments (session_key,
+     * harness and conversation_id): `export const schema = attached.inputs({ … })`.
+     */
+    inputs<S extends ZodRawShapeCompat>(shape: S): S & WakeInputs;
+    /**
+     * Wraps a tool's handler, for the tool file whose metadata names the same
+     * tool: `export default attached.events("watch_ci", async (args, call) => …)`.
+     * handler gets your own arguments and a ToolCall, and returns a string or
+     * a CallToolResult; the reply gets what Wakeshift adds for the
+     * conversation, and a call that fails ends the subscriptions it made. Its
+     * schema must come from attached.inputs.
+     */
+    events<P extends Record<string, any> = Record<string, any>>(name: string, handler: (args: P, call: ToolCall<XmcpExtra>) => WrappedResult | Promise<WrappedResult>): (args: P & WakeArgs, extra: XmcpExtra) => Promise<CallToolResult>;
+    /** One of attach's own tools, for a tool file of its own (src/tools/<name>.ts): its schema, metadata and handler. */
+    tool(name: BuiltinTool): XmcpTool;
+}
+/**
+ * Attaches Wakeshift to an xmcp app, after your last defineEvent. Returns
+ * what your tool files use: attached.inputs and attached.events for your
+ * own tools that subscribe, and attached.tool for attach's own three.
+ */
+export declare function attachXmcp(wake: Wakeshift, opts?: XmcpAttachOptions): XmcpAttached;
+export { BUILTIN_TOOLS, type BuiltinTool, type Identity, type ToolCall, type WakeArgs, type WrappedResult };