@wakeshift/sdk 0.3.0 → 0.5.0

package/dist/spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,yEAAyE;AACzE,6CAA6C;AAE7C,8BAA8B;AAC9B,MAAM,CAAC,MAAM,QAAQ,GAAG,uBAAuB,CAAC;AAEhD,6GAA6G;AAC7G,MAAM,CAAC,MAAM,aAAa,GAAG,gCAAgC,CAAC;AAC9D,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC;AAEnC,gCAAgC;AAChC,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAEtC,sFAAsF;AACtF,MAAM,CAAC,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAE7C,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAYtC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,CAAC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAK,CAAC;AACtC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,CAAC;AAErC,uEAAuE;AACvE,MAAM,UAAU,QAAQ,CAAC,OAAgB;IACvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC,KAAK,EAAE,CAAC;IAC3I,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,CAAC,KAAK,EAAE,CAAC;AAC3H,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,SAAS,CAAC,UAAkB,EAAE,SAAiB;IAC7D,OAAO,UAAU,CAAC,WAAW,EAAE,KAAK,YAAY,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7H,CAAC;AAED,mIAAmI;AACnI,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACjE,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QAChH,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["// The SEP-3415 (MCP Events) constants the SDK uses, in one place, matching\n// Wakeshift's own (internal/mcpevents/event/spec.go, which a test checks\n// these against): the draft is still moving.\n\n/** The draft these follow. */\nexport const REVISION = \"SEP-3415 (2026-10-16)\";\n\n/** Capability keys: the draft's extension, and the top-level key ChatGPT reads. A server advertises both. */\nexport const EXTENSION_KEY = \"io.modelcontextprotocol/events\";\nexport const LEGACY_KEY = \"events\";\n\n/** On every events/* result. */\nexport const RESULT_TYPE = \"complete\";\n\n/** The _meta key of an occurrence's rendered line (Wakeshift adds it on delivery). */\nexport const TEXT_META = \"ai.wakeshift/text\";\n\n/** The Streamable HTTP header events/subscribe and events/unsubscribe carry: params.name. */\nexport const NAME_HEADER = \"mcp-name\";\n\nexport type Dialect = \"draft\" | \"chatgpt\";\n\nexport interface Codes {\n  notFound: number;\n  forbidden: number;\n  resourceExhausted: number;\n  unsupported: number;\n  callbackEndpoint: number;\n}\n\nexport const INVALID_PARAMS = -32602;\nexport const HEADER_MISMATCH = -32020;\nexport const INTERNAL_ERROR = -32603;\n\n/** A dialect's error codes: the draft's (provisional) or ChatGPT's. */\nexport function codesFor(dialect: Dialect): Codes {\n  if (dialect === \"chatgpt\") {\n    return { notFound: -32011, forbidden: -32012, resourceExhausted: INVALID_PARAMS, unsupported: INVALID_PARAMS, callbackEndpoint: -32015 };\n  }\n  return { notFound: -32023, forbidden: -32024, resourceExhausted: -32025, unsupported: -32026, callbackEndpoint: -32027 };\n}\n\n/** A client's dialect, by its clientInfo name or User-Agent: ChatGPT's MCP client is openai-mcp. */\nexport function dialectOf(clientName: string, userAgent: string): Dialect {\n  return clientName.toLowerCase() === \"openai-mcp\" || userAgent.toLowerCase().startsWith(\"openai-mcp\") ? \"chatgpt\" : \"draft\";\n}\n\n/** Decodes an Mcp-Name header: plain ASCII, or SEP-2243's base64 sentinel (=?base64?…?=). null: a sentinel that doesn't decode. */\nexport function headerValue(h: string): string | null {\n  if (!h.startsWith(\"=?base64?\") || !h.endsWith(\"?=\")) return h;\n  try {\n    const b = Buffer.from(h.slice(\"=?base64?\".length, -2), \"base64\");\n    if (b.toString(\"base64\").replace(/=+$/, \"\") !== h.slice(\"=?base64?\".length, -2).replace(/=+$/, \"\")) return null;\n    return b.toString(\"utf8\");\n  } catch {\n    return null;\n  }\n}\n"]}
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,yEAAyE;AACzE,6CAA6C;AAE7C,8BAA8B;AAC9B,MAAM,CAAC,MAAM,QAAQ,GAAG,uBAAuB,CAAC;AAEhD,6IAA6I;AAC7I,MAAM,CAAC,MAAM,aAAa,GAAG,gCAAgC,CAAC;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAC;AAEtC,gCAAgC;AAChC,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAEtC,sFAAsF;AACtF,MAAM,CAAC,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAE7C,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAYtC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,CAAC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAK,CAAC;AACtC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,CAAC;AAErC,uEAAuE;AACvE,MAAM,UAAU,QAAQ,CAAC,OAAgB;IACvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC,KAAK,EAAE,CAAC;IAC3I,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,CAAC,KAAK,EAAE,CAAC;AAC3H,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,SAAS,CAAC,UAAkB,EAAE,SAAiB;IAC7D,OAAO,UAAU,CAAC,WAAW,EAAE,KAAK,YAAY,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7H,CAAC;AAED,mIAAmI;AACnI,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACjE,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QAChH,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["// The SEP-3415 (MCP Events) constants the SDK uses, in one place, matching\n// Wakeshift's own (internal/mcpevents/event/spec.go, which a test checks\n// these against): the draft is still moving.\n\n/** The draft these follow. */\nexport const REVISION = \"SEP-3415 (2026-10-16)\";\n\n/** Capability keys: the draft's extension, and the top-level key ChatGPT reads. A server advertises both; only the extension is exported. */\nexport const EXTENSION_KEY = \"io.modelcontextprotocol/events\";\nexport const TOP_LEVEL_KEY = \"events\";\n\n/** On every events/* result. */\nexport const RESULT_TYPE = \"complete\";\n\n/** The _meta key of an occurrence's rendered line (Wakeshift adds it on delivery). */\nexport const TEXT_META = \"ai.wakeshift/text\";\n\n/** The Streamable HTTP header events/subscribe and events/unsubscribe carry: params.name. */\nexport const NAME_HEADER = \"mcp-name\";\n\nexport type Dialect = \"draft\" | \"chatgpt\";\n\nexport interface Codes {\n  notFound: number;\n  forbidden: number;\n  resourceExhausted: number;\n  unsupported: number;\n  callbackEndpoint: number;\n}\n\nexport const INVALID_PARAMS = -32602;\nexport const HEADER_MISMATCH = -32020;\nexport const INTERNAL_ERROR = -32603;\n\n/** A dialect's error codes: the draft's (provisional) or ChatGPT's. */\nexport function codesFor(dialect: Dialect): Codes {\n  if (dialect === \"chatgpt\") {\n    return { notFound: -32011, forbidden: -32012, resourceExhausted: INVALID_PARAMS, unsupported: INVALID_PARAMS, callbackEndpoint: -32015 };\n  }\n  return { notFound: -32023, forbidden: -32024, resourceExhausted: -32025, unsupported: -32026, callbackEndpoint: -32027 };\n}\n\n/** A client's dialect, by its clientInfo name or User-Agent: ChatGPT's MCP client is openai-mcp. */\nexport function dialectOf(clientName: string, userAgent: string): Dialect {\n  return clientName.toLowerCase() === \"openai-mcp\" || userAgent.toLowerCase().startsWith(\"openai-mcp\") ? \"chatgpt\" : \"draft\";\n}\n\n/** Decodes an Mcp-Name header: plain ASCII, or SEP-2243's base64 sentinel (=?base64?…?=). null: a sentinel that doesn't decode. */\nexport function headerValue(h: string): string | null {\n  if (!h.startsWith(\"=?base64?\") || !h.endsWith(\"?=\")) return h;\n  try {\n    const b = Buffer.from(h.slice(\"=?base64?\".length, -2), \"base64\");\n    if (b.toString(\"base64\").replace(/=+$/, \"\") !== h.slice(\"=?base64?\".length, -2).replace(/=+$/, \"\")) return null;\n    return b.toString(\"utf8\");\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/toolcall.d.ts

@@ -0,0 +1,154 @@
+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 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>;
+declare const wakeInputs: {
+    session_key: z.ZodOptional<z.ZodString>;
+    harness: z.ZodOptional<z.ZodString>;
+    conversation_id: z.ZodOptional<z.ZodString>;
+};
+declare const wakeOutput: {
+    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;
+/** 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'). */
+export type WakeShape = ZodRawShapeCompat & {
+    [K in WakeKey]: AnySchema;
+};
+/** What a wrapped handler gets: the tool's own arguments, without Wakeshift's three. */
+export type AppArgs<S extends ZodRawShapeCompat> = Omit<ShapeOutput<S>, WakeKey>;
+/** What a wrapped handler returns: a string (one text block) or a CallToolResult. */
+export type WrappedResult = string | CallToolResult;
+/**
+ * The calling conversation's subscription, made or renewed by
+ * call.subscribe. id and user address it later: emit's
+ * `to: [{ user, subscription: id }]`, or `event.end(user, id)`.
+ */
+export interface Subscription {
+    id: string;
+    user: string;
+    /** False for a renewal. */
+    created: boolean;
+    /** The conversation's session. A secret: don't show, store or log it. */
+    session: string;
+    /** What Wakeshift recognized the agent's program as. */
+    recognized: Recognized;
+    /** The caller subscribes itself (call.native): nothing was made, id is "", and the block tells it what to subscribe to. */
+    native: boolean;
+}
+/** How call.subscribe subscribes. */
+export interface ToolSubscribeOptions {
+    /** End after this long without a delivery or a fresh subscribe (default 30 days). */
+    ttl?: Duration;
+    /** Why the app subscribes the conversation, shown in the console (at most 200 characters). */
+    reason?: string;
+    /** Names a new session (agent@label), for an app acting for its agents. */
+    label?: string;
+}
+/**
+ * One call of a wrapped tool (attached.events): who's calling, and the
+ * calls that subscribe the calling conversation. Only the wrapper makes
+ * one, and it works until the handler returns (then CallEnded).
+ */
+export interface ToolCall {
+    /** Who attach's identify says is calling (undefined for none). */
+    readonly user: string | undefined;
+    /** The tool being called. */
+    readonly tool: string;
+    /**
+     * The client subscribes to the app's events itself (MCP Events: ChatGPT,
+     * the house agents). call.subscribe then makes no conversation
+     * subscription, and the block tells it what to subscribe to.
+     */
+    readonly native: boolean;
+    /** A native client's conversation, when it names one (ChatGPT's _meta["openai/session"]). */
+    readonly nativeConversation: string | null;
+    /** The session_key passed; after a subscribe or resolveSession, the conversation's session. */
+    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;
+    /**
+     * Subscribes the calling conversation to event with args, or renews its
+     * subscription. The reply then carries what the conversation needs to be
+     * woken (one block for the call, however many subscribes it makes), and
+     * if the call fails, the subscription is ended. For a native caller
+     * nothing is made. Your tool decides who may: authorize isn't consulted.
+     * A personal event needs a user (identify's).
+     */
+    subscribe<A extends AnySchema>(event: WakeEvent<A, any>, args: SchemaInput<A>, opts?: ToolSubscribeOptions): Promise<Subscription>;
+    /**
+     * Ends the calling conversation's subscription to event with args,
+     * resolving to whether one ended. For a native caller it ends the user's
+     * own (webhook) subscriptions to the event with those arguments.
+     */
+    unsubscribe<A extends AnySchema>(event: WakeEvent<A, any>, args: SchemaInput<A>): Promise<boolean>;
+    /** Finds or starts the calling conversation's session without subscribing it (it doesn't make it wakeable). */
+    resolveSession(): Promise<string>;
+}
+/** A ToolCall used after its handler returned. */
+export declare class CallEnded extends Error {
+    constructor();
+}
+/** attach's event options. */
+export interface EventsOptions {
+    /**
+     * 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.
+     */
+    native?: (extra: ToolCallExtra) => boolean;
+}
+/** /calls/addition's answer. */
+export interface CallAddition {
+    text?: string;
+    trailer?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+export declare class Attached {
+    private readonly 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<S extends ZodRawShapeCompat>(shape: S): S & WakeInputs;
+    /**
+     * shape plus an optional wakeshift string, for a wrapped tool's
+     * outputSchema: the wrapper sets it to the block's text (without the
+     * beacon line), for hosts that show the model only structuredContent.
+     * The block stays in the content too.
+     */
+    output<S extends ZodRawShapeCompat>(shape: S): S & WakeOutputShape;
+    /**
+     * Wraps a tool's callback, for `server.registerTool(name, …)` with the
+     * same name (MCP doesn't tell a callback its tool's name): the handler
+     * gets the tool's own arguments and a ToolCall, and returns a string or
+     * a CallToolResult; the reply gets Wakeshift's block. The tool's
+     * 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>;
+    private run;
+}
+export {};