@butlerbot/sdk 0.0.31 → 0.0.33

package/dist/link/agent.d.ts

@@ -0,0 +1,103 @@
+import { LinkAgentDescriptor, LinkServerFrame, LinkServerFrameOf } from "./protocol";
+import { AnyTool } from "./tool";
+export type AgentConfig = {
+    /**
+     * This agent's id within the link. The public id becomes `link:<linkId>/<id>`,
+     * which is what the user's saved settings refer to — so treat it as permanent.
+     */
+    id: string;
+    /** The agent's own name. It signs its replies with it. */
+    name: string;
+    /** What Alfred reads when deciding whether to hand something to this agent. */
+    description: string;
+    /**
+     * The agent's system prompt: who it is, what its tools are for, and how they go together.
+     * This is where a thousand tools become one coherent worker.
+     */
+    prompt: string;
+    /**
+     * The model the agent runs on, by its catalogue name. Omit it for the user's default.
+     * A model the user's plan does not include falls back to their default, exactly as a chat would.
+     */
+    model?: string;
+    /**
+     * The tools the agent works with. They belong to the agent: Alfred never sees them
+     * directly, and they need no `addTool` of their own.
+     */
+    tools?: AnyTool[];
+    /** Shown in Alfred's settings UI. Without it the agent is hidden there. */
+    display?: {
+        name: string;
+        shortDescription: string;
+        longDescription: string;
+    };
+    /** Whether the agent is on before the user has touched it. */
+    defaultEnabled?: boolean;
+};
+/** Progress on an exchange, in the words the agent's status feed would show a conversation. */
+export type AgentStatus = {
+    label: string;
+    state: "running" | "completed" | "failed";
+};
+export type AgentChatOptions = {
+    /**
+     * The exchange this message continues. Messages on one thread share memory.
+     *
+     * Defaults to the agent's own thread, which is minted when the `Agent` is created — so one
+     * `Agent` remembers across `chat` calls, and a new process starts afresh. Name one yourself
+     * to pick a conversation up across restarts, or to keep several going at once.
+     */
+    thread?: string;
+    /** Called with each status update while the agent works. */
+    onStatus?: (status: AgentStatus) => void;
+};
+export type AgentReply = {
+    /** What the agent said. */
+    text: string;
+    /** The thread the reply belongs to, which is what continues it. */
+    thread: string;
+};
+/** What an agent needs from its link. Implemented by `Link`. */
+export type AgentRunner = {
+    chatAgent(agentId: string, message: string, options: AgentChatOptions): Promise<AgentReply>;
+};
+/**
+ * An AI worker that lives on the server for as long as the link does, working with tools
+ * that run here.
+ *
+ * To Alfred it is one tool: he hands it a task and gets a reply, and the tools behind it
+ * stay behind it. To your code it is something to talk to directly — `chat` runs it on the
+ * server and hands the answer back here, so a hook callback can ask it to decide something
+ * and act on what it says.
+ */
+export declare class Agent {
+    private readonly config;
+    readonly id: string;
+    readonly tools: AnyTool[];
+    /** The public id (`link:<linkId>/<id>`), known once the link has registered it. */
+    linkedId?: string;
+    /** The thread `chat` uses when not told otherwise. One per `Agent`, so it remembers. */
+    thread: string;
+    private link?;
+    constructor(config: AgentConfig);
+    get name(): string;
+    get description(): string;
+    /** The declaration sent to the server. */
+    descriptor(): LinkAgentDescriptor;
+    /** Called by `Link.addAgent`. */
+    attach(link: AgentRunner): void;
+    /** One of this agent's tools, by its id. */
+    getTool(id: string): AnyTool | undefined;
+    /**
+     * Asks the agent something and waits for its reply.
+     *
+     * The run happens on the server, on the user's account; the question and the answer live
+     * here. Rejects with a `LinkError` when the agent could not run or failed — never with the
+     * agent's own prose, which is a reply like any other.
+     */
+    chat(message: string, options?: AgentChatOptions): Promise<AgentReply>;
+    /** Starts a fresh thread for the calls that follow, and returns it. */
+    newThread(): string;
+}
+/** Whether a server frame ends an `agent.chat` exchange. */
+export declare function isAgentResult(frame: LinkServerFrame): frame is LinkServerFrameOf<"agent.result">;

