paperclip-plugin-mattermost 0.17.0 → 0.18.1

package/README.md

@@ -14,6 +14,7 @@ Your [Paperclip](https://github.com/paperclipai/paperclip) agents as Mattermost
   - **Single-choice questions** get a button per option. Your pick is posted on the task as a comment from you, which wakes the agent.
 - **Access control.** Choose who may talk to agents: everyone, or only the people you pick. Each person can be limited to some agents, and people outside Paperclip can be added by email.
 - **Agents work in Mattermost themselves.** Through plugin API routes that only agents can call, each agent reads the channels its bot is in, posts, reacts, searches, and DMs the people allowed to talk to it, always as its own bot. Each company gets a Mattermost skill that tells agents how, and saving the settings adds it to every agent with a bot, so they can message people from tasks and scheduled runs too.
+- **Work happens in Paperclip tasks.** Asked to do something, an agent creates a Paperclip task, replies with its number, and does the work there. When the task is done, cancelled or blocked, its outcome is posted back in the thread it was asked in.
 - **Steering.** A message you send in a thread while its agent is still working reaches that run: the agent reads it between steps (and an agent waiting at its computer stops waiting to read it), so "stop" or a correction lands mid-task. One it read is marked ✅ and not run again.
 - **Agents work with agents.** An agent mentioning another agent starts it, and it answers in the thread. After a set number of agent-to-agent messages in a thread (10 by default, set in settings), they pause until a person replies.
 - **Work channels.** For an investigation, incident or project, an agent opens a private channel (`inc-checkout-5xx`), pulls in the people and agents it needs, and ties it to a Paperclip task. Task comments and status changes show up in the channel. When the task is done or cancelled, the channel is archived and the outcome is posted back where the work was asked for.
@@ -84,7 +85,7 @@ PAPERCLIP_REF=<commit> node build.mjs   # build for another Paperclip version
 Bump `version` in `package.json` and `src/manifest.ts`, commit, then tag and push:
 
 ```bash
-git tag -a v0.17.0 -m v0.17.0 && git push origin main v0.17.0
+git tag -a v0.18.1 -m v0.18.1 && git push origin main v0.18.1
 ```
 
 GitHub Actions builds, tests and publishes to npm through npm trusted publishing, so no npm token is involved.

package/dist/manifest.js

@@ -16,11 +16,13 @@ tell whoever you are working with and carry on. A 403 says why something is not
 
 ## How to work
 
-- **Pick the size of the work.** A quick question: answer in the thread. A task: create a Paperclip
-  task (assign it to yourself or delegate it) and say so in the thread with its identifier. An
-  investigation, incident or project, or anything involving several agents or more than a day:
-  create the task, then open a work channel for it (below), with the person who asked and whoever
-  you need. Name it for what it is: "inc checkout 5xx", "inv q3 conversion drop", "proj crm migration".
+- **Work within Paperclip tasks.** A quick question: answer in the thread. Anything you are asked to
+  do: create a Paperclip task first (assign it to yourself or delegate it) and say so in the thread
+  with its number. Do the work in the task and end with the outcome as its last comment: when the
+  task is done, cancelled or blocked, that comment is posted back in the thread it was asked in. An
+  investigation, incident or project, or anything involving several agents or more than a day: also
+  open a work channel for it (below), with the person who asked and whoever you need. Name it for
+  what it is: "inc checkout 5xx", "inv q3 conversion drop", "proj crm migration".
 - **Announce a work channel where the request came in**, in one message: what it is for, who you
   pulled in, and that you will report back there. When the task is done or cancelled the plugin
   archives the channel and posts the outcome back where you asked; you do not need to.
@@ -82,7 +84,7 @@ var route = (routeKey, method, path) => ({ routeKey, method, path, auth: "agent"
 var manifest = {
   id: "mattermost-bridge",
   apiVersion: 1,
-  version: "0.17.0",
+  version: "0.18.1",
   displayName: "Mattermost",
   description: "Every agent becomes its own Mattermost bot. DM an agent or mention it in a channel and it answers in the thread, showing its steps as it works; follow-ups continue the conversation. Paperclip approvals arrive with Approve / Reject buttons.",
   author: "Haseeb Azhar",

package/dist/worker.js

@@ -45353,6 +45353,7 @@ var Actions = class {
 // src/worklinks.ts
 var FROM_PAPERCLIP = { from_paperclip: "true" };
 var CLOSED = /* @__PURE__ */ new Set(["done", "cancelled"]);
+var THREAD_REPORTS = { done: ":white_check_mark: Done:", cancelled: ":no_entry_sign: Cancelled:", blocked: ":pause_button: Blocked:" };
 var STATUS_WORDS = {
   todo: "to do",
   in_progress: "in progress",
@@ -45388,6 +45389,25 @@ var WorkLinks = class {
 ${body}`;
     await this.d.post(own2 ? c.authorAgentId : hit.link.agentId, hit.channelId, "", text2);
   }
+  /**
+   * A task asked for in a Mattermost thread (created by the agent while answering there): when it is
+   * done, cancelled or blocked, its outcome (the last comment) is posted back in that thread, so the
+   * result always reaches the conversation it came from.
+   */
+  async threadUpdate(issueId) {
+    const at = await this.d.store.get(`issuethread:${issueId}`);
+    if (!at) return;
+    const task2 = await this.d.task(issueId);
+    if (!task2 || task2.status === at.status || !THREAD_REPORTS[task2.status]) return;
+    await this.d.store.set(`issuethread:${issueId}`, { ...at, status: task2.status });
+    const last = (await this.d.comments(issueId)).at(-1)?.body?.trim();
+    const outcome = last ? `
+
+${last.length > 3e3 ? last.slice(0, 3e3) + "\u2026" : last}` : "";
+    const by = [task2.assigneeAgentId, at.agentId].find((a) => Boolean(a && this.d.hasBot(a)));
+    if (!by) return;
+    await this.d.post(by, at.channelId, at.rootId, `${THREAD_REPORTS[task2.status]} **${task2.identifier ?? "The task"}** ${task2.title}${outcome}`);
+  }
   /** The task changed: note a new status; on done or cancelled, archive and report back. */
   async updated(issueId) {
     const hit = await this.linked(issueId);
@@ -45443,11 +45463,13 @@ tell whoever you are working with and carry on. A 403 says why something is not
 
 ## How to work
 
-- **Pick the size of the work.** A quick question: answer in the thread. A task: create a Paperclip
-  task (assign it to yourself or delegate it) and say so in the thread with its identifier. An
-  investigation, incident or project, or anything involving several agents or more than a day:
-  create the task, then open a work channel for it (below), with the person who asked and whoever
-  you need. Name it for what it is: "inc checkout 5xx", "inv q3 conversion drop", "proj crm migration".
+- **Work within Paperclip tasks.** A quick question: answer in the thread. Anything you are asked to
+  do: create a Paperclip task first (assign it to yourself or delegate it) and say so in the thread
+  with its number. Do the work in the task and end with the outcome as its last comment: when the
+  task is done, cancelled or blocked, that comment is posted back in the thread it was asked in. An
+  investigation, incident or project, or anything involving several agents or more than a day: also
+  open a work channel for it (below), with the person who asked and whoever you need. Name it for
+  what it is: "inc checkout 5xx", "inv q3 conversion drop", "proj crm migration".
 - **Announce a work channel where the request came in**, in one message: what it is for, who you
   pulled in, and that you will report back there. When the task is done or cancelled the plugin
   archives the channel and posts the outcome back where you asked; you do not need to.
@@ -45508,6 +45530,9 @@ ${HELP}`;
 import { randomUUID as randomUUID2 } from "node:crypto";
 
 // src/bridge.ts
+var IN_FLIGHT = "inflight";
+var IN_FLIGHT_MAX_AGE = 3 * 60 * 60 * 1e3;
+var RESUME_PROMPT = "The Mattermost plugin restarted while you were working on the conversation above, so your reply did not reach the thread. When you have finished, give your answer to the latest message again; it is posted in the thread.";
 var DEFAULT_TURN_LIMIT = 10;
 var TYPING_EVERY_MS = 3e3;
 var OLD_PLACEHOLDER = /^_(thinking…|.+ is working on it…)_/;
@@ -45750,7 +45775,7 @@ var Bridge = class {
     const attached = fileIds.length ? await this.files.receive(member.chat, post.id, fileIds) : [];
     const outbox = this.files ? await this.files.outbox(post.id).catch(() => null) : null;
     const fromAgent = this.roster().isBot(post.user_id);
-    const prompt = `${sender.displayName} (@${sender.username}${fromAgent ? ", another agent" : ""}) wrote to you (@${member.username}) in ${where} on Mattermost. Your reply is posted back there, so answer in Markdown. To offer choices, end your reply with one line \`choices: First | Second\` (2 to ${MAX_CHOICES} short options); they are shown as buttons, and the pick comes back as the next message. You can also read channels, post, message people, mention other agents and open work channels in Mattermost: GET <your Paperclip API URL>/api/plugins/mattermost-bridge/api/mm/help shows how. If this takes more than a minute or two, check GET \u2026/api/plugins/mattermost-bridge/api/mm/inbox between steps: it returns anything people write in this thread meanwhile (a correction, "stop", "never mind"); act on it then, as it is not sent to you again.` + (history ? `
+    const prompt = `${sender.displayName} (@${sender.username}${fromAgent ? ", another agent" : ""}) wrote to you (@${member.username}) in ${where} on Mattermost. Your reply is posted back there, so answer in Markdown. Work within Paperclip tasks: if the message asks you to do something (anything more than answering a quick question), first create a Paperclip task for it, assigned to yourself or to the agent it belongs with, and reply here with the task's number, what will happen, and that the result will come back to this thread. Then do the work in that task, not in this chat, and finish with the outcome as the task's last comment: when the task is done, cancelled or blocked, that comment is posted back here for you. Quick questions you can answer directly. To offer choices, end your reply with one line \`choices: First | Second\` (2 to ${MAX_CHOICES} short options); they are shown as buttons, and the pick comes back as the next message. You can also read channels, post, message people, mention other agents and open work channels in Mattermost: GET <your Paperclip API URL>/api/plugins/mattermost-bridge/api/mm/help shows how. If this takes more than a minute or two, check GET \u2026/api/plugins/mattermost-bridge/api/mm/inbox between steps: it returns anything people write in this thread meanwhile (a correction, "stop", "never mind"); act on it then, as it is not sent to you again.` + (history ? `
 
 Earlier in this thread (oldest first):
 ${history}
@@ -45768,25 +45793,82 @@ To send files back with your reply, save them in ${outbox}` : "");
     this.active.set(member.agentId, here);
     try {
       let sessionId = thread && thread.agentId === member.agentId ? thread.sessionId : null;
+      const flight = (id) => this.inFlight(rootId, { agentId: member.agentId, sessionId: id, channelId: post.channel_id, channelType: evt.channelType, channelName: evt.channelName, at: Date.now() });
       try {
         if (!sessionId) throw new Error("no session yet");
+        await flight(sessionId);
         reply = await this.agents.ask(sessionId, prompt);
-      } catch (first2) {
-        if (sessionId) this.log("session unusable, starting a new one", { sessionId, err: String(first2) });
+      } catch (first) {
+        if (sessionId) this.log("session unusable, starting a new one", { sessionId, err: String(first) });
         sessionId = await this.agents.createSession(member.agentId, `mattermost:${rootId}`);
         await this.store.set(threadKey, { agentId: member.agentId, sessionId });
+        await flight(sessionId);
         reply = await this.agents.ask(sessionId, prompt);
       }
     } catch (err) {
       if (this.active.get(member.agentId) === here) this.active.delete(member.agentId);
       this.inbox.delete(member.agentId);
+      await this.inFlight(rootId, null);
       await member.chat.createPost(post.channel_id, rootId, `:warning: ${member.agentName} could not answer: ${String(err?.message ?? err).slice(0, 500)}`);
       return;
     }
     if (this.active.get(member.agentId) === here) this.active.delete(member.agentId);
     this.inbox.delete(member.agentId);
+    await this.inFlight(rootId, null);
+    await this.postReply(member, { channelId: post.channel_id, rootId, channelType: evt.channelType, channelName: evt.channelName }, reply, outbox);
+  }
+  /** Records (or with null clears) the reply this thread is waiting for. */
+  async inFlight(rootId, f) {
+    const all = await this.store.get(IN_FLIGHT) ?? {};
+    if (f) all[rootId] = f;
+    else delete all[rootId];
+    await this.store.set(IN_FLIGHT, all);
+  }
+  /**
+   * After a plugin restart: every reply that was being waited for is asked for again from the same
+   * agent session (which queues behind the run still going), and posted in its thread when it comes.
+   */
+  async resume() {
+    const all = await this.store.get(IN_FLIGHT) ?? {};
+    let n = 0;
+    for (const [rootId, f] of Object.entries(all)) {
+      const member = this.roster().byAgentId(f.agentId);
+      if (!member || Date.now() - f.at > IN_FLIGHT_MAX_AGE) {
+        await this.inFlight(rootId, null);
+        continue;
+      }
+      n++;
+      const prev = this.queues.get(rootId) ?? Promise.resolve();
+      const next = prev.then(async () => {
+        const typing = () => {
+          void member.chat.typing(f.channelId, rootId).catch(() => {
+          });
+        };
+        typing();
+        const timer = setInterval(typing, TYPING_EVERY_MS);
+        try {
+          const reply = await this.agents.ask(f.sessionId, RESUME_PROMPT);
+          await this.inFlight(rootId, null);
+          await this.postReply(member, { channelId: f.channelId, rootId, channelType: f.channelType, channelName: f.channelName }, reply, null);
+        } catch (err) {
+          await this.inFlight(rootId, null);
+          await member.chat.createPost(f.channelId, rootId, `:warning: ${member.agentName}'s reply was lost when the plugin restarted: ${String(err?.message ?? err).slice(0, 300)}. Ask again here.`).catch(() => {
+          });
+        } finally {
+          clearInterval(timer);
+        }
+      }).catch((err) => this.log("resume failed", { err: String(err) }));
+      this.queues.set(rootId, next);
+      void next.finally(() => {
+        if (this.queues.get(rootId) === next) this.queues.delete(rootId);
+      });
+    }
+    return n;
+  }
+  async postReply(member, origin, reply, outbox) {
+    const post = { channel_id: origin.channelId };
+    const rootId = origin.rootId;
     const { text: body, choices } = extractChoices(linkTasks(absoluteLinks(reply ?? "", this.linkBase), this.linkBase, this.taskPrefix));
-    const origin = { channelId: post.channel_id, rootId, channelType: evt.channelType, channelName: evt.channelName };
     const buttons = choices.length && this.choiceButtons ? this.choiceButtons(origin, choices) : null;
     const shown = choices.length && !buttons ? `${body}
 
@@ -46283,7 +46365,7 @@ var route = (routeKey, method, path3) => ({ routeKey, method, path: path3, auth:
 var manifest = {
   id: "mattermost-bridge",
   apiVersion: 1,
-  version: "0.17.0",
+  version: "0.18.1",
   displayName: "Mattermost",
   description: "Every agent becomes its own Mattermost bot. DM an agent or mention it in a channel and it answers in the thread, showing its steps as it works; follow-ups continue the conversation. Paperclip approvals arrive with Approve / Reject buttons.",
   author: "Haseeb Azhar",
@@ -46637,7 +46719,8 @@ var Tenant = class {
       store,
       post: async (agentId, channelId, rootId, text2) => {
         const as = roster.clientOf(agentId) ?? manager;
-        await as.request("POST", "/posts", { channel_id: channelId, root_id: rootId, message: text2, props: FROM_PAPERCLIP });
+        const message2 = linkTasks(absoluteLinks(text2, paperclipUrl), paperclipUrl, bridge.taskPrefix);
+        await as.request("POST", "/posts", { channel_id: channelId, root_id: rootId, message: message2, props: FROM_PAPERCLIP });
       },
       hasBot: (agentId) => Boolean(roster.clientOf(agentId)),
       agentName: (agentId) => agentName(agentId),
@@ -46658,7 +46741,9 @@ var Tenant = class {
         this.status = `agent bot sync failed: ${errText(err)}`;
         ctx.logger.error(this.status, { companyId });
       });
-      void sync();
+      void sync().then(() => bridge.resume()).then((n) => {
+        if (n) ctx.logger.info("resuming replies interrupted by a restart", { companyId, threads: n });
+      }).catch((err) => warn("could not resume interrupted replies", { err: errText(err) }));
       this.timers.push(setInterval(sync, SYNC_EVERY_MS));
       void ensureSkill(companyId).catch((err) => warn("could not install the Mattermost skill", { err: errText(err) }));
       if (cards) {
@@ -46844,7 +46929,10 @@ var plugin = definePlugin({
       if (e.entityId && commentId) await tenants.get(e.companyId)?.work?.comment(e.entityId, commentId);
     }));
     ctx.events.on("issue.updated", (e) => quietly("could not follow a task update", async () => {
-      if (e.entityId) await tenants.get(e.companyId)?.work?.updated(e.entityId);
+      if (!e.entityId) return;
+      const work = tenants.get(e.companyId)?.work;
+      await work?.updated(e.entityId);
+      await work?.threadUpdate(e.entityId);
     }));
     ctx.events.on("plugin.agent-computer.needs-person", (e) => quietly("could not post a computer help request", async () => {
       await tenants.get(e.companyId)?.computerNeedsPerson(e.payload ?? {});
@@ -46855,7 +46943,7 @@ var plugin = definePlugin({
       const issue2 = await ctx.issues.get(e.entityId, e.companyId);
       const by = issue2?.createdByAgentId;
       const at = by ? tenant.bridge.activeThread(by) : null;
-      if (at) await tenant.store().set(`issuethread:${e.entityId}`, at);
+      if (at) await tenant.store().set(`issuethread:${e.entityId}`, { ...at, agentId: by, status: issue2?.status });
     }));
     ctx.events.on("approval.decided", (e) => quietly("could not update approval", async () => {
       if (e.entityId) await tenants.get(e.companyId)?.approvals?.decided(e.entityId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-plugin-mattermost",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Paperclip agents in Mattermost: a bot per agent, live progress, files, approval and decision buttons, and per-person access, for each Paperclip company.",
   "type": "module",
   "license": "MIT",