@butlerbot/sdk 0.0.32 → 0.0.34

package/dist/config.d.ts

@@ -1,5 +1,12 @@
 export declare const CONFIG: {
     server: string;
+    /**
+     * Where links connect.
+     *
+     * Not the core server: links are carried by their own service, so the SDK holds two
+     * addresses rather than one.
+     */
+    link: string;
     healthcheckPath: string;
     paths: {
         conversation: {
@@ -55,3 +62,15 @@ export declare const CONFIG: {
     };
 };
 export type APIPath = keyof typeof CONFIG.paths.conversation;
+/**
+ * Which server a link should connect to.
+ *
+ * `linkUrl` names it outright and always wins. Failing that, a `serverUrl` pointing anywhere
+ * other than the hosted core is taken at its word: a self-hosted stack is usually one address,
+ * and sending an API key to a host nobody named would be a worse surprise than a wrong path.
+ * Otherwise it is the hosted link service, which is what the core server used to be and is not.
+ */
+export declare function resolveLinkUrl(config: {
+    linkUrl?: string;
+    serverUrl?: string;
+}): string;

package/dist/config.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONFIG = void 0;
+exports.resolveLinkUrl = resolveLinkUrl;
 exports.CONFIG = {
     server: "https://core.butler.now",
+    /**
+     * Where links connect.
+     *
+     * Not the core server: links are carried by their own service, so the SDK holds two
+     * addresses rather than one.
+     */
+    link: "https://link.butler.now",
     healthcheckPath: "/api/healthcheck",
     paths: {
         conversation: {
@@ -45,3 +53,19 @@ exports.CONFIG = {
         }
     }
 };
+const withoutTrailingSlash = (url) => url.replace(/\/+$/, "");
+/**
+ * Which server a link should connect to.
+ *
+ * `linkUrl` names it outright and always wins. Failing that, a `serverUrl` pointing anywhere
+ * other than the hosted core is taken at its word: a self-hosted stack is usually one address,
+ * and sending an API key to a host nobody named would be a worse surprise than a wrong path.
+ * Otherwise it is the hosted link service, which is what the core server used to be and is not.
+ */
+function resolveLinkUrl(config) {
+    if (config.linkUrl)
+        return config.linkUrl;
+    if (config.serverUrl && withoutTrailingSlash(config.serverUrl) !== withoutTrailingSlash(exports.CONFIG.server))
+        return config.serverUrl;
+    return exports.CONFIG.link;
+}

package/dist/index.d.ts

@@ -9,6 +9,14 @@ type OptionalApiKey<T> = Omit<T, "apiKey"> & {
 export type ButlerBotClientOptions = {
     /** The server endpoint, API calls are sent here */
     serverUrl?: string;
+    /**
+     * Where links connect. Defaults to the hosted link service.
+     *
+     * Links are no longer carried by the core server, so this is a second address rather than
+     * a path on the first. A `serverUrl` pointing at your own stack is used for links too,
+     * unless this names somewhere else.
+     */
+    linkUrl?: string;
     /** The API key to use with ButlerBot */
     apiKey: string;
     /** Whether to enable debug logs */
@@ -17,6 +25,7 @@ export type ButlerBotClientOptions = {
 export declare class ButlerBotClient {
     private apiKey;
     private serverUrl;
+    private linkUrl;
     private debug;
     constructor(config: ButlerBotClientOptions);
     /** Checks the health of the server returning true if server is alive */
@@ -25,7 +34,10 @@ export declare class ButlerBotClient {
     createConversation<V extends APIPath = "v4">(config?: OptionalApiKey<ConversationOptions<V>>): Conversation<V>;
     /**
      * Creates a Link: a live connection that can register tools and hooks, and carry
-     * conversations. Inherits the client's API key and server URL.
+     * conversations. Inherits the client's API key and link URL.
+     *
+     * The link URL, not the server URL: links are served by their own service. Pass
+     * `serverUrl` here, or `linkUrl` to the client, to point somewhere else.
      */
     createLink(config: OptionalApiKey<LinkOptions>): Link;
     /** Get current usage policy data */
@@ -33,7 +45,8 @@ export declare class ButlerBotClient {
 }
 export * from "./types/type_registry";
 export * from "./link";
-export { Conversation, ConversationOptions };
+export { Conversation };
+export type { ConversationOptions };
 export type { APIPath };
 export type { ConversationStream, ConversationTransport, TransportTurnRequest, TransportHandlers, } from "./modules/transport";
 export { LinkConversationTransport } from "./modules/transport_link";

package/dist/index.js

@@ -20,10 +20,23 @@ const link_1 = require("./link");
 const conversation_1 = require("./modules/conversation");
 Object.defineProperty(exports, "Conversation", { enumerable: true, get: function () { return conversation_1.Conversation; } });
 const usage_1 = require("./modules/usage");
+/**
+ * The options a caller actually gave, with the keys they left out removed.
+ *
+ * A client's own API key and URLs are the fallback for whatever a factory call omits, and the
+ * usual way to omit something is to forward an optional setting that happens to be unset —
+ * `createLink({ serverUrl: process.env.LINK_URL })`. Spread as it stands, that `undefined`
+ * lands on top of the client's resolved value and erases it, so the link ends up at the hosted
+ * service rather than the self-hosted stack the client was pointed at. Absent means "not given".
+ */
+function given(config) {
+    return Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
+}
 class ButlerBotClient {
     constructor(config) {
         this.apiKey = config.apiKey;
         this.serverUrl = config.serverUrl || config_1.CONFIG.server;
+        this.linkUrl = (0, config_1.resolveLinkUrl)(config);
         this.debug = config.debug || false;
     }
     /** Checks the health of the server returning true if server is alive */
@@ -41,14 +54,17 @@ class ButlerBotClient {
     }
     /** Spawns a new Conversation, inherits api key and server URL */
     createConversation(config = {}) {
-        return new conversation_1.Conversation({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...config });
+        return new conversation_1.Conversation({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...given(config) });
     }
     /**
      * Creates a Link: a live connection that can register tools and hooks, and carry
-     * conversations. Inherits the client's API key and server URL.
+     * conversations. Inherits the client's API key and link URL.
+     *
+     * The link URL, not the server URL: links are served by their own service. Pass
+     * `serverUrl` here, or `linkUrl` to the client, to point somewhere else.
      */
     createLink(config) {
-        return new link_1.Link({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...config });
+        return new link_1.Link({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.linkUrl, ...given(config) });
     }
     /** Get current usage policy data */
     getUsagePolicyData(config) {

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";
@@ -48,6 +49,7 @@ export type LinkOptions = {
      * one takes over and the older one's registrations are released.
      */
     linkId: string;
+    /** The link service. Defaults to the hosted one, which is not the core server. */
     serverUrl?: string;
     /** Informational, shown in server logs. Defaults to the SDK name. */
     client?: string;
@@ -83,10 +85,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 +132,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 +259,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();
@@ -64,7 +66,7 @@ class Link {
             reconnect: true,
             debug: false,
             client: "@butlerbot/sdk",
-            serverUrl: config_1.CONFIG.server,
+            serverUrl: config_1.CONFIG.link,
             socketFactory: socket_1.defaultSocketFactory,
             ...stripUndefined(options),
         };
@@ -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;
 /**
@@ -208,12 +236,19 @@ export type LinkServerPayloads = {
         chatId?: string;
         message: string;
     };
+    /**
+     * A turn ended, one way or another.
+     *
+     * `lastEventId` comes with `turn_suspended`: the turn is still being answered somewhere
+     * and this is where a `conversation.attach` should pick it back up.
+     */
     "conversation.done": {
         chatId?: string;
         ok: boolean;
         code?: string;
         error?: string;
         message?: string;
+        lastEventId?: string;
     };
     /** A turn was stopped. `mode` is what was applied, `requestedMode` what was asked for. */
     "conversation.stopped": {
@@ -230,6 +265,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/modules/transport_link.d.ts

@@ -50,6 +50,35 @@ export declare class LinkConversationTransport implements ConversationTransport
      */
     attach(request: TransportAttachRequest, handlers: TransportHandlers): ConversationStream;
     private runTurn;
+    /**
+     * One `conversation.attach`: streams a turn's events to the caller and resolves with how
+     * that watch ended.
+     *
+     * Shared by watching somebody else's turn and by rejoining one of our own, because from
+     * here the two are the same act. `progress` is carried rather than returned: a watch that
+     * dies halfway still has to leave behind where it got to, or a resume would replay from
+     * the beginning and the caller would read the answer twice.
+     */
+    private watch;
+    /**
+     * Picks a turn back up after losing sight of it.
+     *
+     * Two ways to lose one, one way to get it back. The socket can go — a deploy of the link
+     * service, a proxy timing out — which rejects the exchange carrying the turn. Or core can
+     * suspend the turn at its own deploy and hand it to another instance, which the link
+     * service follows for two minutes before giving up and saying `turn_suspended`. Either way
+     * the turn is still being answered and the conversation still holds it, so this re-attaches
+     * from the last event the caller was actually given and the stream reads as one answer.
+     *
+     * `no_active_turn` is the ambiguous reply and it is deliberately not treated as an ending:
+     * during a handover it means "not picked up yet" far more often than it means "gone", and
+     * the window is what decides between them.
+     *
+     * Nothing here throws. It runs behind a stream the caller already holds, so the outcomes
+     * that matter are the ones delivered into it: a completion, or a failure that says plainly
+     * that the answer was lost track of rather than that it failed.
+     */
+    private resume;
     /** Opens a session, or reuses the open one when it is for the same conversation. */
     private session;
 }

package/dist/modules/transport_link.js

@@ -3,6 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LinkConversationTransport = void 0;
 const protocol_1 = require("../link/protocol");
 const transport_1 = require("./transport");
+/**
+ * How long to keep trying to pick a lost turn back up before giving up on it.
+ *
+ * A turn belongs to its conversation, not to the socket that asked for one, so neither losing
+ * the connection nor losing the instance answering it — which is what a deploy does — ends it.
+ * Long enough to outlast a deploy of either service, short enough that a caller awaiting a
+ * reply is not left there forever when the turn really is gone.
+ */
+const RESUME_WINDOW_MS = 60000;
+/** Waits between attempts to pick a turn back up. The last value repeats. */
+const RESUME_BACKOFF_MS = [250, 500, 1000, 2000, 4000, 5000];
 /**
  * Carries a turn over an existing Link connection.
  *
@@ -18,20 +29,20 @@ class LinkConversationTransport {
         link.on("disconnect", () => { this.sessionId = undefined; });
     }
     send(request, handlers) {
-        let closed = false;
+        const listening = { closed: false };
         const deliver = {
-            payload: (payload) => { if (!closed)
+            payload: (payload) => { if (!listening.closed)
                 handlers.payload(payload); },
-            convoId: (convoId) => { if (!closed)
+            convoId: (convoId) => { if (!listening.closed)
                 handlers.convoId(convoId); },
         };
-        void this.runTurn(request, deliver, true).catch((error) => {
+        void this.runTurn(request, deliver, true, listening).catch((error) => {
             const failure = error instanceof protocol_1.LinkError
                 ? (0, transport_1.failurePayload)(error.code, error.message, error.message, request.chatId)
                 : (0, transport_1.failurePayload)("link_error", String(error), "I'm afraid the connection to Alfred failed.", request.chatId);
             deliver.payload(failure);
         });
-        return { close: () => { closed = true; } };
+        return { close: () => { listening.closed = true; } };
     }
     /**
      * Stops a running turn.
@@ -96,57 +107,46 @@ class LinkConversationTransport {
      * ordinary answer for one that is simply idle.
      */
     attach(request, handlers) {
-        let closed = false;
-        const deliver = (payload) => { if (!closed)
+        const listening = { closed: false };
+        const deliver = (payload) => { if (!listening.closed)
             handlers.payload(payload); };
-        const watching = this.link.exchange("conversation.attach", {
-            chatId: request.chatId,
-            ...(request.afterEventId ? { afterEventId: request.afterEventId } : {}),
-        }, {
-            // A turn takes as long as it takes; only the transport dying ends it early.
-            timeoutMs: 0,
-            isDone: (frame) => frame.type === "conversation.done",
-            onFrame: (frame) => {
-                if (frame.type === "conversation.event") {
-                    const payload = frame.payload;
-                    const event = payload.event;
-                    const final = event.type === "response_status" && Boolean(event.payload?.completed);
-                    deliver({
-                        success: true,
-                        data: {
-                            response: event,
-                            convoId: payload.chatId ?? request.chatId,
-                            ...(final ? { quitStream: true } : {}),
-                        },
-                    });
-                    return;
-                }
-                if (frame.type === "conversation.notice") {
-                    deliver((0, transport_1.noticePayload)(frame.payload.message, frame.payload.chatId ?? request.chatId));
-                }
-            },
-        });
-        void watching.then((done) => {
-            const payload = done.payload;
+        const progress = { chatId: request.chatId, lastEventId: request.afterEventId, sawCompletion: false };
+        // Watching is allowed to end in silence, which is why `quietWhenGone` is true here and
+        // false for a turn of our own: nobody is waiting on an answer to a question they asked.
+        const resume = () => this.resume(request.chatId, progress, deliver, listening, { quietWhenGone: true });
+        void this.watch(request.chatId, progress, deliver).then(async (payload) => {
             if (payload.ok)
                 return;
             // Nothing running is not a failure: the caller asked to watch a conversation
             // that has nothing to watch, and the stream simply ends.
             if (payload.code === "no_active_turn")
                 return;
+            // The turn is alive, somewhere this connection can no longer see. Following it is
+            // the entire point of being here.
+            if (payload.code === "turn_suspended") {
+                if (payload.lastEventId)
+                    progress.lastEventId = payload.lastEventId;
+                await resume();
+                return;
+            }
             deliver((0, transport_1.failurePayload)(payload.code ?? "link_error", payload.error ?? "The turn could not be watched.", payload.message ?? payload.error ?? "I'm afraid I couldn't follow that response.", payload.chatId ?? request.chatId));
-        }, (error) => {
+        }, async (error) => {
             if (error instanceof protocol_1.LinkError && error.code === "no_active_turn")
                 return;
+            // The socket went while we were watching. The turn did not go with it.
+            if (error instanceof protocol_1.LinkError && error.code === "disconnected") {
+                await resume();
+                return;
+            }
             deliver(error instanceof protocol_1.LinkError
                 ? (0, transport_1.failurePayload)(error.code, error.message, error.message, request.chatId)
                 : (0, transport_1.failurePayload)("link_error", String(error), "I'm afraid the connection to Alfred failed.", request.chatId));
         });
         return {
             close: () => {
-                if (closed)
+                if (listening.closed)
                     return;
-                closed = true;
+                listening.closed = true;
                 // Best-effort: a socket that has gone has already ended the watch for us.
                 try {
                     this.link.send("conversation.detach", { chatId: request.chatId });
@@ -157,15 +157,14 @@ class LinkConversationTransport {
             },
         };
     }
-    async runTurn(request, handlers, mayRetry) {
+    async runTurn(request, handlers, mayRetry, listening) {
         const sessionId = await this.session(request);
-        let chatId = request.chatId ?? this.sessionChatId;
+        const progress = { chatId: request.chatId ?? this.sessionChatId, sawCompletion: false };
         let announcedChatId = false;
-        let sawCompletion = false;
         const learnChatId = (candidate) => {
             if (!candidate)
                 return;
-            chatId = candidate;
+            progress.chatId = candidate;
             this.sessionChatId = candidate;
             handlers.convoId(candidate);
             // Mirrors the HTTP transport's first byte, which tells a client which
@@ -176,13 +175,99 @@ class LinkConversationTransport {
                 handlers.payload((0, transport_1.convoStartedPayload)(candidate));
             }
         };
-        learnChatId(chatId);
-        const done = await this.link.exchange("conversation.chat", {
-            sessionId,
-            message: request.message,
-            ...(request.model ? { model: request.model } : {}),
-            ...(request.instructions ? { instructions: request.instructions } : {}),
-            ...(request.personality ? { personality: request.personality } : {}),
+        learnChatId(progress.chatId);
+        let done;
+        try {
+            done = await this.link.exchange("conversation.chat", {
+                sessionId,
+                message: request.message,
+                ...(request.model ? { model: request.model } : {}),
+                ...(request.instructions ? { instructions: request.instructions } : {}),
+                ...(request.personality ? { personality: request.personality } : {}),
+            }, {
+                // A turn takes as long as it takes; only the transport dying ends it early.
+                timeoutMs: 0,
+                isDone: (frame) => frame.type === "conversation.done",
+                onFrame: (frame) => {
+                    if (frame.type === "conversation.event") {
+                        const payload = frame.payload;
+                        learnChatId(payload.chatId);
+                        if (payload.eventId)
+                            progress.lastEventId = payload.eventId;
+                        const event = payload.event;
+                        const final = event.type === "response_status" && Boolean(event.payload?.completed);
+                        if (final)
+                            progress.sawCompletion = true;
+                        handlers.payload({
+                            success: true,
+                            data: {
+                                response: event,
+                                ...(payload.chatId ?? progress.chatId ? { convoId: payload.chatId ?? progress.chatId } : {}),
+                                ...(final ? { quitStream: true } : {}),
+                            },
+                        });
+                        return;
+                    }
+                    if (frame.type === "conversation.notice") {
+                        const payload = frame.payload;
+                        learnChatId(payload.chatId);
+                        handlers.payload((0, transport_1.noticePayload)(payload.message, payload.chatId ?? progress.chatId));
+                    }
+                },
+            });
+        }
+        catch (error) {
+            // The socket went while the turn was running. The turn did not go with it: it
+            // belongs to the conversation, and the conversation outlives this connection.
+            if (progress.chatId && error instanceof protocol_1.LinkError && error.code === "disconnected") {
+                await this.resume(progress.chatId, progress, handlers.payload, listening, { quietWhenGone: false });
+                return;
+            }
+            throw error;
+        }
+        const payload = done.payload;
+        learnChatId(payload.chatId);
+        if (payload.ok) {
+            // Nearly always the pipeline's own completion event has already closed the
+            // stream; this is for the turn that ended without one.
+            if (!progress.sawCompletion)
+                handlers.payload((0, transport_1.completedPayload)(payload.chatId ?? progress.chatId));
+            return;
+        }
+        // The session died with a connection we have since replaced. Reopening it is
+        // invisible to the caller, and the message has not been delivered yet.
+        if (payload.code === "unknown_session" && mayRetry) {
+            this.sessionId = undefined;
+            await this.runTurn(request, handlers, false, listening);
+            return;
+        }
+        // Core suspended the turn at a deploy and handed it to another instance, and the link
+        // service followed it as far as it could. The answer is still being written; rejoining
+        // it is the difference between a deploy costing a reply and costing nothing.
+        if (payload.code === "turn_suspended" && progress.chatId) {
+            if (payload.lastEventId)
+                progress.lastEventId = payload.lastEventId;
+            await this.resume(progress.chatId, progress, handlers.payload, listening, { quietWhenGone: false });
+            return;
+        }
+        handlers.payload((0, transport_1.failurePayload)(
+        // `turn_failed` means the dialogue itself failed, and then `error` holds the
+        // code the HTTP transport would have reported.
+        payload.code === "turn_failed" ? payload.error ?? payload.code : payload.code ?? "link_error", payload.error ?? "The turn failed.", payload.message ?? payload.error ?? "I'm afraid that turn could not be completed.", payload.chatId ?? progress.chatId));
+    }
+    /**
+     * One `conversation.attach`: streams a turn's events to the caller and resolves with how
+     * that watch ended.
+     *
+     * Shared by watching somebody else's turn and by rejoining one of our own, because from
+     * here the two are the same act. `progress` is carried rather than returned: a watch that
+     * dies halfway still has to leave behind where it got to, or a resume would replay from
+     * the beginning and the caller would read the answer twice.
+     */
+    async watch(chatId, progress, deliver) {
+        const done = await this.link.exchange("conversation.attach", {
+            chatId,
+            ...(progress.lastEventId ? { afterEventId: progress.lastEventId } : {}),
         }, {
             // A turn takes as long as it takes; only the transport dying ends it early.
             timeoutMs: 0,
@@ -190,48 +275,112 @@ class LinkConversationTransport {
             onFrame: (frame) => {
                 if (frame.type === "conversation.event") {
                     const payload = frame.payload;
-                    learnChatId(payload.chatId);
+                    if (payload.eventId)
+                        progress.lastEventId = payload.eventId;
                     const event = payload.event;
                     const final = event.type === "response_status" && Boolean(event.payload?.completed);
                     if (final)
-                        sawCompletion = true;
-                    handlers.payload({
+                        progress.sawCompletion = true;
+                    deliver({
                         success: true,
                         data: {
                             response: event,
-                            ...(payload.chatId ?? chatId ? { convoId: payload.chatId ?? chatId } : {}),
+                            convoId: payload.chatId ?? chatId,
                             ...(final ? { quitStream: true } : {}),
                         },
                     });
                     return;
                 }
                 if (frame.type === "conversation.notice") {
-                    const payload = frame.payload;
-                    learnChatId(payload.chatId);
-                    handlers.payload((0, transport_1.noticePayload)(payload.message, payload.chatId ?? chatId));
+                    deliver((0, transport_1.noticePayload)(frame.payload.message, frame.payload.chatId ?? chatId));
                 }
             },
         });
-        const payload = done.payload;
-        learnChatId(payload.chatId);
-        if (payload.ok) {
-            // Nearly always the pipeline's own completion event has already closed the
-            // stream; this is for the turn that ended without one.
-            if (!sawCompletion)
-                handlers.payload((0, transport_1.completedPayload)(payload.chatId ?? chatId));
+        return done.payload;
+    }
+    /**
+     * Picks a turn back up after losing sight of it.
+     *
+     * Two ways to lose one, one way to get it back. The socket can go — a deploy of the link
+     * service, a proxy timing out — which rejects the exchange carrying the turn. Or core can
+     * suspend the turn at its own deploy and hand it to another instance, which the link
+     * service follows for two minutes before giving up and saying `turn_suspended`. Either way
+     * the turn is still being answered and the conversation still holds it, so this re-attaches
+     * from the last event the caller was actually given and the stream reads as one answer.
+     *
+     * `no_active_turn` is the ambiguous reply and it is deliberately not treated as an ending:
+     * during a handover it means "not picked up yet" far more often than it means "gone", and
+     * the window is what decides between them.
+     *
+     * Nothing here throws. It runs behind a stream the caller already holds, so the outcomes
+     * that matter are the ones delivered into it: a completion, or a failure that says plainly
+     * that the answer was lost track of rather than that it failed.
+     */
+    async resume(chatId, progress, deliver, listening, options) {
+        const deadline = Date.now() + RESUME_WINDOW_MS;
+        for (let attempt = 0; !listening.closed && Date.now() < deadline; attempt++) {
+            if (attempt > 0)
+                await pause(RESUME_BACKOFF_MS[Math.min(attempt - 1, RESUME_BACKOFF_MS.length - 1)]);
+            if (listening.closed)
+                return;
+            try {
+                // The link reconnects on its own; this waits for it rather than racing it.
+                await this.link.ready();
+            }
+            catch (error) {
+                // Closed for good means nobody is coming back. Anything else is the link still
+                // being down, which is exactly what the window is for.
+                if (error instanceof protocol_1.LinkError && error.code === "closed")
+                    break;
+                continue;
+            }
+            // An attachment from before may still be registered against a connection that is
+            // itself still alive, and the server allows only one per conversation. Dropping it
+            // first costs nothing when there is none to drop.
+            try {
+                this.link.send("conversation.detach", { chatId });
+            }
+            catch {
+                // Not connected. The server dropped the attachment with the socket.
+            }
+            let payload;
+            try {
+                payload = await this.watch(chatId, progress, deliver);
+            }
+            catch (error) {
+                if (error instanceof protocol_1.LinkError && error.code === "closed")
+                    break;
+                if (error instanceof protocol_1.LinkError && error.code === "no_active_turn" && options.quietWhenGone)
+                    return;
+                continue;
+            }
+            if (payload.ok) {
+                if (!progress.sawCompletion)
+                    deliver((0, transport_1.completedPayload)(payload.chatId ?? chatId));
+                return;
+            }
+            // Not picked up yet, or suspended again mid-hop. Both mean it is still moving.
+            if (payload.code === "no_active_turn") {
+                if (options.quietWhenGone)
+                    return;
+                continue;
+            }
+            if (payload.code === "turn_suspended") {
+                if (payload.lastEventId)
+                    progress.lastEventId = payload.lastEventId;
+                continue;
+            }
+            deliver((0, transport_1.failurePayload)(payload.code ?? "link_error", payload.error ?? "The turn could not be picked back up.", payload.message ?? payload.error ?? "I'm afraid I couldn't follow that response.", payload.chatId ?? chatId));
             return;
         }
-        // The session died with a connection we have since replaced. Reopening it is
-        // invisible to the caller, and the message has not been delivered yet.
-        if (payload.code === "unknown_session" && mayRetry) {
-            this.sessionId = undefined;
-            await this.runTurn(request, handlers, false);
+        if (listening.closed)
             return;
-        }
-        handlers.payload((0, transport_1.failurePayload)(
-        // `turn_failed` means the dialogue itself failed, and then `error` holds the
-        // code the HTTP transport would have reported.
-        payload.code === "turn_failed" ? payload.error ?? payload.code : payload.code ?? "link_error", payload.error ?? "The turn failed.", payload.message ?? payload.error ?? "I'm afraid that turn could not be completed.", payload.chatId ?? chatId));
+        // The completion already reached the caller; there is nothing left to say.
+        if (progress.sawCompletion)
+            return;
+        if (options.quietWhenGone)
+            return;
+        deliver((0, transport_1.failurePayload)("turn_suspended", "The turn could not be picked back up.", "I'm afraid I lost track of that answer. It may well have finished — reopen the conversation to see where it got to.", chatId));
     }
     /** Opens a session, or reuses the open one when it is for the same conversation. */
     async session(request) {
@@ -257,3 +406,10 @@ class LinkConversationTransport {
     }
 }
 exports.LinkConversationTransport = LinkConversationTransport;
+/** Waits, without keeping a Node process alive on its own. */
+function pause(ms) {
+    return new Promise(resolve => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}

package/package.json

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

package/readme.md

@@ -78,7 +78,12 @@ between you and the socket.
 
 ## Link
 
-A Link is a live connection to Alfred. It does three things:
+A Link is a live connection to Alfred, served by its own endpoint — `link.butler.now`,
+not the core API server. `createLink` goes there by default; pass `linkUrl` to the client
+(or `serverUrl` to `createLink`) to point somewhere else. A client given a `serverUrl` of
+its own — a self-hosted stack — uses that for links too.
+
+It does three things:
 
 - **Tools** — Alfred calls code that runs on your machine
 - **Hooks** — your code wakes the user's background agents when something happens
@@ -212,6 +217,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
@@ -247,9 +291,15 @@ Which to use:
   Best when you are already running a link for tools or hooks, or holding many
   conversations at once — one socket carries them all.
 
-One difference to know about: sessions are ephemeral. If the connection drops mid-turn
-the SDK reopens the session and resends transparently; the conversation itself is
-persisted server-side, so nothing is lost.
+A turn survives losing the connection it was asked for on. Sessions are ephemeral — the
+server drops one with its socket — but the turn belongs to the conversation, so when the
+socket goes mid-answer the SDK reconnects, rejoins the turn from the last event it gave
+you, and carries on into the same stream. The same holds when the platform deploys
+mid-turn and the answer is handed to another instance. A message that had not been
+delivered yet is simply sent again on a fresh session; one that had is never sent twice.
+
+If the turn cannot be picked back up within a minute, the stream ends with a failure that
+says so — the reply may still have finished, and reopening the conversation will show it.
 
 ### Rejoining a turn already in progress