@wakeshift/sdk 0.0.0-stage → 0.2.0

package/dist/spec.js.map

@@ -0,0 +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"]}

package/dist/wakeshift.d.ts

@@ -0,0 +1,415 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AnySchema } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import { WakeEvent, type AttachOptions, type EventOptions, type EventTypeManifest } from "./events.js";
+/** Wakeshift's production core, the default for every key but an older wst_test_ one. Override with `core` or WAKESHIFT_CORE. */
+export declare const DEFAULT_CORE = "https://app.wakeshift.ai";
+/** The tool argument an agent passes its session key in (a result gives it one). */
+export declare const SESSION_ARG = "session_key";
+/** The tool argument an agent says which program it runs in with. */
+export declare const HARNESS_ARG = "harness";
+/**
+ * The tool argument an agent passes its own ID for the conversation in,
+ * when its program gives it one (Cursor and Grok Bot: CURSOR_CONVERSATION_ID).
+ */
+export declare const CONVERSATION_ARG = "conversation_id";
+export interface WakeshiftOptions {
+    /** The app key from the console: wst_ and 50 characters (or an older wst_test_… or wst_live_… key). */
+    key: string;
+    /**
+     * Wakeshift's base URL: the console you got the key from. Default:
+     * WAKESHIFT_CORE from the environment, else https://app.wakeshift.ai.
+     * An older wst_test_… key has no default: it needs one of the two.
+     */
+    core?: string;
+    /** Default: the global fetch. */
+    fetch?: typeof fetch;
+    /** Per-request timeout in milliseconds. Default 20000. */
+    timeoutMs?: number;
+    /**
+     * Called with a problem that doesn't fail the call but makes it work less
+     * well, for example a tool call Wakeshift recognised no harness in. Each kind is
+     * reported once. Default: console.warn.
+     */
+    onWarning?: (message: string) => void;
+}
+/** Which app a key is, as Wakeshift says (wake.app()). */
+export interface AppInfo {
+    id: string;
+    name: string;
+}
+/** What the SDK says, once, when Wakeshift recognised no harness in a tool call. */
+export declare const UNKNOWN_CLIENT_WARNING: string;
+/**
+ * Who called one of the app's tools, as Wakeshift needs it. Make one with
+ * `wake.call(extra, …)` inside an MCP tool callback, or `wake.callOf(…)`.
+ */
+export interface Call {
+    /** The app's own ID for the person (optional). */
+    user?: string;
+    /**
+     * The MCP client's name (initialize's clientInfo.name). A stateless
+     * server has none; Wakeshift then tells the harness from meta, else
+     * user_agent.
+     */
+    client: string;
+    /** The tool call's _meta (Codex sends its thread there). */
+    meta?: Record<string, unknown>;
+    /** The session handle an earlier result gave the agent. */
+    session?: string;
+    /** The MCP request's HTTP User-Agent. */
+    user_agent?: string;
+    /** The conversation's ID as the agent passed it (conversation_id: Cursor's CURSOR_CONVERSATION_ID). */
+    conversation?: string;
+    /** The program the agent says it runs in (harness): a hint, never a credential. */
+    harness?: string;
+}
+/**
+ * What Wakeshift recognised the calling conversation's harness as, and by
+ * which signal ("claim": only the agent's harness argument named it); both
+ * null when nothing named one. claimed is what the agent said (normalized:
+ * "Grok Bot" is grok-bot), null if it didn't; a claimed that differs from
+ * harness was ignored, since it contradicted what the call was recognised
+ * as (the claim only refines it: Cursor's calls may be Grok Bot's).
+ */
+export interface Recognised {
+    harness: string | null;
+    via: "client" | "meta" | "user_agent" | "claim" | null;
+    claimed: string | null;
+}
+/**
+ * Seconds, or a string like "90s", "5m", "2h", "30d". Wakeshift checks the
+ * value: days must be whole ("1.5d" is a bad_request; use "36h").
+ */
+export type Duration = number | `${number}${"s" | "m" | "h" | "d"}`;
+export interface SubscribeOptions {
+    /** Wake only for events whose data has these top-level fields equal to these values. */
+    filter?: Record<string, string | number | boolean | null>;
+    /** End after the first delivery. */
+    once?: boolean;
+    /** Deliver the latest event published within this long before subscribing (at most 24 hours). */
+    replay?: Duration;
+    /** End after this long without a delivery or a fresh subscribe (1 minute to 365 days; default 30 days). */
+    ttl?: Duration;
+}
+/** What Wakeshift adds to a tool result: text for the agent, _meta for its harness. */
+export interface Addition {
+    text?: string;
+    meta?: Record<string, unknown>;
+    /** What Wakeshift recognised the caller's harness as (not added to the result). */
+    agent?: Recognised;
+}
+export interface Subscription {
+    /** For `send`. */
+    id: string;
+    topic: string;
+    filter?: Record<string, unknown>;
+    once: boolean;
+    expiresAt: Date;
+    /**
+     * The conversation's session key (the agent passes it back as session_key;
+     * the result says so). It's a secret that acts as the conversation: don't
+     * show, store or log it. To name the conversation, use id, or an HMAC of it.
+     */
+    session: string;
+    /** What the tool result must carry for the caller's harness. */
+    addition: Addition;
+    /** What Wakeshift recognised the caller's harness as. */
+    agent: Recognised;
+    /**
+     * The tool result to return: your text (or result) followed by
+     * Wakeshift's, with its _meta.
+     */
+    result(text: string | CallToolResult): CallToolResult;
+}
+export interface TopicEvent {
+    /** What the agent reads first (at most 1000 bytes). */
+    text: string;
+    /** A JSON object, within the 64 KB request limit; filters match its top-level fields. */
+    data?: Record<string, unknown>;
+    /** Makes retries publish once for a day (at most 200 characters); after a day, the same id publishes again. */
+    id?: string;
+}
+export interface Published {
+    /** Conversations it woke (or will). */
+    matched: number;
+    /** An earlier publish had this event's id. */
+    duplicate: boolean;
+}
+/** delivered: on its way to a connected conversation; queued: waits for it; closed: the subscription ended. */
+export type SendStatus = "delivered" | "queued" | "closed";
+/**
+ * How a conversation is connected: stream (a stream held open, e.g.
+ * Cursor's background command), poll (long polls or waits, e.g. Claude
+ * Code's Monitor, in the last minute) or hooks (Wakeshift's hooks or
+ * connector on the user's machine).
+ */
+export type Via = "stream" | "poll" | "hooks" | "webhook";
+export interface TopicStatus {
+    topic: string;
+    /** Conversations subscribed (ended or expired subscriptions don't count). */
+    subscriptions: number;
+    /** Of those, connected now. */
+    connected: number;
+    /** How many are connected each way. */
+    via: Record<Via, number>;
+}
+export interface SubscriptionStatus {
+    id: string;
+    topic: string;
+    status: "active" | "closed";
+    connected: boolean;
+    via?: Via;
+    expiresAt?: Date;
+}
+/** A publish URL: `topic` for a topic's (`wake.publishUrl`), `event` for an event's (`event.publishUrl`). */
+export interface PublishUrl {
+    id: string;
+    topic?: string;
+    event?: string;
+    url: string;
+}
+/** An event pattern a manifest asks for, and what the person is told it's for. */
+export interface ScopeEvent {
+    pattern: string;
+    description: string;
+}
+/** What the app may do with the agents in the workspaces it keeps (manifest.agent). */
+export interface AgentScope {
+    wake: ScopeEvent[];
+    post: ScopeEvent[];
+    /** Days the person's consent lasts. */
+    ttl_days: number;
+    /** At most max wake-ups in any seconds, on top of Wakeshift's own limits. */
+    wake_limits?: {
+        seconds: number;
+        max: number;
+    }[];
+    /** What the person should say to their agent once it's connected; at most 120 characters. */
+    start_prompt?: string;
+    groups?: boolean;
+}
+/** What the app tells Wakeshift it may do (see wake.publishManifest). */
+export interface Manifest {
+    description?: string;
+    agent?: AgentScope;
+    /** The app's event types: defineEvent fills this in for you. */
+    events?: EventTypeManifest[];
+}
+/** The parts of an MCP tool callback's `extra` that Wakeshift reads. */
+export interface ToolExtra {
+    _meta?: Record<string, unknown>;
+    requestInfo?: {
+        headers?: Record<string, string | string[] | undefined>;
+    };
+}
+/** An McpServer or a low-level Server: anything that knows its client's name. */
+export type ClientInfoSource = {
+    getClientVersion(): {
+        name: string;
+    } | undefined;
+} | {
+    server: {
+        getClientVersion(): {
+            name: string;
+        } | undefined;
+    };
+};
+export interface CallOptions {
+    /** The MCP server the call came to, for the client's name (or pass client). */
+    server?: ClientInfoSource;
+    /** The client's name, if you know it (instead of server). */
+    client?: string;
+    /** The app's own ID for the person. */
+    user?: string;
+    /** The tool's arguments: session_key, harness and conversation_id (wake.args) are read from them. */
+    args?: {
+        [SESSION_ARG]?: string;
+        [HARNESS_ARG]?: string;
+        [CONVERSATION_ARG]?: string;
+    } | Record<string, unknown>;
+    /** The session key, if you read it yourself. */
+    session?: string;
+    /** The program the agent says it runs in (harness), if you read it yourself. */
+    harness?: string;
+    /** The conversation's ID the agent passed (conversation_id), if you read it yourself. */
+    conversation?: string;
+}
+export declare function clientNameOf(s: ClientInfoSource): string;
+/** Adds Wakeshift's text and _meta to a tool result (a copy). */
+export declare function applyAddition(a: Addition, base: string | CallToolResult): CallToolResult;
+declare const argsShape: {
+    session_key: z.ZodOptional<z.ZodString>;
+    harness: z.ZodOptional<z.ZodString>;
+    conversation_id: z.ZodOptional<z.ZodString>;
+};
+/**
+ * The Wakeshift client for an app: subscribe the conversations that call
+ * your tools to topics, and publish to them.
+ */
+export declare class Wakeshift {
+    /**
+     * An older key's mode (wst_test_…, wst_live_…); null for a current key.
+     * @deprecated Modes mean nothing now, and current keys have none.
+     */
+    readonly mode: "test" | "live" | null;
+    readonly core: string;
+    private readonly key;
+    private knownAppId;
+    private appInfo?;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    private readonly warnFn;
+    private readonly warned;
+    constructor(opts: WakeshiftOptions);
+    /**
+     * The app's ID. An older key (wst_test_…, wst_live_…) names it; for a
+     * current key, which doesn't, this throws until `await wake.app()` has
+     * asked Wakeshift.
+     */
+    get appId(): string;
+    /**
+     * Which app the key is, as Wakeshift says: its ID and name. Asks once
+     * (GET /api/apps/v1/app) and remembers the answer; afterwards
+     * `wake.appId` works for any key.
+     */
+    app(): Promise<AppInfo>;
+    private assertion;
+    /** Reports a warning, once per kind. */
+    private warnOnce;
+    /**
+     * The arguments the agent passes Wakeshift's part of the call in, as a
+     * zod shape for your subscribe tool's input (and any other tool whose
+     * results you annotate): `inputSchema: { repo: z.string(), ...wake.args }`.
+     * session_key (the key a result gives the conversation), harness (the
+     * program the agent runs in) and conversation_id (its own ID for the
+     * conversation, where its program gives one). Wakeshift adds nothing to
+     * tools you don't spread it into.
+     */
+    get args(): typeof argsShape;
+    /**
+     * Packs the tool call from an MCP tool callback's `extra`: its _meta and
+     * User-Agent, the client's name (from `server`, or pass `client`), the
+     * user, and session_key, harness and conversation_id from `args`.
+     */
+    call(extra: ToolExtra | undefined, opts?: CallOptions): Call;
+    /** Packs a tool call without an MCP framework. */
+    callOf(c: {
+        meta?: Record<string, unknown>;
+        clientName: string;
+        user?: string;
+        session?: string;
+        userAgent?: string;
+        harness?: string;
+        conversation?: string;
+    }): Call;
+    private recognised;
+    /**
+     * Subscribes the calling conversation to topic (again: refreshes it).
+     * Check the caller may see the topic first: Wakeshift only refuses another
+     * user's u/<user>/… topics.
+     */
+    subscribe(call: Call, topic: string, opts?: SubscribeOptions): Promise<Subscription>;
+    /** Ends the conversation's subscription to topic, or to all the app's topics. Returns how many ended. */
+    unsubscribe(call: Call, topic?: string): Promise<number>;
+    /** Wakes every conversation subscribed to one of topics whose filter the event passes (each once). */
+    publish(topics: string | string[], event: TopicEvent): Promise<Published>;
+    /** Wakes exactly one subscription's conversation, whatever its filter. */
+    send(subscriptionId: string, event: TopicEvent): Promise<SendStatus>;
+    /**
+     * How many conversations are subscribed to topic, and how many are
+     * connected now, and how. Only reads: nothing is delivered, minted or ended.
+     */
+    topicStatus(topic: string): Promise<TopicStatus>;
+    /** Whether a subscription is active and its conversation connected now, and how. Only reads. */
+    subscriptionStatus(subscriptionId: string): Promise<SubscriptionStatus>;
+    /** A capability URL that publishes to topic: a POST's body becomes an event. */
+    publishUrl(topic: string): Promise<PublishUrl>;
+    /** Stops a publish URL working, a topic's or an event's (410 from then on). */
+    revokePublishUrl(id: string): Promise<void>;
+    /** What Wakeshift would add to any other tool result for this conversation (creates nothing). */
+    addition(call: Call): Promise<Addition>;
+    /**
+     * Adds what Wakeshift has for the calling conversation to a tool result
+     * of yours (a copy): what's waiting for a harness that can't be woken, a
+     * fresh connector beacon while a Codex thread's connector isn't running.
+     * Only results you pass here (and a subscription's result()) change.
+     */
+    annotate(call: Call, result: CallToolResult): Promise<CallToolResult>;
+    /** Ends every subscription to topic; each conversation is told. Returns how many ended. */
+    closeTopic(topic: string): Promise<number>;
+    /**
+     * Ends one subscription by its id, telling its conversation that the app
+     * ended it. Returns false if it had already ended (or there's no such
+     * subscription of the app's).
+     */
+    endSubscription(subscriptionId: string): Promise<boolean>;
+    /**
+     * Ends the subscriptions of every conversation of one of the app's users
+     * to topic, or to all of the app's topics (they lost access to something),
+     * telling each conversation. Returns how many ended.
+     */
+    unsubscribeUser(user: string, topic?: string): Promise<number>;
+    /**
+     * Deletes everything Wakeshift keeps for one of the app's users: their
+     * conversations, subscriptions, events and deliveries, recent publishes to
+     * their u/<user>/… topics and publish URLs for them, and their ID. Open
+     * streams close. Returns false if there was nothing to forget.
+     */
+    forgetUser(user: string): Promise<boolean>;
+    /**
+     * Tells Wakeshift what the app may do, replacing what it said before.
+     * The events you defined (defineEvent) are added unless m has events of
+     * its own. Returns the manifest as Wakeshift keeps it.
+     */
+    publishManifest(m: Manifest): Promise<Manifest>;
+    private readonly events;
+    private manifestBase;
+    private published;
+    /**
+     * Defines one of the app's event types: what a subscriber picks (args),
+     * what each occurrence carries (payload), and the line an agent reads
+     * first (text). Returns the event, whose emit sends occurrences. Define
+     * every event before attach.
+     *
+     *   const message = wake.defineEvent("chat.message", {
+     *     description: "A new message in a channel",
+     *     args: z.object({ channel: z.string() }),
+     *     payload: z.object({ from: z.string(), text: z.string() }),
+     *     text: (m) => `${m.from}: ${m.text}`,
+     *   })
+     *   await message.emit({ channel: "eng" }, { from: "ada", text: "shipped" })
+     */
+    defineEvent<A extends AnySchema, P extends AnySchema>(name: string, opts: EventOptions<A, P>): WakeEvent<A, P>;
+    /**
+     * Attaches Wakeshift to your MCP server, before you connect it: the one
+     * call that connects the two. Today it serves the defined events: MCP
+     * Events (events/list, events/subscribe, events/unsubscribe) for clients
+     * that speak it, such as ChatGPT, and the subscribe_events tool for
+     * everyone else, whom Wakeshift wakes its own ways; plus
+     * unsubscribe_events and list_subscriptions for every client, so a person
+     * can always see and stop what they're subscribed to.
+     *
+     *   wake.attach(server, { identify: (extra) => ({ user: guestOf(extra)?.user }) })
+     */
+    attach(server: McpServer, opts?: AttachOptions): void;
+    /**
+     * The workspace Wakeshift keeps for one of the app's users (user: the
+     * app's own ID for them, as in wake.call's user), creating it on first use.
+     * Topics keep that user's conversations there too. GuestAuth calls this;
+     * most apps never need to.
+     */
+    workspace(user: string, name: string): Promise<string>;
+    /** Creates an agent in one of the app's workspaces (if new), and its grant for the app's manifest scope. Returns the grant's ID. */
+    addAgent(workspace: string, agent: string, displayName: string): Promise<string>;
+    /**
+     * Checks that one of the app's agents still has a live grant, asking
+     * Wakeshift each time. Throws a WakeshiftError: no_grant once the grant is
+     * revoked, unknown_workspace once the workspace is forgotten.
+     */
+    checkAgent(workspace: string, agent: string): Promise<void>;
+    private request;
+    private unreachable;
+}
+export {};