@butlerbot/sdk 0.0.21 → 0.0.23

package/dist/link/hook.d.ts

@@ -42,7 +42,7 @@ export type HookEmitter = {
      * 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[]>;
+    reportHookEvent(hookId: string, event: string, payload?: Record<string, unknown>, subscriptionIds?: string[]): Promise<string[]>;
     /** The subscriptions the server has pushed for this hook's source. */
     hookSubscriptions(hookId: string): LinkSubscription[];
 };
@@ -99,4 +99,17 @@ export declare class Hook<S extends ToolSchema | undefined = undefined> {
      * disconnect — nothing is persisted, because the server re-sends it on every connect.
      */
     get subscriptions(): LinkSubscription[];
+    /**
+     * Reports an event to subscriptions you picked yourself.
+     *
+     * The escape hatch from the prefilter, for conditions that are not field equality: "mentions my
+     * user", "within 50 metres", "the third time today". Read `subscriptions`, decide with real code —
+     * `identities` is there for the "is this about my user" half — and pass the ids you chose.
+     *
+     * The prefilter is deliberately not applied to these: you already decided. What is checked is that
+     * each id is one this link currently holds for this hook, so a stale id is dropped rather than sent
+     * and rejected. Unknown ids are dropped quietly, because a subscription disappearing between your
+     * decision and this call is a race, not a mistake.
+     */
+    reportTo(subscriptionIds: string[], event: string, payload?: Record<string, unknown>): Promise<string[]>;
 }

package/dist/link/hook.js

