@butlerbot/sdk 0.0.19 → 0.0.21

package/dist/link/hook.d.ts

@@ -1,4 +1,5 @@
 import { LinkHookDeclaration, LinkHookEventDeclaration } from "./protocol";
+import type { LinkSubscription } from "./subscriptions";
 import { JSONSchema, ToolSchema } from "./schema";
 export type HookConfig<S extends ToolSchema | undefined> = {
     /**
@@ -37,6 +38,13 @@ export type HookEmitter = {
      * which only exists once the hook has been registered.
      */
     emitHook(hookId: string, event: string, payload?: Record<string, unknown>, ownerId?: string): Promise<void>;
+    /**
+     * Reports an event against the subscriptions it matched, sending nothing when it
+     * matched none. Returns the ids that were reported.
+     */
+    reportHookEvent(hookId: string, event: string, payload?: Record<string, unknown>): Promise<string[]>;
+    /** The subscriptions the server has pushed for this hook's source. */
+    hookSubscriptions(hookId: string): LinkSubscription[];
 };
 /**
  * A source of events that can wake the user's background agents.
@@ -67,4 +75,28 @@ export declare class Hook<S extends ToolSchema | undefined = undefined> {
      * user-scoped link is always stamped with its own owner and may not name another.
      */
     emit(event: string, payload?: Record<string, unknown>, ownerId?: string): Promise<void>;
+    /**
+     * Reports that something happened, to whoever asked to be told.
+     *
+     * The difference from `emit` is where the filtering lives. `emit` hands the event to the server
+     * and lets it decide who cares, which means the server needs to understand your platform's
+     * payloads. `report` matches locally against the subscriptions the server pushed down, and sends
+     * only the ids that matched — so "messages in #support from non-bots" stays knowledge that lives
+     * in your code, and an event nobody subscribed to costs nothing at all.
+     *
+     * Returns the subscription ids reported, which is `[]` when nothing matched. `[]` is the common
+     * case in a busy channel and is not an error.
+     *
+     * Match it yourself when the condition is more than field equality — `subscriptions` gives you the
+     * list, including `identities` for "is this about *my* user" questions — and pass the ids to
+     * `reportTo`.
+     */
+    report(event: string, payload?: Record<string, unknown>): Promise<string[]>;
+    /**
+     * What the server has asked this hook to watch.
+     *
+     * Empty until the link is connected and the snapshot has arrived, and empty again after a
+     * disconnect — nothing is persisted, because the server re-sends it on every connect.
+     */
+    get subscriptions(): LinkSubscription[];
 }

package/dist/link/hook.js

@@ -56,5 +56,41 @@ class Hook {
         // registration has assigned one, and the link fills it in once it knows.
         await this.link.emitHook(this.id, event, payload, ownerId);
     }
+    /**
+     * Reports that something happened, to whoever asked to be told.
+     *
+     * The difference from `emit` is where the filtering lives. `emit` hands the event to the server
+     * and lets it decide who cares, which means the server needs to understand your platform's
+     * payloads. `report` matches locally against the subscriptions the server pushed down, and sends
+     * only the ids that matched — so "messages in #support from non-bots" stays knowledge that lives
+     * in your code, and an event nobody subscribed to costs nothing at all.
+     *
+     * Returns the subscription ids reported, which is `[]` when nothing matched. `[]` is the common
+     * case in a busy channel and is not an error.
+     *
+     * Match it yourself when the condition is more than field equality — `subscriptions` gives you the
+     * list, including `identities` for "is this about *my* user" questions — and pass the ids to
+     * `reportTo`.
+     */
+    async report(event, payload) {
+        if (!this.link) {
+            throw new Error(`Hook "${this.id}" is not on a link yet — call link.addHook(hook) first.`);
+        }
+        // Caught here rather than on the wire: a typo should fail where it was made.
+        if (!this.config.events.some(declared => declared.name === event)) {
+            const declared = this.config.events.map(entry => entry.name).join(", ") || "none";
+            throw new Error(`Hook "${this.id}" does not declare an event named "${event}". Declared: ${declared}.`);
+        }
+        return this.link.reportHookEvent(this.id, event, payload);
+    }
+    /**
+     * What the server has asked this hook to watch.
+     *
+     * Empty until the link is connected and the snapshot has arrived, and empty again after a
+     * disconnect — nothing is persisted, because the server re-sends it on every connect.
+     */
+    get subscriptions() {
+        return this.link?.hookSubscriptions(this.id) ?? [];
+    }
 }
 exports.Hook = Hook;

