paperclip-plugin-mattermost 0.15.1 → 0.16.0

package/README.md

@@ -14,10 +14,11 @@ 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.
+- **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.
 - **Ask first.** Some actions wait for an approver to click Approve: `@channel`, `@all` and `@here`, public channels, and adding people to a channel the agent didn't create. Agents can't change or archive channels they didn't create, remove anyone, or touch team and server settings.
-- **Agent computer requests.** With the Agent computer plugin installed, an agent that needs a person in its browser (a login, 2FA, a password) posts in the thread it is working in, or the approvals channel, with a link to take over.
+- **Agent computer requests.** With the Agent computer plugin installed, an agent that needs a person at its computer (a login, 2FA, a password) posts in the thread it is working in, or the approvals channel, with a link to take over.
 - **One install, many companies.** Each Paperclip company connects its own Mattermost, with its own settings, bots and state.
 
 ## Requirements
@@ -83,7 +84,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.15.1 -m v0.15.1 && git push origin main v0.15.1
+git tag -a v0.16.0 -m v0.16.0 && git push origin main v0.16.0
 ```
 
 GitHub Actions builds, tests and publishes to npm through npm trusted publishing, so no npm token is involved.

package/dist/manifest.js

@@ -32,6 +32,13 @@ tell whoever you are working with and carry on. A 403 says why something is not
 - Do not write @channel, @all or @here unless everyone in the channel must be notified: it needs
   approval.
 
+## While you work
+
+If people write in the thread you are answering while you work (a correction, "stop", "never mind"),
+it reaches you: GET /mm/inbox returns those messages, and any other /mm call you make carries them
+as \`newMessages\`. Check /mm/inbox between steps of anything that takes more than a minute or two,
+and act on what you find then. Each message is handed to you once; it is not sent again afterwards.
+
 ## Calls
 
 Reading (GET):
@@ -42,6 +49,7 @@ Reading (GET):
 - /mm/search?q=words                        search messages in your channels
 - /mm/people?q=name                         find people and agents by name
 - /mm/requests/{id}                         an approval request you made
+- /mm/inbox                                 what people wrote in your thread while you were working
 
 Talking (POST, JSON body):
 - /mm/post      {"channel": "...", "text": "...", "threadId": "optional post id to reply to"}
@@ -74,7 +82,7 @@ var route = (routeKey, method, path) => ({ routeKey, method, path, auth: "agent"
 var manifest = {
   id: "mattermost-bridge",
   apiVersion: 1,
-  version: "0.15.1",
+  version: "0.16.0",
   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",
@@ -90,6 +98,7 @@ var manifest = {
     "plugin.state.write",
     "http.outbound",
     "events.subscribe",
+    "events.emit",
     "webhooks.receive",
     "approvals.read",
     "approvals.respond",
@@ -110,6 +119,7 @@ var manifest = {
   // checks the caller is an agent and scopes it to that agent's company.
   apiRoutes: [
     route("help", "GET", "/mm/help"),
+    route("inbox", "GET", "/mm/inbox"),
     route("channels", "GET", "/mm/channels"),
     route("channel-posts", "GET", "/mm/channels/:channel/posts"),
     route("thread", "GET", "/mm/posts/:postId/thread"),

package/dist/worker.js

@@ -45456,6 +45456,13 @@ tell whoever you are working with and carry on. A 403 says why something is not
 - Do not write @channel, @all or @here unless everyone in the channel must be notified: it needs
   approval.
 
+## While you work
+
+If people write in the thread you are answering while you work (a correction, "stop", "never mind"),
+it reaches you: GET /mm/inbox returns those messages, and any other /mm call you make carries them
+as \`newMessages\`. Check /mm/inbox between steps of anything that takes more than a minute or two,
+and act on what you find then. Each message is handed to you once; it is not sent again afterwards.
+
 ## Calls
 
 Reading (GET):
@@ -45466,6 +45473,7 @@ Reading (GET):
 - /mm/search?q=words                        search messages in your channels
 - /mm/people?q=name                         find people and agents by name
 - /mm/requests/{id}                         an approval request you made
+- /mm/inbox                                 what people wrote in your thread while you were working
 
 Talking (POST, JSON body):
 - /mm/post      {"channel": "...", "text": "...", "threadId": "optional post id to reply to"}
@@ -45513,6 +45521,11 @@ function mentions(text2) {
 function stripMention(text2, username) {
   return text2.replace(new RegExp(`(^|[^\\w@])@${username.replace(/[.-]/g, "\\$&")}\\b[:,]?`, "gi"), "$1").replace(/\s{2,}/g, " ").trim();
 }
+function absoluteLinks(text2, base) {
+  if (!base) return text2;
+  const root = base.replace(/\/+$/, "");
+  return text2.replace(/\]\((\/(?!\/)[^)\s]*)\)/g, (_m, path3) => `](${root}${path3})`);
+}
 function splitMessage(text2, max = MAX_POST) {
   const parts = [];
   let rest = text2;
@@ -45538,6 +45551,16 @@ var Bridge = class {
   choiceButtons;
   canTalk;
   turnLimit;
+  /** Paperclip's public URL, for agents' relative links. */
+  linkBase = "";
+  /**
+   * Steering: messages people send in a thread while its agent is mid-run, kept for that agent to
+   * read in the same run (`takeInbox`). One it read is not run again afterwards.
+   */
+  inbox = /* @__PURE__ */ new Map();
+  delivered = /* @__PURE__ */ new Set();
+  /** Told when a person writes to an agent that is busy (the computer plugin wakes a waiting agent). */
+  onSteer = null;
   constructor(roster, directory, agents, store, log = () => {
   }, files = null, choiceButtons = null, canTalk = null, turnLimit = DEFAULT_TURN_LIMIT) {
     this.files = files;
@@ -45559,6 +45582,7 @@ var Bridge = class {
     this.seen.add(evt.post.id);
     if (this.seen.size > 5e3) this.seen.delete(this.seen.values().next().value);
     const rootId = evt.post.root_id || evt.post.id;
+    this.steer(evt, rootId);
     const prev = this.queues.get(rootId) ?? Promise.resolve();
     const next = prev.then(() => this.process(evt, rootId)).catch((err) => this.log("bridge error", { err: String(err) }));
     this.queues.set(rootId, next);
@@ -45567,6 +45591,36 @@ var Bridge = class {
     });
     return next;
   }
+  /** A person writing in a thread whose agent is mid-run: offered to that run as well as queued. */
+  steer(evt, rootId) {
+    const { post } = evt;
+    if (!post.root_id || post.type || post.props?.from_webhook === "true" || post.props?.from_paperclip === "true" || post.props?.from_bot === "true") return;
+    if (this.roster().isBot(post.user_id) || !post.message?.trim()) return;
+    for (const [agentId, at] of this.active) {
+      if (at.rootId !== rootId) continue;
+      const list2 = this.inbox.get(agentId) ?? [];
+      list2.push({ id: post.id, rootId, userId: post.user_id, text: post.message.slice(0, 4e3), at: Date.now() });
+      this.inbox.set(agentId, list2.slice(-20));
+      this.onSteer?.(agentId, post.id);
+    }
+  }
+  /** Whether the agent has unread messages from people in the thread it is answering. */
+  hasInbox(agentId) {
+    return (this.inbox.get(agentId)?.length ?? 0) > 0;
+  }
+  /** What people wrote in the agent's thread since its run started; each is handed over once. */
+  async takeInbox(agentId) {
+    const list2 = this.inbox.get(agentId) ?? [];
+    this.inbox.delete(agentId);
+    const out = [];
+    for (const m of list2) {
+      this.delivered.add(m.id);
+      const who = await this.directory.userName(m.userId).catch(() => ({ username: m.userId, displayName: m.userId }));
+      out.push({ from: `${who.displayName} (@${who.username})`, text: m.text, at: new Date(m.at).toISOString() });
+    }
+    if (this.delivered.size > 2e3) this.delivered.delete(this.delivered.values().next().value);
+    return out;
+  }
   /** The thread an agent is answering right now, for posts its run causes (approvals). */
   activeThread(agentId) {
     return this.active.get(agentId) ?? null;
@@ -45644,6 +45698,11 @@ var Bridge = class {
       if (!fromAgent && post.root_id) await this.resetTurns(rootId);
       return;
     }
+    if (this.delivered.has(post.id)) {
+      await member.chat.react(post.id, "white_check_mark").catch(() => {
+      });
+      return;
+    }
     if (!await this.allowAgentTurn(rootId, fromAgent, member, post.channel_id)) return;
     const text2 = stripMention(post.message, member.username);
     const fileIds = this.files ? post.file_ids ?? [] : [];
@@ -45680,7 +45739,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.` + (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. 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}
@@ -45709,11 +45768,13 @@ To send files back with your reply, save them in ${outbox}` : "");
       }
     } catch (err) {
       if (this.active.get(member.agentId) === here) this.active.delete(member.agentId);
+      this.inbox.delete(member.agentId);
       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);
-    const { text: body, choices } = extractChoices(reply ?? "");
+    this.inbox.delete(member.agentId);
+    const { text: body, choices } = extractChoices(absoluteLinks(reply ?? "", this.linkBase));
     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}
@@ -46211,7 +46272,7 @@ var route = (routeKey, method, path3) => ({ routeKey, method, path: path3, auth:
 var manifest = {
   id: "mattermost-bridge",
   apiVersion: 1,
-  version: "0.15.1",
+  version: "0.16.0",
   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",
@@ -46227,6 +46288,7 @@ var manifest = {
     "plugin.state.write",
     "http.outbound",
     "events.subscribe",
+    "events.emit",
     "webhooks.receive",
     "approvals.read",
     "approvals.respond",
@@ -46247,6 +46309,7 @@ var manifest = {
   // checks the caller is an agent and scopes it to that agent's company.
   apiRoutes: [
     route("help", "GET", "/mm/help"),
+    route("inbox", "GET", "/mm/inbox"),
     route("channels", "GET", "/mm/channels"),
     route("channel-posts", "GET", "/mm/channels/:channel/posts"),
     route("thread", "GET", "/mm/posts/:postId/thread"),
@@ -46488,6 +46551,11 @@ var Tenant = class {
     onPosted = (evt) => {
       void bridge.handle(evt);
     };
+    bridge.linkBase = paperclipUrl;
+    bridge.onSteer = (agentId, postId) => {
+      void ctx.events.emit("person-wrote", companyId, { agentId, postId }).catch(() => {
+      });
+    };
     const approvers = parseApprovers(config2.approvers);
     const approvalsChannel = typeof config2.approvalsChannel === "string" ? config2.approvalsChannel.trim() : "";
     const agentName = (agentId) => agentId && roster.roster().byAgentId(agentId)?.agentName || "Paperclip";
@@ -46604,7 +46672,7 @@ var Tenant = class {
     if (!this.actions) return { status: 503, body: { error: `Mattermost is not connected for this company (${this.status})` } };
     return this.actions.handle(agentId, routeKey, params, input2);
   }
-  /** The Agent computer plugin: an agent wants a person in its browser. Posted where the agent is working. */
+  /** The Agent computer plugin: an agent wants a person at its computer. Posted where the agent is working. */
   async computerNeedsPerson(p) {
     if (!this.manager || !this.bots || !this.bridge || !p.agentId) return;
     const poster = this.poster(this.manager, this.bots);
@@ -46612,7 +46680,7 @@ var Tenant = class {
     if (!where) return;
     const link = this.paperclipUrl && p.path ? `${this.paperclipUrl}${p.path}` : null;
     const on = p.url ? ` on ${p.url}` : "";
-    const message2 = p.kind === "password" ? `:key: I ${p.reason ?? "need a password"}${on}. ${link ? `[Enter it here](${link})` : "Enter it from Computers in Paperclip"}: it goes straight into the page, and I never see it.` : `:raising_hand: I need a person in ${p.browser ? `the shared ${p.browser} browser` : "my browser"}${on}: ${p.reason ?? "I am stuck"}. ${link ? `[Take over](${link})` : "Take over from Computers in Paperclip"}, then hand it back; I carry on as soon as you do.`;
+    const message2 = p.kind === "password" ? `:key: I ${p.reason ?? "need a password"}${on}. ${link ? `[Enter it here](${link})` : "Enter it from Computers in Paperclip"}: it goes straight into the page, and I never see it.` : `:raising_hand: I need a person at ${p.computer ?? p.browser ? `the shared ${p.computer ?? p.browser} computer` : "my computer"}${on}: ${p.reason ?? "I am stuck"}. ${link ? `[Take over](${link})` : "Take over from Computers in Paperclip"}, then hand it back; I carry on as soon as you do.`;
     await poster.post(p.agentId, where, message2, { ...FROM_PAPERCLIP });
   }
   async notify(req, notice) {
@@ -46793,7 +46861,14 @@ var plugin = definePlugin({
     if (!tenant) return { status: 503, body: { error: "Mattermost is not set up for your company." } };
     const query = Object.fromEntries(Object.entries(input2.query).map(([k, v]) => [k, Array.isArray(v) ? v[0] : v]));
     const body = input2.body && typeof input2.body === "object" && !Array.isArray(input2.body) ? input2.body : {};
+    if (input2.routeKey === "inbox") {
+      const messages = tenant.bridge ? await tenant.bridge.takeInbox(agentId) : [];
+      return { status: 200, body: { messages, note: messages.length ? "Written to you while you were working. Act on them now: they are not sent to you again." : "Nothing new." } };
+    }
     const res = await tenant.api(agentId, input2.routeKey, input2.params, { ...query, ...body });
+    if (tenant.bridge?.hasInbox(agentId) && res.body && typeof res.body === "object" && !Array.isArray(res.body)) {
+      res.body = { ...res.body, newMessages: await tenant.bridge.takeInbox(agentId) };
+    }
     return { status: res.status, body: res.body };
   },
   async onHealth() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-plugin-mattermost",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "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",