@@ -92,5 +92,29 @@ class Hook {
     get subscriptions() {
         return this.link?.hookSubscriptions(this.id) ?? [];
     }
+    /**
+     * Reports an event to subscriptions you picked yourself.
+     *
+     * The escape hatch from the prefilter, for conditions that are not field equality: "mentions my
+     * user", "within 50 metres", "the third time today". Read `subscriptions`, decide with real code —
+     * `identities` is there for the "is this about my user" half — and pass the ids you chose.
+     *
+     * The prefilter is deliberately not applied to these: you already decided. What is checked is that
+     * each id is one this link currently holds for this hook, so a stale id is dropped rather than sent
+     * and rejected. Unknown ids are dropped quietly, because a subscription disappearing between your
+     * decision and this call is a race, not a mistake.
+     */
+    async reportTo(subscriptionIds, event, payload) {
+        if (!this.link) {
+            throw new Error(`Hook "${this.id}" is not on a link yet — call link.addHook(hook) first.`);
+        }
+        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}.`);
+        }
+        if (subscriptionIds.length === 0)
+            return [];
+        return this.link.reportHookEvent(this.id, event, payload, subscriptionIds);
+    }
 }
 exports.Hook = Hook;

package/dist/link/link.d.ts

@@ -142,7 +142,7 @@ export declare class Link {
      * 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[]>;
+    reportHookEvent(hookId: string, event: string, payload?: Record<string, unknown>, chosenIds?: string[]): Promise<string[]>;
     /** Called by `Hook.subscriptions`. */
     hookSubscriptions(hookId: string): LinkSubscription[];
     /** Everything this link has been asked to watch, across all of its hooks. */

package/dist/link/link.js

@@ -268,10 +268,19 @@ class Link {
      * 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) {
+    async reportHookEvent(hookId, event, payload, chosenIds) {
         await this.ready();
         const sourceId = this.hooks.get(hookId)?.sourceId ?? hookId;
-        const subscriptionIds = this.subscriptionStore.match({ sourceId, event, payload });
+        // Explicit ids are still checked against what this link actually holds. Not out of distrust of
+        // the caller — the server checks again anyway — but because an id it was never given can only
+        // be a bug or a race with a removal, and both are better as a dropped report than as a frame
+        // the server rejects. Dropped rather than thrown: a subscription vanishing mid-event is normal.
+        const subscriptionIds = chosenIds
+            ? chosenIds.filter(id => this.subscriptionStore.get(id)?.sourceId === sourceId)
+            : this.subscriptionStore.match({ sourceId, event, payload });
+        if (chosenIds && subscriptionIds.length !== chosenIds.length) {
+            this.debug(`dropped ${chosenIds.length - subscriptionIds.length} unknown subscription id(s) on ${event}`);
+        }
         if (subscriptionIds.length === 0)
             return [];
         this.send("hook.event", {

package/dist/link/protocol.d.ts

@@ -21,6 +21,7 @@ export type LinkToolDescriptor = {
         longDescription: string;
     };
     defaultEnabled?: boolean;
+    platforms?: string[];
     timeoutMs?: number;
 };
 export type LinkHookEventDeclaration = {
@@ -152,6 +153,7 @@ export type LinkServerPayloads = {
             userId: string;
             chatId?: string;
             runId: string;
+            identities?: Record<string, string>;
         };
         timeoutMs: number;
     };

package/dist/link/tool.d.ts

@@ -24,6 +24,17 @@ export type ToolCallMeta = {
     chatId?: string;
     /** Unique per call, useful for logs. */
     runId: string;
+    /**
+     * The user's linked accounts, in namespaces you understand: `{ discord: "1897..." }`.
+     *
+     * Present only for global-scope links — a platform client acting *as* the user, which is the case
+     * that needs it: to kick somebody as them you need their Discord id, and resolving that from an
+     * Alfred user id is the server's job. A user-scoped link is already the user's own process and is
+     * told nothing extra.
+     *
+     * Absent when the user has linked nothing. Refuse the call rather than guessing.
+     */
+    identities?: Record<string, string>;
 };
 export type ToolRunContext<S extends ToolSchema | undefined> = {
     /** Typed from `schema` when one was given. */
@@ -53,6 +64,19 @@ export type ToolConfig<S extends ToolSchema | undefined> = {
     };
     /** Whether the tool is on before the user has touched it. */
     defaultEnabled?: boolean;
+    /**
+     * Where in Alfred the tool is reachable, as platform ids. Defaults to the user's chat.
+     *
+     * Say this when your client mirrors a whole platform. A Discord bot offering seventy tools does
+     * not want seventy entries in front of somebody having a conversation about their groceries — it
+     * wants them behind Alfred's Discord agent, which is one entry and already knows how to decide
+     * when Discord is relevant.
+     *
+     * Known values are Alfred's platform ids, e.g. `"platform.chat.user"` (the default) and
+     * `"platform.agent.discord"`. An unknown one is rejected at registration rather than ignored,
+     * because a tool reachable from nowhere is indistinguishable from a tool that is broken.
+     */
+    platforms?: string[];
     /** How long the server waits for a result before giving up. */
     timeoutMs?: number;
     /** Runs the tool. Return anything JSON-serialisable, or throw to fail the call. */

package/dist/link/tool.js

@@ -27,6 +27,7 @@ class Tool {
             inputSchema,
             ...(this.config.display ? { display: this.config.display } : {}),
             ...(this.config.defaultEnabled !== undefined ? { defaultEnabled: this.config.defaultEnabled } : {}),
+            ...(this.config.platforms ? { platforms: this.config.platforms } : {}),
             ...(this.config.timeoutMs !== undefined ? { timeoutMs: this.config.timeoutMs } : {}),
         };
     }

package/package.json

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

package/readme.md

@@ -130,10 +130,24 @@ Why this is the better path:
 
 `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
+query language. Ignoring prefilters entirely is still *correct*, just louder — the server evaluates
 them again before spending anything.
 
+For a condition that is not field equality — "mentions my user", "within 50 metres", "the third time
+today" — decide with real code and use `reportTo`:
+
+```ts
+const mine = doorbell.subscriptions.filter(
+  (s) => s.identities?.discord && message.mentions.users.has(s.identities.discord),
+);
+
+await doorbell.reportTo(mine.map((s) => s.subscriptionId), "rang", payload);
+```
+
+`reportTo` does not apply the prefilter — you already decided. It does drop any id this link isn't
+currently holding, so a subscription that disappeared between your decision and the call is a
+dropped report rather than a rejected frame.
+
 `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.
@@ -142,6 +156,27 @@ Subscriptions are never persisted by the SDK. They arrive on connect, follow del
 connected, and are dropped on disconnect — so there is nothing to reconcile, and a restart is
 correct by construction.
 
+### Tools can belong to an agent instead of a chat
+
+By default a tool shows up where a user is talking to Alfred. If your client mirrors a whole
+platform, say so instead:
+
+```ts
+new Tool({
+    id: "discord_member_kick",
+    description: "Kick a member from a server.",
+    platforms: ["platform.agent.discord"],
+    run: async ({ args, meta }) => kick(meta.identities?.discord, args),
+});
+```
+
+Seventy tools in front of somebody asking about their groceries is not a feature. Behind Alfred's
+Discord agent they are one entry that already knows when Discord is relevant — and the agent keeps
+whatever tier and permission gating it carries, which tools bolted onto the chat would quietly skip.
+
+An unknown platform is rejected when you register, not ignored: a tool reachable from nowhere looks
+exactly like a tool that is broken.
+
 ### 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