package/dist/link/index.d.ts

@@ -6,6 +6,10 @@ export { Hook } from "./hook";
 export type { AnyHook, HookConfig, HookEmitter } from "./hook";
 export { LINK_PROTOCOL_VERSION, LinkError } from "./protocol";
 export type { LinkClientFrame, LinkClientFrameOf, LinkClientFrameType, LinkServerFrame, LinkServerFrameOf, LinkServerFrameType, LinkScopeKind, LinkToolDescriptor, LinkHookDeclaration, LinkHookEventDeclaration, } from "./protocol";
+export { SubscriptionStore } from "./subscriptions";
+export type { LinkSubscription, SubscriptionSnapshot, SubscriptionDelta } from "./subscriptions";
+export { matchesPrefilter, readPath } from "./prefilter";
+export type { Prefilter, PrefilterCondition, PrefilterScalar } from "./prefilter";
 export type { JSONSchema, StandardSchemaV1, ToolSchema, InferSchemaOutput } from "./schema";
 export { buildHandshake, defaultSocketFactory } from "./socket";
 export type { SocketFactory, SocketConnection, SocketHandlers } from "./socket";

package/dist/link/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultSocketFactory = exports.buildHandshake = exports.LinkError = exports.LINK_PROTOCOL_VERSION = exports.Hook = exports.Tool = exports.Link = void 0;
+exports.defaultSocketFactory = exports.buildHandshake = exports.readPath = exports.matchesPrefilter = exports.SubscriptionStore = exports.LinkError = exports.LINK_PROTOCOL_VERSION = exports.Hook = exports.Tool = exports.Link = void 0;
 var link_1 = require("./link");
 Object.defineProperty(exports, "Link", { enumerable: true, get: function () { return link_1.Link; } });
 var tool_1 = require("./tool");
