@wakeshift/sdk 0.3.0 → 0.5.0

package/dist/wakeshift.js

@@ -1,7 +1,6 @@
-import { z } from "zod";
 import { WakeshiftError } from "./errors.js";
 import { WakeEvent, attachEvents } from "./events.js";
-import { parseKey, signAssertion } from "./key.js";
+import { parseKey, signAssertion, isTestKey } from "./key.js";
 import { retryRefused } from "./retry.js";
 /** Wakeshift's production core, the default for every key but an older wst_test_ one. Override with `core` or WAKESHIFT_CORE. */
 export const DEFAULT_CORE = "https://app.wakeshift.ai";
@@ -14,19 +13,25 @@ export const HARNESS_ARG = "harness";
  * when its program gives it one (Cursor and Grok Bot: CURSOR_CONVERSATION_ID).
  */
 export const CONVERSATION_ARG = "conversation_id";
-// What the agent is told each argument is (the core's own words:
-// internal/harnesses, whose tests check these match).
-const SESSION_DESCRIPTION = "The session key an earlier result gave you, if it did. It's a secret: keep it to this conversation; don't share or log it";
-const HARNESS_DESCRIPTION = "The program you're running in: codex, claude-code, cursor (local CLI or IDE), cursor-cloud (Cursor cloud agent), grok-bot, copilot-cli, opencode, antigravity, openclaw (even when it runs your turns in Codex), hermes, chatgpt, or your program's name if it isn't listed";
-const CONVERSATION_DESCRIPTION = "Your own ID for this conversation, if your program gives you one. Cursor and Grok Bot: the output of `printenv CURSOR_CONVERSATION_ID`. Codex and Antigravity send it automatically; others leave it empty";
-/** What the SDK says, once, when Wakeshift recognised no harness in a tool call. */
-export const UNKNOWN_CLIENT_WARNING = "wakeshift: Wakeshift couldn't tell which agent made a tool call (no MCP client name, nothing it knows in the " +
-    "call's _meta or User-Agent, and no harness argument), so it treats the agent as one it can't wake (its messages are held " +
-    "for its next call to the tool). The name comes from the client's initialize request, which a server created per request " +
-    "(stateless Streamable HTTP) never sees; Claude Code, Codex, Antigravity, Copilot CLI, opencode and Cursor are recognised " +
-    "without it. Spread ...wake.args into the tool's input and pass args to wake.call, so the agent can say (harness); for " +
-    "other clients, keep one McpServer per MCP session (a stateful transport), or pass the name yourself: " +
-    "wake.call(extra, { client }) or wake.callOf({ clientName }).";
+// recipientsOf reads an emit's unmatched or ended list: "user",
+// { native: user } or { user, subscription }.
+function recipientsOf(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const r of raw) {
+        if (typeof r === "string")
+            out.push(r);
+        else if (r && typeof r === "object") {
+            const m = r;
+            if (typeof m.native === "string" && m.native)
+                out.push({ native: m.native });
+            else if (typeof m.user === "string")
+                out.push({ user: m.user, subscription: typeof m.subscription === "string" ? m.subscription : "" });
+        }
+    }
+    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) {
@@ -36,45 +41,51 @@ function userAgentOf(extra) {
     const v = headers["user-agent"] ?? headers["User-Agent"];
     return (Array.isArray(v) ? v[0] : v) ?? "";
 }
-export function clientNameOf(s) {
-    const info = "getClientVersion" in s ? s.getClientVersion() : s.server.getClientVersion();
-    return info?.name ?? "";
-}
-/** Adds Wakeshift's text and _meta to a tool result (a copy). */
-export function applyAddition(a, base) {
-    let out;
-    if (typeof base === "string") {
-        const text = (base.trim() + "\n\n" + (a.text ?? "")).trim();
-        out = { content: text ? [{ type: "text", text }] : [] };
-    }
-    else {
-        out = { ...base, content: [...(base.content ?? [])] };
-        if (a.text)
-            out.content.push({ type: "text", text: a.text });
-    }
-    if (a.meta && Object.keys(a.meta).length > 0)
-        out._meta = { ...(out._meta ?? {}), ...a.meta };
+/** @internal Packs a tool call as Wakeshift takes it: empty fields left out, the agent's claims trimmed. */
+export function packCall(c) {
+    const out = { client: c.clientName ?? "" };
+    if (c.user)
+        out.user = c.user;
+    if (c.meta && Object.keys(c.meta).length > 0)
+        out.meta = c.meta;
+    if (c.session)
+        out.session = c.session;
+    if (c.userAgent)
+        out.user_agent = c.userAgent;
+    if (c.harness?.trim())
+        out.harness = c.harness.trim();
+    if (c.conversation?.trim())
+        out.conversation = c.conversation.trim();
+    if (c.tool?.trim())
+        out.tool = c.tool.trim();
     return out;
 }
-const argsShape = {
-    [SESSION_ARG]: z.string().optional().describe(SESSION_DESCRIPTION),
-    [HARNESS_ARG]: z.string().optional().describe(HARNESS_DESCRIPTION),
-    [CONVERSATION_ARG]: z.string().optional().describe(CONVERSATION_DESCRIPTION),
-};
+/**
+ * @internal The call to one of attach's own tools (subscribe_events and the
+ * others): its _meta and User-Agent, the client's name, the user, and
+ * session_key, harness and conversation_id from its arguments.
+ */
+export function toolCallOf(extra, client, user, args, tool) {
+    return packCall({
+        meta: extra?._meta,
+        clientName: client,
+        user,
+        session: str(args, SESSION_ARG),
+        userAgent: userAgentOf(extra),
+        harness: str(args, HARNESS_ARG),
+        conversation: str(args, CONVERSATION_ARG),
+        tool,
+    });
+}
 // str is a tool argument's value if it's a string.
 function str(args, name) {
     return typeof args?.[name] === "string" ? args[name] : undefined;
 }
 /**
- * The Wakeshift client for an app: subscribe the conversations that call
- * your tools to topics, and publish to them.
+ * The Wakeshift client for an app: define the events your app offers,
+ * attach them to your MCP server, and emit them when they happen.
  */
 export 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.
-     */
-    mode;
     core;
     key;
     // The app's ID: from the key, if it names the app, or else from app().
@@ -89,10 +100,9 @@ export class Wakeshift {
             throw new Error("wakeshift: no app key (WAKESHIFT_KEY?)");
         this.key = parseKey(opts.key);
         this.knownAppId = this.key.appId;
-        this.mode = this.key.mode;
         // Test keys come from staging and local consoles, and one sent to
         // production fails in a way that's hard to read: ask for the core.
-        const core = opts.core || process.env.WAKESHIFT_CORE || (this.mode === "test" ? "" : DEFAULT_CORE);
+        const core = opts.core || process.env.WAKESHIFT_CORE || (isTestKey(opts.key) ? "" : DEFAULT_CORE);
         if (!core) {
             throw new Error("wakeshift: no core URL for this test key: set WAKESHIFT_CORE, or pass { core }, to the address of the console the key came from (for example https://app.staging.wakeshift.ai)");
         }
@@ -113,7 +123,8 @@ export class Wakeshift {
         return this.knownAppId;
     }
     /**
-     * Which app the key is, as Wakeshift says: its ID and name. Asks once
+     * Which app the key is, as Wakeshift says: its ID and name, and the
+     * key's. Asks once
      * (GET /api/apps/v1/app) and remembers the answer; afterwards
      * `wake.appId` works for any key.
      */
@@ -125,7 +136,8 @@ export class Wakeshift {
             }
             const id = this.knownAppId ?? r.id;
             this.knownAppId = id;
-            return { id, name: typeof r.name === "string" ? r.name : "" };
+            const str = (v) => (typeof v === "string" ? v : "");
+            return { id, name: str(r.name), key: { id: str(r.key?.key_id), name: str(r.key?.name) } };
         })
             .catch((err) => {
             this.appInfo = undefined; // a later call asks again
@@ -145,205 +157,105 @@ export class Wakeshift {
     warn(message) {
         this.warnFn(message);
     }
-    /** Reports a warning, once per kind. */
+    /** @internal Reports a warning, once per kind. */
     warnOnce(kind, message) {
         if (this.warned.has(kind))
             return;
         this.warned.add(kind);
         this.warnFn(message);
     }
-    /**
-     * 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() {
-        return 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, opts = {}) {
-        let client = opts.client;
-        if (client === undefined) {
-            if (!opts.server)
-                throw new Error("wakeshift: wake.call needs the MCP client's name: pass { server } (your McpServer), or { client }");
-            client = clientNameOf(opts.server);
-        }
-        const args = opts.args;
-        return this.callOf({
-            meta: extra?._meta,
-            clientName: client,
-            user: opts.user,
-            session: opts.session ?? str(args, SESSION_ARG),
-            userAgent: userAgentOf(extra),
-            harness: opts.harness ?? str(args, HARNESS_ARG),
-            conversation: opts.conversation ?? str(args, CONVERSATION_ARG),
-            tool: opts.tool,
-        });
-    }
-    /** Packs a tool call without an MCP framework. */
-    callOf(c) {
-        const out = { client: c.clientName ?? "" };
-        if (c.user)
-            out.user = c.user;
-        if (c.meta && Object.keys(c.meta).length > 0)
-            out.meta = c.meta;
-        if (c.session)
-            out.session = c.session;
-        if (c.userAgent)
-            out.user_agent = c.userAgent;
-        if (c.harness?.trim())
-            out.harness = c.harness.trim();
-        if (c.conversation?.trim())
-            out.conversation = c.conversation.trim();
-        if (c.tool?.trim())
-            out.tool = c.tool.trim();
-        return out;
-    }
-    // recognised reads what the core recognised the caller as, and warns
-    // once if it was nothing and the agent didn't say (an older core that
-    // doesn't say: no warning).
-    recognised(agent) {
-        if (agent && !agent.harness && !agent.claimed)
-            this.warnOnce("unknown_client", UNKNOWN_CLIENT_WARNING);
-        return { harness: agent?.harness ?? null, via: agent?.via ?? null, claimed: agent?.claimed ?? null };
-    }
-    /**
-     * 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.
-     */
-    async subscribe(call, topic, opts = {}) {
-        const body = { call, topic, once: !!opts.once };
-        if (opts.filter && Object.keys(opts.filter).length > 0)
-            body.filter = opts.filter;
-        if (opts.replay !== undefined)
-            body.replay = opts.replay;
-        if (opts.ttl !== undefined)
-            body.ttl = opts.ttl;
-        const out = await this.request("POST", "/topics/subscribe", body);
-        const agent = this.recognised(out.agent);
-        const addition = out.addition ?? {};
-        const s = out.subscription;
-        return {
-            id: s.id,
-            topic: s.topic,
-            filter: s.filter,
-            once: s.once,
-            expiresAt: new Date(s.expires_at),
-            session: out.session,
-            addition,
-            agent,
-            result: (text) => applyAddition(addition, text),
-        };
-    }
-    /** Ends the conversation's subscription to topic, or to all the app's topics. Returns how many ended. */
-    async unsubscribe(call, topic) {
-        const out = await this.request("POST", "/topics/unsubscribe", topic ? { call, topic } : { call });
-        return out.unsubscribed;
-    }
-    /** Wakes every conversation subscribed to one of topics whose filter the event passes (each once). */
-    async publish(topics, event) {
-        const out = await this.request("POST", "/topics/publish", { topics: typeof topics === "string" ? [topics] : topics, event });
-        return { matched: out.matched, duplicate: !!out.duplicate };
-    }
-    /** Wakes exactly one subscription's conversation, whatever its filter. */
-    async send(subscriptionId, event) {
-        const out = await this.request("POST", `/subscriptions/${encodeURIComponent(subscriptionId)}/send`, { event });
-        return out.status;
-    }
-    /**
-     * How many conversations are subscribed to topic, and how many are
-     * connected now, and how. Only reads: nothing is delivered, minted or ended.
-     */
-    async topicStatus(topic) {
-        const out = await this.request("GET", `/topics/status?topic=${encodeURIComponent(topic)}`);
-        return { topic: out.topic, subscriptions: out.subscriptions, connected: out.connected, via: { stream: 0, poll: 0, hooks: 0, webhook: 0, ...out.via } };
-    }
-    /** Whether a subscription is active and its conversation connected now, and how. Only reads. */
-    async subscriptionStatus(subscriptionId) {
-        const out = await this.request("GET", `/subscriptions/${encodeURIComponent(subscriptionId)}`);
-        const s = { id: out.id, topic: out.topic, status: out.status, connected: out.connected };
-        if (out.via)
-            s.via = out.via;
-        if (out.expires_at)
-            s.expiresAt = new Date(out.expires_at);
-        return s;
-    }
-    /** A capability URL that publishes to topic: a POST's body becomes an event. */
-    async publishUrl(topic) {
-        return this.request("POST", "/topics/publish-urls", { topic });
-    }
-    /** Stops a publish URL working, a topic's or an event's (410 from then on). */
+    /** Stops a publish URL working (410 from then on). */
     async revokePublishUrl(id) {
         await this.request("DELETE", `/events/publish-urls/${encodeURIComponent(id)}`);
     }
-    /** What Wakeshift would add to any other tool result for this conversation (creates nothing). */
-    async addition(call) {
-        const out = await this.request("POST", "/topics/annotate", { call });
-        return { ...out, agent: this.recognised(out.agent) };
-    }
-    /**
-     * 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.
-     */
-    async annotate(call, result) {
-        return applyAddition(await this.addition(call), result);
-    }
-    /** Ends every subscription to topic; each conversation is told. Returns how many ended. */
-    async closeTopic(topic) {
-        return (await this.request("POST", "/topics/close", { topic })).closed;
-    }
-    /**
-     * 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).
-     */
-    async endSubscription(subscriptionId) {
-        return (await this.request("POST", `/subscriptions/${encodeURIComponent(subscriptionId)}/end`, {})).ended;
-    }
-    /**
-     * 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.
-     */
-    async unsubscribeUser(user, topic) {
-        return (await this.request("POST", "/topics/unsubscribe", topic ? { user, topic } : { user })).unsubscribed;
-    }
     /**
      * 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.
+     * conversations, subscriptions, events and deliveries, publish URLs for
+     * them, and their ID. Open streams close. Returns false if there was nothing to forget.
      */
     async forgetUser(user) {
         return (await this.request("POST", "/users/forget", { user })).forgotten;
     }
     /**
-     * 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.
+     * Tells Wakeshift what the app may do, replacing what it said before: m,
+     * with the events you defined (defineEvent) after m's own events. An
+     * event both defined and listed in m.events is an error, and nothing is
+     * sent. You needn't call it: a process that serves your tools (attach)
+     * sends the manifest automatically, merged into the one Wakeshift has.
+     * Call it to remove an event or clear a setting. Once called, m's
+     * settings are what every automatic send carries (even if this one
+     * failed), with the events defined by then. Returns the manifest as
+     * Wakeshift keeps it.
      */
     async publishManifest(m) {
-        const body = m.events === undefined && this.events.size > 0 ? { ...m, events: [...this.events.values()].map((e) => e.manifest) } : m;
-        const out = await this.request("PUT", "/manifest", body);
+        const version = this.manifestVersion; // before the body: a later defineEvent is sent again
+        const body = this.manifestBody(m);
         this.manifestBase = m;
-        this.published = Promise.resolve();
-        return out;
+        const run = this.serial(() => this.request("PUT", "/manifest", body));
+        this.track(run, version);
+        return run;
+    }
+    // serial runs a send after every send before it, explicit or automatic,
+    // so the last manifest Wakeshift gets is the newest.
+    sending = Promise.resolve();
+    serial(send) {
+        const run = this.sending.then(send, send);
+        this.sending = run.catch(() => undefined);
+        return run;
+    }
+    // track makes a send the one event calls wait for: once it's done,
+    // Wakeshift has the manifest for the events defined at version, unless it
+    // failed (the next call sends again) or an event was defined since.
+    track(send, version) {
+        const p = send.then(() => {
+            if (this.manifestVersion !== version && this.published === p)
+                this.published = null;
+        });
+        this.published = p;
+        p.catch(() => {
+            if (this.published === p)
+                this.published = null;
+        });
+    }
+    // The manifest as Wakeshift gets it: m's events, then the defined ones,
+    // refusing a name in both.
+    manifestBody(m) {
+        const listed = m.events ?? [];
+        for (const name of this.events.keys()) {
+            if (listed.some((e) => e.name === name)) {
+                throw new Error(`wakeshift: event ${name} is defined with defineEvent and listed in the manifest's events: keep one`);
+            }
+        }
+        const events = [...listed, ...[...this.events.values()].map((e) => e.manifest)];
+        const { events: _listed, ...rest } = m;
+        return events.length > 0 ? { ...rest, events } : rest;
+    }
+    // The automatic send, from a process that serves the app's tools: the
+    // settings the app last published (only those it set), with the defined
+    // events, merged into the manifest Wakeshift has, so it never removes an
+    // event or clears a setting another process sent.
+    async sendManifest() {
+        const body = {};
+        for (const [k, v] of Object.entries(this.manifestBody(this.manifestBase ?? {}))) {
+            if (v === undefined || v === null || v === "" || v === false || (Array.isArray(v) && v.length === 0))
+                continue;
+            body[k] = v;
+        }
+        if (!body.events)
+            return; // nothing to add (attach refuses with no events, but never send an empty list)
+        await this.request("POST", "/manifest/merge", body);
     }
     // ── Events (MCP Events, natively or bridged) ──────────────────────────
     events = new Map();
-    manifestBase = {};
+    // What publishManifest was last given (null: nothing yet); whether this
+    // process serves the app's tools (attach: only then is the manifest sent
+    // automatically); whether Wakeshift has the manifest for the events
+    // defined now (the send; null: not yet, or a defineEvent since); and how
+    // many defineEvents there were.
+    manifestBase = null;
+    serving = false;
     published = null;
+    manifestVersion = 0;
     /**
      * Defines one of the app's event types: what a subscriber picks (args),
      * what each occurrence carries (payload), and the line an agent reads
@@ -363,7 +275,8 @@ export class Wakeshift {
             throw new Error(`wakeshift: event ${name} is defined twice`);
         const ev = new WakeEvent(this, name, opts);
         this.events.set(name, ev);
-        this.published = null; // the manifest changed
+        this.published = null; // the manifest changed: sent again when next needed
+        this.manifestVersion++;
         return ev;
     }
     /**
@@ -375,21 +288,28 @@ export class Wakeshift {
      * 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: myUser(extra) }) })
+     *   const attached = wake.attach(server, { identify: (extra) => ({ user: myUser(extra) }) })
+     *
+     * 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.
      */
     attach(server, opts = {}) {
-        attachEvents(this, server, [...this.events.values()], opts);
+        const attached = attachEvents(this, server, [...this.events.values()], opts);
+        this.serving = true; // the manifest is sent automatically from now on
+        return attached;
     }
-    /** @internal Publishes the manifest with the defined events, once (again after a defineEvent). */
+    /**
+     * @internal Sends the manifest with the defined events, once (again after
+     * a defineEvent), from a process that serves the app's tools (attach). A
+     * process that only emits never sends it: its events may be fewer, or
+     * older, than its server's.
+     */
     ensureEvents() {
-        if (!this.published) {
-            const p = this.publishManifest(this.manifestBase).then(() => undefined);
-            this.published = p;
-            p.catch(() => {
-                if (this.published === p)
-                    this.published = null; // try again next time
-            });
-        }
+        if (!this.serving)
+            return Promise.resolve();
+        if (!this.published)
+            this.track(this.serial(() => this.sendManifest()), this.manifestVersion);
         return this.published;
     }
     /** @internal An event's emit. */
@@ -401,7 +321,7 @@ export class Wakeshift {
         if (e.to)
             body.to = e.to;
         const out = await this.request("POST", "/events/emit", body);
-        return { matched: out.matched, duplicate: !!out.duplicate };
+        return { matched: out.matched, duplicate: !!out.duplicate, unmatched: recipientsOf(out.unmatched), ended: recipientsOf(out.ended) };
     }
     /** @internal A call to the app API (the events machinery's), after the manifest with the defined events is published. */
     async requestApp(method, path, body) {
@@ -411,8 +331,8 @@ export class Wakeshift {
     // ── Users' workspaces ──────────────────────────────────────────────────
     /**
      * 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), created on first use.
-     * Topics keep that user's conversations there.
+     * app's own ID for them, as attach's identify gives it), created on first
+     * use. Wakeshift keeps that user's conversations there.
      */
     async workspace(user, name) {
         return (await this.request("POST", "/workspaces", { external_id: user, name })).workspace;
@@ -455,13 +375,16 @@ export class Wakeshift {
             json = undefined;
         }
         if (!resp.ok) {
-            const e = json?.error ?? {};
-            throw new WakeshiftError(resp.status, e.code ?? "", e.message ?? (text.slice(0, 200) || resp.statusText), {
-                reason: typeof e.reason === "string" ? e.reason : undefined,
+            // Wakeshift's code, message and reason where it sent them as strings, else
+            // the body's start, else the status's text, as every SDK reads it (test/errors.json).
+            const e = json?.error !== null && typeof json?.error === "object" ? json.error : {};
+            const str = (v) => (typeof v === "string" ? v : "");
+            throw new WakeshiftError(resp.status, str(e.code), str(e.message) || text.slice(0, 200) || resp.statusText, {
+                reason: str(e.reason) || undefined,
             });
         }
         // A 2xx that isn't Wakeshift's JSON: a proxy's page, or a wrong core.
-        if (json === null || typeof json !== "object") {
+        if (json === null || typeof json !== "object" || Array.isArray(json)) {
             throw new WakeshiftError(resp.status, "bad_response", `Wakeshift at ${this.core} answered ${resp.status} without a JSON object. Check that WAKESHIFT_CORE, or the core option, is the address of the console your key came from`);
         }
         return json;