package/dist/link/agent.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+exports.isAgentResult = isAgentResult;
+/**
+ * An AI worker that lives on the server for as long as the link does, working with tools
+ * that run here.
+ *
+ * To Alfred it is one tool: he hands it a task and gets a reply, and the tools behind it
+ * stay behind it. To your code it is something to talk to directly — `chat` runs it on the
+ * server and hands the answer back here, so a hook callback can ask it to decide something
+ * and act on what it says.
+ */
+class Agent {
+    constructor(config) {
+        this.config = config;
+        this.id = config.id;
+        this.tools = [...(config.tools ?? [])];
+        this.thread = mintThread();
+        const ids = new Set();
+        for (const tool of this.tools) {
+            if (ids.has(tool.id))
+                throw new Error(`Agent "${this.id}" holds two tools with the id "${tool.id}".`);
+            ids.add(tool.id);
+        }
+    }
+    get name() {
+        return this.config.name;
+    }
+    get description() {
+        return this.config.description;
+    }
+    /** The declaration sent to the server. */
+    descriptor() {
+        return {
+            localId: this.id,
+            name: this.config.name,
+            description: this.config.description,
+            prompt: this.config.prompt,
+            ...(this.config.model ? { model: this.config.model } : {}),
+            // An agent's tools are placed by the agent, so whatever platform a tool
+            // declared for itself does not travel.
+            tools: this.tools.map(tool => {
+                const { platforms: _platforms, ...descriptor } = tool.descriptor();
+                return descriptor;
+            }),
+            ...(this.config.display ? { display: this.config.display } : {}),
+            ...(this.config.defaultEnabled !== undefined ? { defaultEnabled: this.config.defaultEnabled } : {}),
+        };
+    }
+    /** Called by `Link.addAgent`. */
+    attach(link) {
+        this.link = link;
+    }
+    /** One of this agent's tools, by its id. */
+    getTool(id) {
+        return this.tools.find(tool => tool.id === id);
+    }
+    /**
+     * Asks the agent something and waits for its reply.
+     *
+     * The run happens on the server, on the user's account; the question and the answer live
+     * here. Rejects with a `LinkError` when the agent could not run or failed — never with the
+     * agent's own prose, which is a reply like any other.
+     */
+    chat(message, options = {}) {
+        if (!this.link)
+            return Promise.reject(new Error(`Agent "${this.id}" has not been added to a link.`));
+        return this.link.chatAgent(this.id, message, { thread: this.thread, ...options });
+    }
+    /** Starts a fresh thread for the calls that follow, and returns it. */
+    newThread() {
+        this.thread = mintThread();
+        return this.thread;
+    }
+}
+exports.Agent = Agent;
+/** A thread id the server will accept: letters, digits, dot, dash, underscore, 64 at most. */
+function mintThread() {
+    const random = Math.random().toString(36).slice(2, 10);
+    return `t-${Date.now().toString(36)}-${random}`;
+}
+/** Whether a server frame ends an `agent.chat` exchange. */
+function isAgentResult(frame) {
+    return frame.type === "agent.result";
+}

package/dist/link/index.d.ts

@@ -2,10 +2,12 @@ export { Link } from "./link";
 export type { LinkOptions, LinkEvents, LinkState, ExchangeOptions } from "./link";
 export { Tool } from "./tool";
 export type { AnyTool, ToolConfig, ToolRunContext, ToolCallMeta, ToolStatusReporter, ToolInvocation } from "./tool";
+export { Agent } from "./agent";
+export type { AgentConfig, AgentChatOptions, AgentReply, AgentStatus, AgentRunner } from "./agent";
 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 type { LinkClientFrame, LinkClientFrameOf, LinkClientFrameType, LinkServerFrame, LinkServerFrameOf, LinkServerFrameType, LinkScopeKind, LinkToolDescriptor, LinkAgentDescriptor, LinkHookDeclaration, LinkHookEventDeclaration, } from "./protocol";
 export { SubscriptionStore } from "./subscriptions";
 export type { LinkSubscription, SubscriptionSnapshot, SubscriptionDelta } from "./subscriptions";
 export { matchesPrefilter, readPath } from "./prefilter";

