@wakeshift/openclaw 0.0.0-stage → 1.4.25

package/dist/plugin.js

@@ -0,0 +1,523 @@
+// Wakeshift's plugin for OpenClaw (verified against 2026.10.4).
+//
+// Connecting: an app's tool result for an OpenClaw session carries a
+// beacon (internal/beacon). OpenClaw drops a result's _meta in its own
+// runtime, so there it's a line of the result's text, which the plugin's
+// tool-result middleware takes out before the model sees it; when OpenClaw
+// runs the turn in Codex's app-server, the beacon is in _meta, which the
+// plugin's hooks see and Codex keeps from the model. The plugin trusts a
+// beacon only if the Wakeshift pinned at install signed it
+// (plugins.entries.wakeshift.config.issuer), redeems its one-time ticket
+// for the conversation's own stream link, and keeps the link on disk.
+//
+// One conversation can watch several apps: it keeps a link per app (and
+// issuer), each with its own transport. A beacon replaces only its own
+// app's link and hands back (supersedes) only that one: another app's link
+// is never sent anywhere but its own stream, and a new link never stops
+// another app's stream. A link saved before links named their app (one per
+// conversation) is handed back and replaced by the first beacon after the
+// update, as before.
+//
+// Waking: per connected conversation, a transport per link reads its stream
+// (transport.ts: Server-Sent Events, falling back to long polling) and one
+// Conversation (deliveries.ts) owns every delivery from all of them: a durable
+// record each, framed as outside data (framing.ts), handed to a turn with
+// OpenClaw's /hooks/agent (wake.ts: persistent, in the conversation's own
+// session, which OpenClaw safety-wraps as outside content), and an ack only
+// once that turn has finished. The hooks it needs are set up and scoped by
+// control.ts (hooks.ts says what changes).
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { acceptable, BeaconError, beaconIn, findBeacon, jwkKey, mcpServer, mcpTool, verifyBound } from "./beacon.js";
+import { Conversation, Ledger } from "./deliveries.js";
+import { agentOf } from "./hooks.js";
+import { linkKey, PINS_UNREADABLE } from "./store.js";
+import { Transport } from "./transport.js";
+import { CLIENT_HEADER, clientHeader } from "./version.js";
+/** The connected note's start (harnesses.Connected): agents look for it. */
+export const CONNECTED = "Wakeshift: connected";
+export const NOTE_CONNECTED = CONNECTED + ". New messages for this conversation will reach it as soon as they arrive, even while it's idle, as long as the OpenClaw gateway runs.";
+export const noteFailed = (why) => `Wakeshift: couldn't connect this conversation (${why}), so new messages won't reach it yet. To retry, call the app's tool that started watching again.`;
+/** Connected, but OpenClaw's hooks can't wake it yet (why). */
+export const noteNoWake = (why) => `${CONNECTED}, but new messages can't wake this conversation yet: ${why}. Until then they wait in Wakeshift.`;
+/** A wake that OpenClaw's hooks refused (why), said on the conversation's next tool result. */
+export const noteWakeFailed = (why) => `Wakeshift: couldn't wake this conversation: ${why}. New messages wait in Wakeshift until it can.`;
+/** Wakeshift refused this version (426 update_required): its message asks for the update. */
+export const noteOutdated = (message) => `Wakeshift: couldn't connect this conversation. ${message}`;
+/** Wakeshift no longer serves this version of the plugin (426 update_required). */
+class OutdatedError extends Error {
+}
+/** Wakeshift refused to move the conversation to another workspace's session (409 conversation_taken). */
+class TakenError extends Error {
+}
+/** The note when Wakeshift refused to move a connected conversation (its link stays). */
+export const NOTE_TAKEN = "Wakeshift: this conversation stays connected where it was: a result asked to connect it to a session of another account or workspace, and Wakeshift doesn't move a connected conversation. To connect it there, stop it being woken where it is first (the app's unwatch tool), or start a new conversation.";
+// The text beacon line (beacon.Text), with the newlines before it, also as
+// they appear inside JSON text, escaped once or more (OpenClaw's code mode
+// shows an MCP result as JSON inside its exec result).
+const BEACON_LINE = /(?:\\+n|\n)*\(For Wakeshift's hook on this computer, not for you: wakeshift-beacon: [A-Za-z0-9_.-]+\)/g;
+/** Whether a tool result has a beacon text line anywhere in it. */
+export function hasBeaconLine(v) {
+    let s;
+    try {
+        s = typeof v === "string" ? v : (JSON.stringify(v) ?? "");
+    }
+    catch {
+        return false;
+    }
+    return s.includes("wakeshift-beacon:");
+}
+/** A tool result with the beacon's text line taken out (anywhere in it). */
+export function stripBeacon(v) {
+    if (typeof v === "string")
+        return v.replace(BEACON_LINE, "");
+    if (Array.isArray(v))
+        return v.map(stripBeacon);
+    if (v && typeof v === "object") {
+        const o = {};
+        for (const [k, x] of Object.entries(v))
+            o[k] = stripBeacon(x);
+        return o;
+    }
+    return v;
+}
+/**
+ * Whether a stream link is on the issuer's scheme and host (wss for https,
+ * ws for http), as the plugin trusts only links from the pinned Wakeshift.
+ */
+export function linkOnIssuer(link, issuer) {
+    let l, i;
+    try {
+        l = new URL(link);
+        i = new URL(issuer);
+    }
+    catch {
+        return false;
+    }
+    const scheme = { "wss:": "https:", "https:": "https:", "ws:": "http:", "http:": "http:" };
+    return !!l.host && scheme[l.protocol] !== undefined && scheme[l.protocol] === i.protocol && l.host.toLowerCase() === i.host.toLowerCase();
+}
+/** How often delivery records are pruned while the gateway runs. */
+export const PRUNE_EVERY = 3600 * 1000;
+export const notePinned = (why, file) => why === PINS_UNREADABLE
+    ? `Wakeshift: didn't connect this conversation: ${file} can't be read, so Wakeshift can't check which MCP server carries this app's messages. Fix the file, or remove it to start over, and call the app's tool again.`
+    : `Wakeshift: didn't connect this conversation: ${why}. If that's the server you use for this app (you renamed or re-added it), remove its line from ${file} and call the app's tool again.`;
+export class Wakeshift {
+    o;
+    f;
+    // This install's ID, read (or made) at first use: loading the plugin
+    // writes nothing (OpenClaw's CLI loads it too, `openclaw wakeshift reset`
+    // and `openclaw plugins uninstall` included).
+    installID;
+    get install() {
+        return (this.installID ??= this.o.store.installId());
+    }
+    // Per conversation: its one Conversation, and a transport per link (by
+    // linkKey: its issuer and app), each with its link's stream ID.
+    streams = new Map();
+    // A conversation's last Conversation while it may still be inside a host
+    // call, for the next one to wait on.
+    settling = new Map();
+    ledger;
+    // Each session's last beacon and the note it produced: OpenClaw's own
+    // runtime shows an MCP result twice (the call inside code mode, then the
+    // exec result the model sees), and a ticket works once. One per session,
+    // only while it's in flight or connected: dropped when connecting fails,
+    // when the session's stream ends for good, and when the gateway starts.
+    beacons = new Map();
+    keys;
+    keysFetchedAt = 0;
+    started = false;
+    pruneTimer;
+    // Each session's last channel route (message_received), for the reply.
+    routes = new Map();
+    // A wake problem per session, and whether it was said, so it's said once.
+    problems = new Map();
+    constructor(o) {
+        this.o = o;
+        this.f = o.fetch ?? fetch;
+        this.ledger = new Ledger(join(o.store.dir, "deliveries"));
+    }
+    /** The conversation as Wakeshift knows it: unique to this install. */
+    conversation(sessionKey) {
+        return `openclaw/${this.install}/${sessionKey}`;
+    }
+    /** Starts the streams of conversations connected before (the gateway restarted). */
+    start() {
+        this.started = true;
+        this.beacons.clear();
+        this.prune();
+        clearInterval(this.pruneTimer);
+        this.pruneTimer = setInterval(() => this.prune(), PRUNE_EVERY);
+        this.pruneTimer.unref?.();
+        for (const l of this.o.store.links()) {
+            // Only links from the Wakeshift pinned now: one saved under another
+            // issuer (the pin changed since) or pointing elsewhere isn't used.
+            if (l.issuer !== this.o.issuer || !linkOnIssuer(l.link, this.o.issuer)) {
+                this.o.host.log.warn(`wakeshift (${l.sessionKey}): a saved link isn't from ${this.o.issuer}; not connecting it`);
+                continue;
+            }
+            this.listen(l);
+            // Never left to reject: an unhandled rejection would take the gateway down.
+            void this.o.hooks.allow(l.sessionKey, l.agentId || agentOf(l.sessionKey)).then((why) => this.setProblem(l.sessionKey, why), (e) => this.o.host.log.warn(`wakeshift (${l.sessionKey}): couldn't check OpenClaw's hooks settings: ${e?.message ?? e}`));
+        }
+    }
+    /** The channel a session last spoke on (OpenClaw's message_received), for a woken turn's reply. */
+    onMessage(sessionKey, route) {
+        // A message on OpenClaw's own surface (the TUI, the web chat) means the
+        // reply belongs in the session, not on the channel it spoke on before.
+        if (route)
+            this.routes.set(sessionKey, route);
+        else
+            this.routes.delete(sessionKey);
+    }
+    setProblem(sessionKey, why) {
+        if (!why) {
+            this.problems.delete(sessionKey);
+            return;
+        }
+        if (this.problems.get(sessionKey)?.why === why)
+            return;
+        this.o.host.log.warn(`wakeshift (${sessionKey}): ${why}`);
+        this.problems.set(sessionKey, { why, said: false });
+    }
+    /** A wake problem not yet told to this session's model, once ("" for none). */
+    takeNote(sessionKey) {
+        const p = this.problems.get(sessionKey);
+        if (!p || p.said)
+            return "";
+        p.said = true;
+        return noteWakeFailed(p.why);
+    }
+    prune() {
+        try {
+            this.ledger.prune();
+        }
+        catch (e) {
+            this.o.host.log.warn(`wakeshift: pruning delivery records failed: ${e.message}`);
+        }
+    }
+    stop() {
+        this.started = false;
+        clearInterval(this.pruneTimer);
+        this.pruneTimer = undefined;
+        for (const [conversation, s] of this.streams) {
+            s.c.stop();
+            for (const x of s.ts.values())
+                x.t.stop();
+            this.settling.set(conversation, s.c.settled());
+        }
+        this.streams.clear();
+    }
+    /** Each listening conversation's links, by linkKey. */
+    get listening() {
+        return [...this.streams].flatMap(([c, s]) => [...s.ts.keys()].map((k) => (k ? `${c}\n${k}` : c)));
+    }
+    /**
+     * A tool result in a session: connects the session on a beacon for it.
+     * Resolves to the note for the model ("" for none: no beacon, or one
+     * that isn't trusted, which it says nothing about).
+     */
+    onResult(result, call) {
+        // Only the result's own _meta, or the last line of its text: a beacon
+        // line inside what the app wrote (a chat message a read tool relays)
+        // can be anyone's.
+        const { token, carried } = findBeacon(result);
+        if (!call.sessionKey)
+            return Promise.resolve("");
+        const seen = this.beacons.get(call.sessionKey);
+        // Code mode's exec result shows the MCP call's result again, as JSON
+        // in its text: the note of the beacon that call connected with (and
+        // only that) comes with it. Nothing is connected from it.
+        if (seen && (seen.token === token || (!token && seen.token === beaconIn(result))))
+            return seen.note;
+        if (!token)
+            return Promise.resolve("");
+        // A beacon proves Wakeshift minted it, not that this result is its
+        // app's: OpenClaw tells servers nothing, so it's bound to no
+        // conversation, and one an attacker minted could sit in a page a tool
+        // fetched or in another server's result. It connects only from an MCP
+        // server's own result (code mode's exec result shows the same beacon
+        // again, after its inner call did), from the server pinned to its app.
+        const server = mcpServer(call.toolName);
+        if (!server)
+            return Promise.resolve("");
+        const sessionKey = call.sessionKey;
+        const note = this.connect(token, carried, call, server)
+            .catch((e) => {
+            this.o.host.log.warn(`wakeshift: connecting failed: ${e.message}`);
+            return "";
+        })
+            .then((n) => {
+            // Kept only while it connected: a failure is tried again when the
+            // beacon shows up again.
+            if (!n.startsWith(CONNECTED) && this.beacons.get(sessionKey)?.note === note)
+                this.beacons.delete(sessionKey);
+            return n;
+        });
+        this.beacons.set(sessionKey, { token, note });
+        return note;
+    }
+    async connect(token, carried, call, server) {
+        const sessionKey = call.sessionKey;
+        const conversation = this.conversation(sessionKey);
+        let claims;
+        try {
+            claims = await this.verify(token, conversation);
+        }
+        catch (e) {
+            if (e instanceof BeaconError)
+                return ""; // not for us: say nothing
+            throw e;
+        }
+        // From the tool it names (one minted for another tool's result, relayed
+        // here, isn't), and one naming none only from the result's own _meta.
+        if (!acceptable(claims, carried, mcpTool(call.toolName)))
+            return "";
+        const pinned = this.o.store.pin(server, claims.app);
+        if (pinned)
+            return notePinned(pinned, this.o.store.pinsPath());
+        // The link this conversation had until now for this app, if any: after
+        // a gateway restart OpenClaw may run its turns in a new Codex thread,
+        // whose calls start a new Wakeshift session. Handing the old link back
+        // ends the session it belongs to, so one conversation stays one
+        // subscription per app. Another app's link isn't this app's to hand
+        // back (Wakeshift supersedes only within an app), and stays as it is. A
+        // link saved before links named their app goes too, as it did then.
+        const key = linkKey({ issuer: this.o.issuer, app: claims.app });
+        const prior = this.o.store.loadLink(conversation, key);
+        const legacy = prior ? undefined : this.o.store.loadLink(conversation, "");
+        const held = prior ?? legacy;
+        const supersedes = held && held.issuer === this.o.issuer && linkOnIssuer(held.link, this.o.issuer) ? held.link : "";
+        let link;
+        try {
+            link = await this.redeem(claims, conversation, call.toolCallId ?? "", supersedes);
+        }
+        catch (e) {
+            if (e instanceof OutdatedError)
+                return noteOutdated(e.message);
+            if (e instanceof TakenError)
+                return NOTE_TAKEN; // the link it had stays
+            return noteFailed(e.message);
+        }
+        if (!linkOnIssuer(link, this.o.issuer))
+            return noteFailed("Wakeshift gave a stream link on another host");
+        // A new stream ID: what the link it replaces brought isn't this one's to acknowledge.
+        const saved = { conversation, sessionKey, agentId: call.agentId ?? "", link, issuer: this.o.issuer, app: claims.app, stream: randomBytes(8).toString("hex") };
+        this.o.store.saveLink(saved);
+        if (legacy)
+            this.o.store.forgetLink(conversation, "");
+        this.listen({ ...saved, saved_at: new Date().toISOString() }, legacy ? [""] : []);
+        const why = await this.o.hooks.allow(sessionKey, call.agentId || agentOf(sessionKey));
+        if (why) {
+            // Said now, in the note: not again on the next result.
+            this.problems.set(sessionKey, { why, said: true });
+            return noteNoWake(why);
+        }
+        this.problems.delete(sessionKey);
+        return NOTE_CONNECTED;
+    }
+    async verify(token, conversation) {
+        const issuers = [this.o.issuer];
+        const keyFor = (kid) => this.keys?.byKid.get(kid);
+        await this.loadKeys(false);
+        try {
+            return verifyBound(token, { conversation, unbound: true }, issuers, keyFor);
+        }
+        catch (e) {
+            // A key that changed under a kid we have, or a new one: fetch once (at most once a minute).
+            if (e instanceof BeaconError && (await this.loadKeys(true)))
+                return verifyBound(token, { conversation, unbound: true }, issuers, keyFor);
+            throw e;
+        }
+    }
+    // The pinned issuer's keys, from disk or <issuer>/oauth/jwks; true if fetched now.
+    async loadKeys(refresh) {
+        const parse = (body) => {
+            const byKid = new Map();
+            try {
+                for (const k of (JSON.parse(body).keys ?? []))
+                    if (k.kid)
+                        byKid.set(k.kid, jwkKey(k));
+            }
+            catch {
+                /* none */
+            }
+            return byKid;
+        };
+        if (!refresh && this.keys)
+            return false;
+        if (!refresh) {
+            const disk = this.o.store.loadKeys(this.o.issuer);
+            if (disk) {
+                this.keys = { at: disk.at, byKid: parse(disk.body) };
+                return false;
+            }
+        }
+        if (Date.now() - this.keysFetchedAt < 60000)
+            return false;
+        this.keysFetchedAt = Date.now();
+        try {
+            const r = await this.f(this.o.issuer.replace(/\/$/, "") + "/oauth/jwks", { signal: AbortSignal.timeout(5000), redirect: "error" });
+            if (!r.ok)
+                return false;
+            const body = await r.text();
+            this.o.store.saveKeys(this.o.issuer, body);
+            this.keys = { at: Date.now(), byKid: parse(body) };
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async redeem(c, conversation, call, supersedes) {
+        const body = { ticket: c.ticket, thread: conversation };
+        if (call)
+            body.call = call;
+        if (supersedes)
+            body.supersedes = supersedes;
+        let r;
+        try {
+            r = await this.f(c.redeem, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", [CLIENT_HEADER]: clientHeader() },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(10000),
+                redirect: "error", // the ticket and the old link go only to the issuer
+            });
+        }
+        catch {
+            throw new Error("Wakeshift couldn't be reached");
+        }
+        let out = {};
+        try {
+            out = (await r.json());
+        }
+        catch {
+            /* not JSON */
+        }
+        if (r.ok && typeof out.url === "string" && out.url)
+            return out.url;
+        if (r.status === 426 || out.error?.code === "update_required") {
+            throw new OutdatedError(typeof out.error?.message === "string" && out.error.message
+                ? out.error.message
+                : "Wakeshift's hooks for OpenClaw are out of date. Ask the user whether to update them; only if they agree, run the install command again.");
+        }
+        switch (out.error?.code) {
+            case "unknown_ticket":
+                throw new Error("the ticket expired or was used");
+            case "no_grant":
+                throw new Error("the app isn't allowed for this agent any more");
+            case "wrong_thread":
+                throw new Error("the ticket was for another conversation");
+            case "conversation_taken":
+                throw new TakenError("this conversation is connected to another workspace's session");
+        }
+        throw new Error(`Wakeshift answered ${r.status}`);
+    }
+    // One link of a connected conversation, in place of the transport it had
+    // for the same app (and for the keys in replaces): its transport reads,
+    // the conversation's one Conversation decides (deliveries.ts). What a
+    // replaced transport read and no turn has had is still in the
+    // conversation's records: it runs, but isn't acknowledged on the new
+    // link, which doesn't carry it (a new stream ID).
+    listen(l, replaces = []) {
+        if (!this.started)
+            return;
+        const key = linkKey(l);
+        const stream = l.stream ?? "";
+        const log = (m) => this.o.host.log.info(`wakeshift (${l.sessionKey}): ${m}`);
+        let e = this.streams.get(l.conversation);
+        if (!e) {
+            const ts = new Map();
+            const transport = (via) => [...ts.values()].find((x) => x.stream === via)?.t;
+            const after = this.settling.get(l.conversation);
+            this.settling.delete(l.conversation);
+            const c = new Conversation({
+                ledger: this.ledger,
+                conversation: l.conversation,
+                sessionKey: l.sessionKey,
+                agentId: l.agentId || undefined,
+                host: this.o.host,
+                // Only on the link that brought it: a lost stream's are never sent elsewhere.
+                ack: (ids, via) => transport(via)?.ack(ids) ?? Promise.resolve(401),
+                // Waiting: a saved link start() would listen on (the pinned
+                // issuer's) that isn't listening now; any other is lost.
+                stream: (via) => transport(via)
+                    ? "live"
+                    : this.o.store
+                        .links()
+                        .some((x) => x.conversation === l.conversation && (x.stream ?? "") === via && x.issuer === this.o.issuer && linkOnIssuer(x.link, this.o.issuer))
+                        ? "waiting"
+                        : "lost",
+                redeliver: (vias) => {
+                    for (const via of vias)
+                        transport(via)?.reconnect();
+                },
+                route: () => this.routes.get(l.sessionKey),
+                routeRefused: () => this.routes.delete(l.sessionKey),
+                problem: (why) => this.setProblem(l.sessionKey, why),
+                wakeFor: this.o.wakeFor,
+                wakeRetry: this.o.wakeRetry,
+                ackRetry: this.o.ackRetry,
+                redeliverAfter: this.o.redeliverAfter,
+                // A Conversation it had before may still be inside a host call for
+                // these records: this one starts once it's done, so nothing is
+                // queued twice.
+                after,
+            });
+            e = { c, ts };
+            this.streams.set(l.conversation, e);
+        }
+        const { c, ts } = e;
+        for (const k of new Set([key, ...replaces])) {
+            ts.get(k)?.t.stop();
+            ts.delete(k);
+        }
+        let t;
+        t = new Transport({
+            ...this.o.stream,
+            link: l.link,
+            fetch: this.f,
+            log,
+            receive: (ds) => c.receive(ds, stream),
+            onLink: (link) => {
+                // Saved only while it's still this app's transport: a replaced one
+                // must not overwrite the newer link.
+                if (this.streams.get(l.conversation)?.ts.get(key)?.t === t)
+                    this.o.store.saveLink({ conversation: l.conversation, sessionKey: l.sessionKey, agentId: l.agentId, link, issuer: l.issuer, app: l.app, stream: l.stream });
+            },
+            onStop: (why) => {
+                const cur = this.streams.get(l.conversation);
+                if (cur?.ts.get(key)?.t === t) {
+                    cur.ts.delete(key);
+                    if (cur.ts.size === 0) {
+                        this.streams.delete(l.conversation);
+                        c.stop();
+                        this.settling.set(l.conversation, c.settled());
+                    }
+                }
+                if (why.why === "gone") {
+                    this.beacons.delete(l.sessionKey); // its next beacon connects again
+                    log(`the stream ended (${why.reason}); forgetting its link`);
+                    // Only this app's link: another app's stays, and goes on.
+                    if (this.o.store.loadLink(l.conversation, key)?.link === t.currentLink)
+                        this.o.store.forgetLink(l.conversation, key);
+                    if (!this.streams.has(l.conversation))
+                        this.problems.delete(l.sessionKey);
+                    // Its session and agent are no longer allowed in OpenClaw's hooks
+                    // (unless another connected conversation, or another app's link
+                    // of this one, still needs them).
+                    const rest = this.o.store.links();
+                    void this.o.hooks
+                        .release({ sessionKeys: rest.map((x) => x.sessionKey), agentIds: rest.map((x) => x.agentId || agentOf(x.sessionKey) || "").filter(Boolean) })
+                        .catch((e) => log(`couldn't update OpenClaw's hooks settings: ${e?.message ?? e}`));
+                }
+            },
+        });
+        ts.set(key, { t, stream });
+        // Picks up what an earlier process left, and what's for this stream.
+        c.start();
+        t.start();
+    }
+}

package/dist/reset.js

@@ -0,0 +1,95 @@
+// `openclaw wakeshift reset`: undoes what the plugin turned on, before an
+// uninstall (OpenClaw has no uninstall hook, and `openclaw plugins
+// uninstall` leaves hooks.* alone). Run where the gateway runs:
+//
+//   openclaw wakeshift reset && openclaw plugins uninstall wakeshift --force
+//
+// It puts OpenClaw's hooks settings back from the record the plugin kept
+// (<state dir>/hooks.json, restorePatch in hooks.ts: only what the plugin
+// added goes, and a setting it changed is put back only while it still
+// holds the plugin's value), drops the plugin's own hooks token with them,
+// removes the user's network-hooks consent (allowNetworkHooks: the next
+// install asks again), and deletes the plugin's state directory (its
+// conversations' stream links and that record). The Wakeshift the plugin
+// trusts (issuer) stays: it says where the plugin connects, not something
+// it turned on, and the uninstall removes it with the plugin's settings.
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { restorePatch } from "./hooks.js";
+/** The plugin's record of what it changed in hooks.*, if there is one. */
+export function readChanges(dir) {
+    try {
+        const c = JSON.parse(readFileSync(join(dir, "hooks.json"), "utf8"));
+        return c && c.version === 1 && c.added && c.set ? c : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** hooks.* with restorePatch's patch applied (null deletes a setting); undefined when none is left. */
+export function applyPatch(cur, patch) {
+    const next = { ...(cur ?? {}) };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null || v === undefined)
+            delete next[k];
+        else
+            next[k] = v;
+    }
+    return Object.keys(next).length ? next : undefined;
+}
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : undefined);
+/** The plugin's own settings in a config draft (plugins.entries.wakeshift.config), if any. */
+function pluginConfig(draft, id) {
+    return obj(obj(obj(obj(draft.plugins)?.entries)?.[id])?.config);
+}
+/** Changes the config to undo the plugin's changes; says what it did, one line each. */
+export function undo(draft, changes, id = "wakeshift") {
+    const done = [];
+    if (changes) {
+        const cur = obj(draft.hooks);
+        const patch = restorePatch(cur, changes);
+        if (patch) {
+            const next = applyPatch(cur, patch);
+            if (next === undefined)
+                delete draft.hooks;
+            else
+                draft.hooks = next;
+            done.push(changes.owned
+                ? "OpenClaw's hooks settings are back as they were before Wakeshift turned them on (its token is gone), apart from what you changed since."
+                : "Wakeshift's additions to your OpenClaw hooks settings are removed.");
+        }
+    }
+    const cfg = pluginConfig(draft, id);
+    if (cfg && "allowNetworkHooks" in cfg) {
+        delete cfg.allowNetworkHooks;
+        done.push("The agreement to OpenClaw's hooks endpoint on a gateway that listens beyond this computer (allowNetworkHooks) is removed: installing again asks again.");
+    }
+    return done;
+}
+/**
+ * Undoes what the plugin turned on (see the top of this file), and says
+ * what it did. Config first: if OpenClaw refuses the write, the record of
+ * what to undo stays, for another try.
+ */
+export async function reset(o) {
+    const changes = readChanges(o.dir);
+    // A record that's there but can't be read stays, with the directory:
+    // without it nothing says what to put back.
+    if (!changes && existsSync(join(o.dir, "hooks.json"))) {
+        throw new Error(`${join(o.dir, "hooks.json")}, the record of what the plugin changed in OpenClaw's hooks settings, can't be read; nothing was changed`);
+    }
+    let done = [];
+    const now = o.config.current?.();
+    // No record, and no consent in the config as it is: no write (a write to
+    // the plugin's settings makes the gateway load the plugin again). With a
+    // record it always goes through the config file itself, where undo works
+    // out the patch, before the record is deleted.
+    if (changes || !now || undo(structuredClone(now), undefined, o.id).length > 0) {
+        await o.config.mutate((draft) => {
+            done = undo(draft, changes, o.id);
+        });
+    }
+    rmSync(o.dir, { recursive: true, force: true });
+    done.push(`Wakeshift's state for OpenClaw (${o.dir}) is deleted.`);
+    return done;
+}