@@ -10,6 +10,11 @@ Object.defineProperty(exports, "Hook", { enumerable: true, get: function () { re
 var protocol_1 = require("./protocol");
 Object.defineProperty(exports, "LINK_PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_1.LINK_PROTOCOL_VERSION; } });
 Object.defineProperty(exports, "LinkError", { enumerable: true, get: function () { return protocol_1.LinkError; } });
+var subscriptions_1 = require("./subscriptions");
+Object.defineProperty(exports, "SubscriptionStore", { enumerable: true, get: function () { return subscriptions_1.SubscriptionStore; } });
+var prefilter_1 = require("./prefilter");
+Object.defineProperty(exports, "matchesPrefilter", { enumerable: true, get: function () { return prefilter_1.matchesPrefilter; } });
+Object.defineProperty(exports, "readPath", { enumerable: true, get: function () { return prefilter_1.readPath; } });
 var socket_1 = require("./socket");
 Object.defineProperty(exports, "buildHandshake", { enumerable: true, get: function () { return socket_1.buildHandshake; } });
 Object.defineProperty(exports, "defaultSocketFactory", { enumerable: true, get: function () { return socket_1.defaultSocketFactory; } });

package/dist/link/link.d.ts

@@ -2,6 +2,7 @@ import { AnyHook } from "./hook";
 import { LinkClientFrameType, LinkClientPayloads, LinkScopeKind, LinkServerFrame } from "./protocol";
 import { SocketFactory } from "./socket";
 import { AnyTool } from "./tool";
+import { type LinkSubscription } from "./subscriptions";
 export type LinkState = "idle" | "connecting" | "open" | "closed";
 export type LinkEvents = {
     /** The link is connected and everything it holds has been registered. */
@@ -23,6 +24,14 @@ export type LinkEvents = {
         reason: string;
         reconnectAfterMs: number;
     }];
+    /**
+     * The set of things the server wants watched has changed.
+     *
+     * Fires on every snapshot and every delta, including the first one after connecting. Use it to
+     * set up whatever your platform needs in order to watch — a channel listener, a poll — and note
+     * that it can fire with an empty list, which means "nothing is subscribed right now".
+     */
+    subscriptions: [LinkSubscription[]];
 };
 export type LinkOptions = {
     /** A user API key, or the service key for a global link. */
@@ -75,6 +84,7 @@ export declare class Link {
     private readonly emitter;
     private readonly tools;
     private readonly hooks;
+    private readonly subscriptionStore;
     private readonly pending;
     private readonly calls;
     private socket;
@@ -123,6 +133,20 @@ export declare class Link {
     private registerAll;
     private registerTools;
     private registerHook;
+    /**
+     * Called by `Hook.report`.
+     *
+     * Sends nothing when the event matched nothing, which is the entire volume story: a busy channel
+     * produces thousands of events a day that no reflex asked about, and none of them reach the wire.
+     *
+     * The epoch travels with the frame so the server can tell a stale view from a bad one — an id
+     * that was valid a moment ago is a race, not a bug worth complaining about.
+     */
+    reportHookEvent(hookId: string, event: string, payload?: Record<string, unknown>): Promise<string[]>;
+    /** Called by `Hook.subscriptions`. */
+    hookSubscriptions(hookId: string): LinkSubscription[];
+    /** Everything this link has been asked to watch, across all of its hooks. */
+    get subscriptions(): LinkSubscription[];
     /** Called by `Hook.emit`. */
     emitHook(hookId: string, event: string, payload?: Record<string, unknown>, ownerId?: string): Promise<void>;
     /** Sends a frame without waiting for anything. Returns its id. */

package/dist/link/link.js

@@ -5,6 +5,7 @@ const config_1 = require("../config");
 const emitter_1 = require("../util/emitter");
 const protocol_1 = require("./protocol");
 const socket_1 = require("./socket");
+const subscriptions_1 = require("./subscriptions");
 const DEFAULTS = {
     minReconnectDelayMs: 500,
     maxReconnectDelayMs: 30000,
@@ -23,6 +24,7 @@ class Link {
         this.emitter = new emitter_1.Emitter();
         this.tools = new Map();
         this.hooks = new Map();
+        this.subscriptionStore = new subscriptions_1.SubscriptionStore();
         this.pending = new Map();
         this.calls = new Map();
         this.socket = null;
@@ -40,6 +42,20 @@ class Link {
             socketFactory: socket_1.defaultSocketFactory,
             ...stripUndefined(options),
         };
+        // A gap means a delta was missed, and the answer is always the same: ask for the snapshot
+        // again. Sent best-effort — if the socket has gone, the reconnect will bring a snapshot anyway.
+        this.subscriptionStore.onResyncNeeded = (have) => {
+            this.debug(`subscription epoch gap at ${have}, resyncing`);
+            try {
+                this.send("hook.subscriptions.resync", { have });
+            }
+            catch {
+                // Disconnected mid-gap. The next connect re-declares and is told again.
+            }
+        };
+        this.subscriptionStore.onChange = (subscriptions) => {
+            this.emitter.emit("subscriptions", subscriptions);
+        };
     }
     // =============================================
     // WHAT THE LINK HOLDS
@@ -176,6 +192,9 @@ class Link {
         this.identity = undefined;
         this.connecting = undefined;
         this.currentState = willReconnect ? "connecting" : "closed";
+        // Nothing about subscriptions survives a socket: the server re-sends the set on every
+        // connect, so holding the old one would only risk reporting against ids that are gone.
+        this.subscriptionStore.reset();
         this.stopHeartbeat();
         this.failPending(new protocol_1.LinkError("disconnected", `The link disconnected (${code}${reason ? `: ${reason}` : ""}).`));
         this.emitter.emit("disconnect", { code, reason, willReconnect });
@@ -240,6 +259,39 @@ class Link {
         hook.sourceId = frame.payload.ids?.[0];
         this.debug(`registered hook ${hook.id}`);
     }
+    /**
+     * Called by `Hook.report`.
+     *
+     * Sends nothing when the event matched nothing, which is the entire volume story: a busy channel
+     * produces thousands of events a day that no reflex asked about, and none of them reach the wire.
+     *
+     * The epoch travels with the frame so the server can tell a stale view from a bad one — an id
+     * that was valid a moment ago is a race, not a bug worth complaining about.
+     */
+    async reportHookEvent(hookId, event, payload) {
+        await this.ready();
+        const sourceId = this.hooks.get(hookId)?.sourceId ?? hookId;
+        const subscriptionIds = this.subscriptionStore.match({ sourceId, event, payload });
+        if (subscriptionIds.length === 0)
+            return [];
+        this.send("hook.event", {
+            sourceId,
+            subscriptionIds,
+            event,
+            ...(payload ? { payload } : {}),
+            epoch: this.subscriptionStore.epoch,
+        });
+        return subscriptionIds;
+    }
+    /** Called by `Hook.subscriptions`. */
+    hookSubscriptions(hookId) {
+        const sourceId = this.hooks.get(hookId)?.sourceId;
+        return sourceId ? this.subscriptionStore.forSource(sourceId) : [];
+    }
+    /** Everything this link has been asked to watch, across all of its hooks. */
+    get subscriptions() {
+        return this.subscriptionStore.all();
+    }
     /** Called by `Hook.emit`. */
     async emitHook(hookId, event, payload, ownerId) {
         await this.ready();
@@ -349,6 +401,12 @@ class Link {
                 this.debug(`call ${callId} cancelled: ${reason}`);
                 return;
             }
+            case "hook.subscriptions":
+                this.subscriptionStore.applySnapshot(frame.payload);
+                return;
+            case "hook.subscriptions.delta":
+                this.subscriptionStore.applyDelta(frame.payload);
+                return;
             case "log":
                 this.emitter.emit("log", frame.payload.log);
                 return;
@@ -379,9 +437,20 @@ class Link {
         }
         const controller = new AbortController();
         this.calls.set(callId, controller);
+        // Only a final status is kept in the conversation, so every call has to end on
+        // one. The tool may send its own, with a better label than we could invent; if
+        // it does not, we send one for it below rather than leave the call unfinished.
+        let reported = "running";
+        const report = (label, state) => {
+            if (reported !== "running")
+                return;
+            reported = state;
+            this.send("tool.status", { label, state }, frame.id);
+        };
         const status = {
-            update: (label) => this.send("tool.status", { label, state: "running" }, frame.id),
-            fail: (label) => this.send("tool.status", { label, state: "failed" }, frame.id),
+            update: (label) => report(label, "running"),
+            complete: (label) => report(label, "completed"),
+            fail: (label) => report(label, "failed"),
         };
         void tool.invoke(args, meta, status, controller.signal).then(result => {
             this.calls.delete(callId);
@@ -389,6 +458,15 @@ class Link {
             // given up on the call, so there is nothing to report to.
             if (!this.socket)
                 return;
+            if (!result.ok && reported === "completed") {
+                // The tool said it succeeded and then failed anyway. The outcome is the
+                // part worth keeping, so let the failure replace what it claimed.
+                reported = "running";
+            }
+            if (result.ok)
+                report(`Finished ${tool.id}.`, "completed");
+            else
+                report(result.error, "failed");
             this.send("tool.result", result.ok
                 ? { ok: true, output: result.output }
                 : { ok: false, error: result.error }, frame.id);

package/dist/link/prefilter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The prefilter, client side.
+ *
+ * A deliberate reimplementation rather than a shared package: the server's copy is the reference,
+ * and the point of keeping the language this dumb is that any client in any language can rewrite it
+ * in twenty lines. A shared dependency would make that claim untestable and would couple every
+ * platform's release cycle to the server's.
+ *
+ * It is a volume gate, not an expressiveness mechanism. **Nothing may depend on it.** A client that
+ * ignores prefilters and reports every event is still correct, just louder — the server evaluates
+ * the same condition again before spending anything.
+ *
+ * Every condition is ANDed. No OR, no regex, no arithmetic, no code.
+ */
+export type PrefilterScalar = string | number | boolean | null;
+export type PrefilterCondition = PrefilterScalar | PrefilterScalar[] | {
+    not: PrefilterScalar | PrefilterScalar[];
+} | {
+    exists: boolean;
+};
+/** Dot-path to condition. An empty or absent prefilter matches everything. */
+export type Prefilter = Record<string, PrefilterCondition>;
+export declare function matchesPrefilter(payload: unknown, prefilter?: Prefilter | null): boolean;
+/** Reads `author.bot` out of `{ author: { bot: true } }`. Missing paths read as `undefined`. */
+export declare function readPath(payload: unknown, path: string): unknown;

package/dist/link/prefilter.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * The prefilter, client side.
+ *
+ * A deliberate reimplementation rather than a shared package: the server's copy is the reference,
+ * and the point of keeping the language this dumb is that any client in any language can rewrite it
+ * in twenty lines. A shared dependency would make that claim untestable and would couple every
+ * platform's release cycle to the server's.
+ *
+ * It is a volume gate, not an expressiveness mechanism. **Nothing may depend on it.** A client that
+ * ignores prefilters and reports every event is still correct, just louder — the server evaluates
+ * the same condition again before spending anything.
+ *
+ * Every condition is ANDed. No OR, no regex, no arithmetic, no code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesPrefilter = matchesPrefilter;
+exports.readPath = readPath;
+function matchesPrefilter(payload, prefilter) {
+    if (!prefilter)
+        return true;
+    for (const [path, condition] of Object.entries(prefilter)) {
+        if (!matchesCondition(readPath(payload, path), condition))
+            return false;
+    }
+    return true;
+}
+function matchesCondition(value, condition) {
+    if (Array.isArray(condition))
+        return condition.some(candidate => value === candidate);
+    if (condition && typeof condition === "object") {
+        if ("exists" in condition)
+            return (value !== undefined) === condition.exists;
+        if ("not" in condition)
+            return !matchesCondition(value, condition.not);
+    }
+    return value === condition;
+}
+/** Reads `author.bot` out of `{ author: { bot: true } }`. Missing paths read as `undefined`. */
+function readPath(payload, path) {
+    let current = payload;
+    for (const segment of path.split(".")) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof current !== "object")
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}

package/dist/link/protocol.d.ts

@@ -36,6 +36,8 @@ export type LinkHookDeclaration = {
     argsSchema: Record<string, unknown>;
     events: LinkHookEventDeclaration[];
 };
+export type { LinkSubscription } from "./subscriptions";
+import type { LinkSubscription } from "./subscriptions";
 export type LinkClientPayloads = {
     "hello": {
         linkId: string;
@@ -67,6 +69,24 @@ export type LinkClientPayloads = {
         payload?: Record<string, unknown>;
         ownerId?: string;
     };
+    /**
+     * An event reported against the subscriptions it matched.
+     *
+     * The inverted path, and the one to prefer: the server pushed a list of things to watch, this
+     * client matched, and the ids say which subscriptions matched. Several ids in one frame is
+     * fan-out — five reflexes watching one channel is one frame. No user is ever named.
+     */
+    "hook.event": {
+        sourceId: string;
+        subscriptionIds: string[];
+        event: string;
+        payload?: Record<string, unknown>;
+        epoch?: number;
+    };
+    /** Asks for a fresh snapshot after noticing an epoch gap. */
+    "hook.subscriptions.resync": {
+        have?: number;
+    };
     "conversation.start": {
         chatId?: string;
         model?: string;
@@ -162,6 +182,25 @@ export type LinkServerPayloads = {
         reason: string;
         reconnectAfterMs: number;
     };
+    /**
+     * The full set this connection should watch, for the sources it has registered.
+     *
+     * `chunk` / `of` are 1-based and present only when the set was split; every chunk of one snapshot
+     * carries the same `epoch`.
+     */
+    "hook.subscriptions": {
+        epoch: number;
+        chunk?: number;
+        of?: number;
+        subscriptions: LinkSubscription[];
+    };
+    /** An incremental change. An epoch more than one ahead means a delta was missed. */
+    "hook.subscriptions.delta": {
+        epoch: number;
+        added?: LinkSubscription[];
+        removed?: string[];
+        updated?: LinkSubscription[];
+    };
 };
 export type LinkServerFrameType = keyof LinkServerPayloads;
 /** A union of one member per frame type, so `frame.type` narrows `frame.payload`. */

package/dist/link/subscriptions.d.ts

@@ -0,0 +1,95 @@
+import { type Prefilter } from "./prefilter";
+/**
+ * One thing the server wants watched.
+ *
+ * `subscriptionId` is a handle the server issued, not a name you can invent: it is how an event is
+ * attributed to a reflex and therefore to a user, which is why reporting an event never involves
+ * naming a user at all.
+ */
+export type LinkSubscription = {
+    subscriptionId: string;
+    sourceId: string;
+    /** Absent means every event from the source. */
+    event?: string;
+    /** A cheap condition to apply before reporting. Advisory — see `prefilter.ts`. */
+    prefilter?: Prefilter;
+    /**
+     * The owner's accounts on platforms they have linked, keyed by a namespace this client
+     * understands: `{ discord: "1897..." }`. Absent when the owner has linked nothing, in which case
+     * a subscription that needs an identity to make sense should be treated as un-matchable rather
+     * than matched against a guess.
+     */
+    identities?: Record<string, string>;
+    /** For logging and for telling a user what is being watched. */
+    name?: string;
+};
+export type SubscriptionSnapshot = {
+    epoch: number;
+    chunk?: number;
+    of?: number;
+    subscriptions: LinkSubscription[];
+};
+export type SubscriptionDelta = {
+    epoch: number;
+    added?: LinkSubscription[];
+    removed?: string[];
+    updated?: LinkSubscription[];
+};
+/**
+ * WHAT THIS LINK HAS BEEN TOLD TO WATCH
+ * =====================================
+ *
+ * Holds the subscription set, keeps it consistent, and answers "which subscriptions does this event
+ * match".
+ *
+ * Nothing here is persisted, on purpose. A client that restarts reconnects, re-declares its sources
+ * and is sent a fresh snapshot, so there is no durable state that can drift out of agreement with
+ * the server and therefore no reconciliation to implement. Deltas and epochs are only an
+ * optimisation on top of that: the epoch lets a client notice it missed a delta, and the answer to
+ * missing one is always the same — ask for the snapshot again.
+ *
+ * Chunked snapshots are buffered until every chunk has arrived, so a half-applied set never briefly
+ * looks like a complete one. That matters: applying half a snapshot would silently stop reporting
+ * events for real subscriptions.
+ */
+export declare class SubscriptionStore {
+    private subscriptions;
+    private currentEpoch;
+    private pending?;
+    /** Called when the store notices a gap and needs a fresh snapshot. */
+    onResyncNeeded?: (have: number) => void;
+    /** Called after the set changes, with the new set. */
+    onChange?: (subscriptions: LinkSubscription[]) => void;
+    get epoch(): number;
+    all(): LinkSubscription[];
+    get(subscriptionId: string): LinkSubscription | undefined;
+    /** Subscriptions for one source, for a caller that wants to report matches itself. */
+    forSource(sourceId: string): LinkSubscription[];
+    /** Everything is forgotten on disconnect: the next connection is told again. */
+    reset(): void;
+    applySnapshot(payload: SubscriptionSnapshot): void;
+    /**
+     * Applies a delta, or asks for a snapshot if one was missed.
+     *
+     * The gap check is the entire consistency mechanism, and the two failure directions are not the
+     * same. An epoch *ahead* of the next one means a delta went missing, and applying this one anyway
+     * would leave a set that is wrong in a way nothing later can detect — so ask for the truth. An
+     * epoch at or *behind* the current one is a replay, which is already applied; asking for a
+     * snapshot would turn a harmless duplicate into a round trip, and a re-sending server into a
+     * loop.
+     */
+    applyDelta(payload: SubscriptionDelta): void;
+    /**
+     * The subscriptions an event should be reported against.
+     *
+     * Order is the pushed order, so a platform that logs the ids gets a stable list. An empty result
+     * means the event is nobody's business and should not be sent at all — which is the point: the
+     * server never sees the 10,000 messages a day that match nothing.
+     */
+    match(input: {
+        sourceId: string;
+        event: string;
+        payload?: Record<string, unknown>;
+    }): string[];
+    private replace;
+}

package/dist/link/subscriptions.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionStore = void 0;
+const prefilter_1 = require("./prefilter");
+/**
+ * WHAT THIS LINK HAS BEEN TOLD TO WATCH
+ * =====================================
+ *
+ * Holds the subscription set, keeps it consistent, and answers "which subscriptions does this event
+ * match".
+ *
+ * Nothing here is persisted, on purpose. A client that restarts reconnects, re-declares its sources
+ * and is sent a fresh snapshot, so there is no durable state that can drift out of agreement with
+ * the server and therefore no reconciliation to implement. Deltas and epochs are only an
+ * optimisation on top of that: the epoch lets a client notice it missed a delta, and the answer to
+ * missing one is always the same — ask for the snapshot again.
+ *
+ * Chunked snapshots are buffered until every chunk has arrived, so a half-applied set never briefly
+ * looks like a complete one. That matters: applying half a snapshot would silently stop reporting
+ * events for real subscriptions.
+ */
+class SubscriptionStore {
+    constructor() {
+        this.subscriptions = new Map();
+        this.currentEpoch = 0;
+    }
+    get epoch() {
+        return this.currentEpoch;
+    }
+    all() {
+        return [...this.subscriptions.values()];
+    }
+    get(subscriptionId) {
+        return this.subscriptions.get(subscriptionId);
+    }
+    /** Subscriptions for one source, for a caller that wants to report matches itself. */
+    forSource(sourceId) {
+        return this.all().filter(subscription => subscription.sourceId === sourceId);
+    }
+    /** Everything is forgotten on disconnect: the next connection is told again. */
+    reset() {
+        this.subscriptions.clear();
+        this.currentEpoch = 0;
+        this.pending = undefined;
+    }
+    applySnapshot(payload) {
+        const total = payload.of ?? 1;
+        if (total === 1) {
+            this.replace(payload.epoch, payload.subscriptions);
+            return;
+        }
+        // A snapshot at a new epoch supersedes one still being assembled, rather than merging with
+        // it: the older chunks describe a set that no longer exists.
+        if (!this.pending || this.pending.epoch !== payload.epoch) {
+            this.pending = { epoch: payload.epoch, chunks: new Map(), of: total };
+        }
+        this.pending.chunks.set(payload.chunk ?? 1, payload.subscriptions);
+        if (this.pending.chunks.size < this.pending.of)
+            return;
+        const assembled = [...this.pending.chunks.entries()]
+            .sort(([a], [b]) => a - b)
+            .flatMap(([, chunk]) => chunk);
+        this.pending = undefined;
+        this.replace(payload.epoch, assembled);
+    }
+    /**
+     * Applies a delta, or asks for a snapshot if one was missed.
+     *
+     * The gap check is the entire consistency mechanism, and the two failure directions are not the
+     * same. An epoch *ahead* of the next one means a delta went missing, and applying this one anyway
+     * would leave a set that is wrong in a way nothing later can detect — so ask for the truth. An
+     * epoch at or *behind* the current one is a replay, which is already applied; asking for a
+     * snapshot would turn a harmless duplicate into a round trip, and a re-sending server into a
+     * loop.
+     */
+    applyDelta(payload) {
+        if (payload.epoch <= this.currentEpoch)
+            return;
+        if (payload.epoch > this.currentEpoch + 1) {
+            this.onResyncNeeded?.(this.currentEpoch);
+            return;
+        }
+        for (const subscriptionId of payload.removed ?? [])
+            this.subscriptions.delete(subscriptionId);
+        for (const subscription of [...(payload.added ?? []), ...(payload.updated ?? [])]) {
+            this.subscriptions.set(subscription.subscriptionId, subscription);
+        }
+        this.currentEpoch = payload.epoch;
+        this.onChange?.(this.all());
+    }
+    /**
+     * The subscriptions an event should be reported against.
+     *
+     * Order is the pushed order, so a platform that logs the ids gets a stable list. An empty result
+     * means the event is nobody's business and should not be sent at all — which is the point: the
+     * server never sees the 10,000 messages a day that match nothing.
+     */
+    match(input) {
+        const candidate = { ...(input.payload ?? {}), type: input.event };
+        return this.all()
+            .filter(subscription => subscription.sourceId === input.sourceId)
+            .filter(subscription => !subscription.event || subscription.event === input.event)
+            .filter(subscription => (0, prefilter_1.matchesPrefilter)(candidate, subscription.prefilter))
+            .map(subscription => subscription.subscriptionId);
+    }
+    replace(epoch, subscriptions) {
+        this.subscriptions = new Map(subscriptions.map(subscription => [subscription.subscriptionId, subscription]));
+        this.currentEpoch = epoch;
+        this.onChange?.(this.all());
+    }
+}
+exports.SubscriptionStore = SubscriptionStore;

package/dist/link/tool.d.ts

@@ -1,9 +1,19 @@
 import { LinkToolDescriptor } from "./protocol";
 import { InferSchemaOutput, JSONSchema, ToolSchema } from "./schema";
-/** Reports progress while a tool runs. Shown live in Alfred's tool status feed. */
+/**
+ * Reports progress while a tool runs. Shown live in Alfred's tool status feed.
+ *
+ * `update` is progress; `complete` and `fail` are final. Only a final status is kept
+ * in the conversation once the turn ends — a status left at `update` is shown live
+ * and then forgotten — so a tool that wants to leave a trace should finish with
+ * `complete`. If it does not, the link sends a final status for it when `run`
+ * returns, so the call is recorded either way.
+ */
 export type ToolStatusReporter = {
-    /** Replaces the current status label. */
+    /** Replaces the current status label. The call is still running. */
     update(label: string): void;
+    /** Marks the tool as finished, with the label the conversation keeps. */
+    complete(label: string): void;
     /** Marks the tool as failed in the UI. The thrown error still decides the result. */
     fail(label: string): void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.19",
+	"version": "0.0.21",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/readme.md

@@ -61,8 +61,9 @@ link.addTool(new Tool({
   description: "Brew a coffee for the user",
   schema: z.object({ cups: z.number().int().min(1).max(4) }),
   run: async ({ args, status }) => {
-    status.update("Grinding beans");
-    return `Brewed ${args.cups} cup(s).`;   // args is typed from the schema
+    status.update("Grinding beans");           // progress, shown while it runs
+    status.complete("Brewed the coffee");      // the label the conversation keeps
+    return `Brewed ${args.cups} cup(s).`;      // args is typed from the schema
   },
 }));
 
@@ -97,6 +98,50 @@ over and the older one's registrations are released. That is deliberate, so a ha
 socket cannot lock out a fresh one during a deploy, but it does mean two genuinely
 different clients must not share an id.
 
+### Hooks: emit, or report what matched
+
+`emit` hands an event to the server and lets it work out who cares. That is fine for a source
+that fires rarely — a water tank, a build finishing — and it is what already-deployed clients do.
+
+For a busy source, prefer `report`. The server pushes down the list of things it wants watched,
+your client matches locally, and only the subscriptions that matched are sent:
+
+```ts
+link.on("subscriptions", (subscriptions) => {
+  // Called on connect and whenever the set changes. Set up whatever you need to watch.
+  for (const subscription of subscriptions) {
+    console.log(subscription.name, subscription.prefilter, subscription.identities);
+  }
+});
+
+// Report an event. Sends nothing at all if no subscription matched.
+const matched = await doorbell.report("rang", { camera: "front" });
+```
+
+Why this is the better path:
+
+- **Nothing irrelevant is sent.** A channel with 10,000 messages a day that nobody subscribed to
+  costs one local comparison per message and zero frames.
+- **Your platform's semantics stay in your code.** "Messages in #support from non-bots" is
+  knowledge Alfred's server never has to learn.
+- **Fan-out is one frame.** Five people watching one channel is one `hook.event` with five ids.
+- **You never name a user.** A subscription id is a handle the server issued and already bound to
+  an owner, so ownership is not something your client can get wrong or forge.
+
+`subscription.prefilter` is applied for you by `report` — a dot-path map of conditions, all ANDed,
+scalars or arrays (`{ "author.bot": false, "channel.id": ["1", "2"] }`). It is a volume gate, not a
+query language: anything it cannot express, match yourself with `hook.subscriptions` and pass the
+ids you chose. Ignoring prefilters entirely is still *correct*, just louder — the server evaluates
+them again before spending anything.
+
+`subscription.identities` is how you answer "is this event about *my* user": a plain string map in
+namespaces you understand, e.g. `{ discord: "1897..." }`, present only for owners who have linked
+that account. Nothing else about the user is exposed.
+
+Subscriptions are never persisted by the SDK. They arrive on connect, follow deltas while
+connected, and are dropped on disconnect — so there is nothing to reconcile, and a restart is
+correct by construction.
+
 ### Tools belong to the user, not to a conversation
 
 Once a tool is registered, Alfred can call it anywhere that user talks to it — the web