package/dist/link/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultSocketFactory = exports.buildHandshake = exports.readPath = exports.matchesPrefilter = exports.SubscriptionStore = 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.Agent = 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");
 Object.defineProperty(exports, "Tool", { enumerable: true, get: function () { return tool_1.Tool; } });
+var agent_1 = require("./agent");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return agent_1.Agent; } });
 var hook_1 = require("./hook");
 Object.defineProperty(exports, "Hook", { enumerable: true, get: function () { return hook_1.Hook; } });
 var protocol_1 = require("./protocol");

package/dist/link/link.d.ts

@@ -1,3 +1,4 @@
+import { Agent, AgentChatOptions, AgentReply, AgentRunner } from "./agent";
 import { AnyHook } from "./hook";
 import { LinkClientFrameType, LinkClientPayloads, LinkScopeKind, LinkServerFrame } from "./protocol";
 import { SocketFactory } from "./socket";
@@ -83,10 +84,11 @@ export type ExchangeOptions = {
  * re-declared on connect, and ids are derived from your `linkId`, so a reconnect
  * anywhere lands on the same saved settings and subscriptions.
  */
-export declare class Link {
+export declare class Link implements AgentRunner {
     private readonly options;
     private readonly emitter;
     private readonly tools;
+    private readonly agents;
     private readonly hooks;
     private readonly subscriptionStore;
     private readonly pending;
@@ -129,10 +131,22 @@ export declare class Link {
     constructor(options: LinkOptions);
     /** Adds a tool Alfred can call. Registered on connect, or immediately if already open. */
     addTool(tool: AnyTool): this;
+    /**
+     * Adds an agent, with the tools it works with.
+     *
+     * The tools come with the agent — they need no `addTool` of their own, and giving them one
+     * would place them in the chat as well, which is the thing an agent exists to avoid. One
+     * namespace for everything the link declares, so an id used twice is refused here rather
+     * than resolved by whichever registered last.
+     */
+    addAgent(agent: Agent): this;
     /** Adds a hook that can wake the user's background agents. */
     addHook(hook: AnyHook): this;
     getTool(id: string): AnyTool | undefined;
     getHook(id: string): AnyHook | undefined;
+    getAgent(id: string): Agent | undefined;
+    /** A tool by its local id, wherever it lives: on the link itself or behind one of its agents. */
+    private findTool;
     get state(): LinkState;
     get linkId(): string;
     /** The ephemeral id of this connection. Changes on every reconnect. */
@@ -244,6 +258,15 @@ export declare class Link {
     private wait;
     private settleWaiters;
     private registerAll;
+    private registerAgents;
+    /**
+     * Called by `Agent.chat`.
+     *
+     * One exchange, however long the agent takes: status frames go to the caller as they
+     * arrive, and the result frame ends it. Never timed out here — an agent that is calling
+     * tools on this very machine may legitimately take a while.
+     */
+    chatAgent(agentId: string, message: string, options: AgentChatOptions): Promise<AgentReply>;
     private registerTools;
     private registerHook;
     /**

package/dist/link/link.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Link = void 0;
 const config_1 = require("../config");
 const emitter_1 = require("../util/emitter");
+const agent_1 = require("./agent");
 const protocol_1 = require("./protocol");
 const socket_1 = require("./socket");
 const subscriptions_1 = require("./subscriptions");
@@ -23,6 +24,7 @@ class Link {
     constructor(options) {
         this.emitter = new emitter_1.Emitter();
         this.tools = new Map();
+        this.agents = new Map();
         this.hooks = new Map();
         this.subscriptionStore = new subscriptions_1.SubscriptionStore();
         this.pending = new Map();
@@ -93,6 +95,29 @@ class Link {
             void this.registerTools([tool]);
         return this;
     }
+    /**
+     * Adds an agent, with the tools it works with.
+     *
+     * The tools come with the agent — they need no `addTool` of their own, and giving them one
+     * would place them in the chat as well, which is the thing an agent exists to avoid. One
+     * namespace for everything the link declares, so an id used twice is refused here rather
+     * than resolved by whichever registered last.
+     */
+    addAgent(agent) {
+        for (const tool of agent.tools) {
+            const holder = this.findTool(tool.id) ? "another tool" : this.agents.has(tool.id) ? "an agent" : undefined;
+            if (holder)
+                throw new Error(`Cannot add agent "${agent.id}": its tool "${tool.id}" shares an id with ${holder} on this link.`);
+        }
+        if (this.tools.has(agent.id) || this.findTool(agent.id)) {
+            throw new Error(`Cannot add agent "${agent.id}": a tool on this link already has that id.`);
+        }
+        this.agents.set(agent.id, agent);
+        agent.attach(this);
+        if (this.currentState === "open")
+            void this.registerAgents([agent]);
+        return this;
+    }
     /** Adds a hook that can wake the user's background agents. */
     addHook(hook) {
         this.hooks.set(hook.id, hook);
@@ -107,6 +132,21 @@ class Link {
     getHook(id) {
         return this.hooks.get(id);
     }
+    getAgent(id) {
+        return this.agents.get(id);
+    }
+    /** A tool by its local id, wherever it lives: on the link itself or behind one of its agents. */
+    findTool(localId) {
+        const own = this.tools.get(localId);
+        if (own)
+            return own;
+        for (const agent of this.agents.values()) {
+            const tool = agent.getTool(localId);
+            if (tool)
+                return tool;
+        }
+        return undefined;
+    }
     // =============================================
     // STATE
     // =============================================
@@ -516,9 +556,45 @@ class Link {
     // =============================================
     async registerAll() {
         await this.registerTools(Array.from(this.tools.values()));
+        await this.registerAgents(Array.from(this.agents.values()));
         for (const hook of this.hooks.values())
             await this.registerHook(hook);
     }
+    async registerAgents(agents) {
+        if (!agents.length)
+            return;
+        const frame = await this.exchange("agent.register", { agents: agents.map(agent => agent.descriptor()) }, { awaitReady: false });
+        const ids = frame.payload.ids ?? [];
+        agents.forEach((agent, index) => { agent.linkedId = ids[index]; });
+        this.debug(`registered ${agents.length} agent(s)`);
+    }
+    /**
+     * Called by `Agent.chat`.
+     *
+     * One exchange, however long the agent takes: status frames go to the caller as they
+     * arrive, and the result frame ends it. Never timed out here — an agent that is calling
+     * tools on this very machine may legitimately take a while.
+     */
+    async chatAgent(agentId, message, options) {
+        const frame = await this.exchange("agent.chat", {
+            localId: agentId,
+            message,
+            ...(options.thread ? { thread: options.thread } : {}),
+        }, {
+            timeoutMs: 0,
+            isDone: agent_1.isAgentResult,
+            onFrame: (update) => {
+                if (update.type === "agent.status")
+                    options.onStatus?.({ label: update.payload.label, state: update.payload.state });
+            },
+        });
+        if (!(0, agent_1.isAgentResult)(frame))
+            throw new protocol_1.LinkError("bad_frame", `Expected an agent.result, got "${frame.type}".`);
+        const { payload } = frame;
+        if (!payload.ok)
+            throw new protocol_1.LinkError(payload.code, payload.error);
+        return { text: payload.output, thread: payload.thread };
+    }
     async registerTools(tools) {
         if (!tools.length)
             return;
@@ -725,7 +801,7 @@ class Link {
     }
     handleToolCall(frame) {
         const { callId, localId, args, meta } = frame.payload;
-        const tool = this.tools.get(localId);
+        const tool = this.findTool(localId);
         if (!tool) {
             this.send("tool.result", { ok: false, error: `This link has no tool "${localId}".` }, frame.id);
             return;

package/dist/link/protocol.d.ts

@@ -24,6 +24,22 @@ export type LinkToolDescriptor = {
     platforms?: string[];
     timeoutMs?: number;
 };
+/**
+ * An agent as declared to the server: a prompt, a model and the tools it works with.
+ *
+ * The tools travel inside the agent because that is what places them: reachable through the
+ * agent only, never from a chat directly.
+ */
+export type LinkAgentDescriptor = {
+    localId: string;
+    name: string;
+    description: string;
+    prompt: string;
+    model?: string;
+    tools: Omit<LinkToolDescriptor, "platforms">[];
+    display?: LinkToolDescriptor["display"];
+    defaultEnabled?: boolean;
+};
 export type LinkHookEventDeclaration = {
     name: string;
     description?: string;
@@ -139,6 +155,18 @@ export type LinkClientPayloads = {
         chatId: string;
         message: string;
     };
+    "agent.register": {
+        agents: LinkAgentDescriptor[];
+    };
+    /**
+     * Talks to one of this link's agents directly. `thread` names the exchange the message
+     * continues; the same thread carries the same memory.
+     */
+    "agent.chat": {
+        localId: string;
+        message: string;
+        thread?: string;
+    };
 };
 export type LinkClientFrameType = keyof LinkClientPayloads;
 /**
@@ -230,6 +258,25 @@ export type LinkServerPayloads = {
         reason: string;
         reconnectAfterMs: number;
     };
+    /** Progress on an `agent.chat`, in the words the agent's status feed would show a conversation. */
+    "agent.status": {
+        localId: string;
+        label: string;
+        state: "running" | "completed" | "failed";
+    };
+    /** The agent's reply, exactly once per `agent.chat`. */
+    "agent.result": {
+        localId: string;
+        thread: string;
+        ok: true;
+        output: string;
+    } | {
+        localId: string;
+        thread?: string;
+        ok: false;
+        code: string;
+        error: string;
+    };
     /**
      * The full set this connection should watch, for the sources it has registered.
      *

package/dist/types/conversation/v3/conversation_v3.d.ts

@@ -207,6 +207,16 @@ export type ResponseStatusPayload = {
         /** When the stop was requested. */
         at: number;
     };
+    /**
+     * Messages steered into the turn that never reached the model, in the order they were sent.
+     *
+     * Steering only lands at a step boundary, and a turn does not always have another one: it
+     * stops, it fails, or the model answers without needing a further step. The text is not in
+     * the conversation's history — it was never said to anyone — so it is handed back here and
+     * the client decides what to do with it. Send it as an ordinary message when the turn
+     * merely ended; put it back in front of the user when they are the one who stopped it.
+     */
+    undeliveredSteer?: string[];
     /** Rich response metadata — only present on the final `completed: true` event.
      *  Populated by the caller (e.g. gateway) after the response finishes and usage is available. */
     metadata?: ResponseMetadata;

package/package.json

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

package/readme.md

@@ -212,6 +212,45 @@ whatever tier and permission gating it carries, which tools bolted onto the chat
 An unknown platform is rejected when you register, not ignored: a tool reachable from nowhere looks
 exactly like a tool that is broken.
 
+### Agents: your tools behind a worker of your own
+
+When your client has more tools than a chat should see, or tools that only make sense together,
+declare an agent. It lives on the server for as long as the link does, works with tools that run
+here, and to Alfred it is one tool:
+
+```ts
+import { Agent, Tool } from "@butlerbot/sdk";
+
+const grind = new Tool({ id: "grind", description: "Grind beans.", run: async () => grinder.run() });
+const brew = new Tool({ id: "brew", description: "Brew from the ground beans.", run: async () => machine.brew() });
+
+const barista = new Agent({
+    id: "barista",
+    name: "Barista",
+    description: "Runs the kitchen coffee machine: grinding, brewing, cleaning.",
+    prompt: "You operate a coffee machine. Always grind before you brew. Report what you made.",
+    model: "DeepSeek-V4-Flash",
+    tools: [grind, brew],
+});
+link.addAgent(barista);
+```
+
+The tools come with the agent — no `addTool` for them, and Alfred never sees them directly. The
+prompt is where a thousand tools become one coherent worker.
+
+You can talk to the agent yourself. The run happens on the server, on your account; the question
+and the answer live here:
+
+```ts
+const { text } = await barista.chat("Make me a flat white.");
+```
+
+One `Agent` remembers across `chat` calls; pass `{ thread }` to name the conversation yourself, or
+`newThread()` to start over. This is what makes a hook callback useful on its own: something
+happens, your code notices, and you ask an agent what to do about it.
+
+Needs `link.tools.register` to declare agents, and `tools.run` to talk to one directly.
+
 ### 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