paperclip-plugin-mattermost 0.13.0 → 0.15.0

package/README.md

@@ -13,10 +13,11 @@ Your [Paperclip](https://github.com/paperclipai/paperclip) agents as Mattermost
   - **Confirmations and suggested tasks** get Accept / Reject buttons.
   - **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. `GET /api/plugins/mattermost-bridge/api/mm/help` tells an agent how.
+- **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.
 - **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.
 - **One install, many companies.** Each Paperclip company connects its own Mattermost, with its own settings, bots and state.
 
 ## Requirements
@@ -82,7 +83,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.13.0 -m v0.13.0 && git push origin main v0.13.0
+git tag -a v0.15.0 -m v0.15.0 && git push origin main v0.15.0
 ```
 
 GitHub Actions builds, tests and publishes to npm through npm trusted publishing, so no npm token is involved.

package/dist/manifest.js

@@ -1,9 +1,80 @@
+// src/help.ts
+var HELP = `# Working in Mattermost
+
+You have your own Mattermost account (a bot). Everything below runs as you, in your company's
+Mattermost, and you can only see and use channels you are a member of. Use it whenever you need
+to reach a person or another agent in Mattermost, including from a task or a scheduled run: to
+ping someone, DM them, or post in a channel. Call it with your Paperclip API credentials:
+
+  B="\${PAPERCLIP_API_URL%/}"; B="\${B%/api}/api/plugins/mattermost-bridge/api"
+  curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" "$B/mm/channels"
+  curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" -H "content-type: application/json" \\
+    -d '{"person":"username","text":"..."}' "$B/mm/dm"
+
+Answers are JSON. A 202 with "waiting_for_approval" means a person has been asked to approve;
+tell whoever you are working with and carry on. A 403 says why something is not allowed.
+
+## 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".
+- **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.
+- **Hand work to another agent by mentioning it** (@cto) in a channel or thread it is in; invite it
+  first if it is not. Give it the context it needs in that message. It replies in the thread.
+  Mention an agent only when you want it to act: every mention starts it.
+- **Say something before going quiet.** If an answer will take a while, post one line ("On it,
+  checking what shipped this morning") and then do the work.
+- Do not write @channel, @all or @here unless everyone in the channel must be notified: it needs
+  approval.
+
+## Calls
+
+Reading (GET):
+- /mm/channels                              channels you are in
+- /mm/channels/{channel}/posts?limit=30     recent posts in a channel (oldest first)
+- /mm/posts/{postId}/thread                 a whole thread
+- /mm/channels/{channel}/members            who is in a channel (people and agents)
+- /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
+
+Talking (POST, JSON body):
+- /mm/post      {"channel": "...", "text": "...", "threadId": "optional post id to reply to"}
+- /mm/react     {"postId": "...", "emoji": "white_check_mark"}
+- /mm/dm        {"person": "username", "text": "..."}   only people allowed to talk to you
+
+Channels (POST, JSON body):
+- /mm/channels                   {"name": "inc checkout 5xx", "purpose": "...", "people": ["username"],
+                                  "agents": ["cto"], "taskId": "BAD-123 or task id", "private": true}
+  Private by default. A public channel needs approval. With taskId, the channel is tied to the
+  task: its comments and status show up there, and it is archived when the task closes.
+- /mm/channels/{channel}/invite  {"people": [...], "agents": [...]}   free on channels you created
+- /mm/channels/{channel}/update  {"purpose": "...", "header": "...", "name": "..."}  yours only
+- /mm/channels/{channel}/archive {}                                   yours only
+
+{channel} is a channel's id, its URL name (inc-checkout-5xx) or its display name.
+`;
+var SKILL = `---
+name: mattermost
+description: >
+  Use to talk to people and agents in Mattermost as your own bot: DM someone, post or reply in
+  a channel, read and search channels you are in, hand work to another agent by mentioning it,
+  and open a work channel for an investigation, incident or project tied to a Paperclip task.
+---
+
+${HELP}`;
+
 // src/manifest.ts
 var route = (routeKey, method, path) => ({ routeKey, method, path, auth: "agent", capability: "api.routes.register" });
 var manifest = {
   id: "mattermost-bridge",
   apiVersion: 1,
-  version: "0.13.0",
+  version: "0.15.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",
@@ -29,7 +100,8 @@ var manifest = {
     "issue.comments.create",
     "issue.comments.create_human_attributed",
     "issue.comments.read",
-    "api.routes.register"
+    "api.routes.register",
+    "skills.managed"
   ],
   entrypoints: { worker: "./dist/worker.js", ui: "./dist/ui" },
   // Replaces the generated form: approvers picked from members, URL detected and checked.
@@ -53,6 +125,8 @@ var manifest = {
     route("update-channel", "POST", "/mm/channels/:channel/update"),
     route("archive", "POST", "/mm/channels/:channel/archive")
   ],
+  // Installed in each company's skill library; the settings page adds it to every agent with a bot.
+  skills: [{ skillKey: "mattermost", displayName: "Mattermost", slug: "mattermost", description: "Talk to people and agents in Mattermost as your own bot.", markdown: SKILL }],
   webhooks: [
     { endpointKey: "actions", displayName: "Mattermost buttons", description: "Approve / Reject clicks on approval posts. Every click carries a signature the plugin checks." }
   ],

package/dist/ui/index.js

@@ -203,6 +203,8 @@ function SettingsPage({ context }) {
   const [saved, setSaved] = useState(false);
   const [check, setCheck] = useState(null);
   const verify = usePluginAction("verify-url");
+  const skill = usePluginAction("skill");
+  const [skillNote, setSkillNote] = useState(null);
   useEffect(() => {
     if (!companyId) return;
     Promise.all([
@@ -264,8 +266,22 @@ function SettingsPage({ context }) {
     else next.add(id);
     setSelected(next);
   };
+  async function giveSkill(targets) {
+    try {
+      const { key } = await skill({ companyId });
+      if (!key) return "The Mattermost skill is not installed yet; save again in a minute.";
+      const failed = [];
+      for (const a of targets) {
+        await api(`/api/agents/${a.id}/skills/sync`, { method: "POST", body: JSON.stringify({ mode: "add", desiredSkills: [key] }) }).catch(() => failed.push(a.name));
+      }
+      return failed.length ? `Could not give the Mattermost skill to ${failed.join(", ")}; add it on their Skills tab.` : null;
+    } catch (e) {
+      return `Could not give agents the Mattermost skill: ${String(e?.message ?? e).slice(0, 200)}`;
+    }
+  }
   async function save() {
     setSaveError(null);
+    setSkillNote(null);
     const errors = validate(config);
     if (agentsMode === "selected" && !pickedAgents.size) errors.agents = "Tick at least one agent, or choose All agents.";
     if (access === "selected" && !grants.size) errors.access = "Tick at least one person, or choose Everyone.";
@@ -283,6 +299,7 @@ function SettingsPage({ context }) {
       await api(`/api/plugins/${PLUGIN}/config`, { method: "POST", body: JSON.stringify({ companyId, configJson: next }) });
       setConfig(next);
       setSaved(true);
+      setSkillNote(await giveSkill(agentsMode === "selected" ? agents.filter((a) => pickedAgents.has(a.id)) : agents));
     } catch (e) {
       setSaveError(saveErrorText(String(e?.message ?? e)));
     } finally {
@@ -334,7 +351,7 @@ function SettingsPage({ context }) {
         onChange: (e) => set({ agentTurnLimit: Math.min(100, Math.max(1, Math.round(Number(e.target.value) || 10))) })
       }
     ) }),
-    /* @__PURE__ */ jsxs(Field, { label: "Agents in Mattermost", error: fieldErrors.agents, help: "Each agent shown here gets its own Mattermost bot. Unticking an agent switches its bot off but keeps it, with its history, for when you tick it again.", children: [
+    /* @__PURE__ */ jsxs(Field, { label: "Agents in Mattermost", error: fieldErrors.agents, help: "Each agent shown here gets its own Mattermost bot, and saving gives it the Mattermost skill so it can message people from any run. Unticking an agent switches its bot off but keeps it, with its history, for when you tick it again.", children: [
       /* @__PURE__ */ jsx(
         Modes,
         {
@@ -380,7 +397,8 @@ function SettingsPage({ context }) {
     /* @__PURE__ */ jsxs("div", { style: s.row, children: [
       /* @__PURE__ */ jsx("button", { style: s.primary, onClick: save, disabled: saving, children: saving ? "Saving\u2026" : "Save" }),
       saved ? /* @__PURE__ */ jsx("span", { style: s.ok, children: "Saved" }) : null,
-      saveError ? /* @__PURE__ */ jsx("span", { style: s.bad, children: saveError }) : null
+      saveError ? /* @__PURE__ */ jsx("span", { style: s.bad, children: saveError }) : null,
+      skillNote ? /* @__PURE__ */ jsx("span", { style: s.bad, children: skillNote }) : null
     ] })
   ] });
 }

package/dist/worker.js

@@ -45426,10 +45426,14 @@ _~${name} is archived._`
 var HELP = `# Working in Mattermost
 
 You have your own Mattermost account (a bot). Everything below runs as you, in your company's
-Mattermost, and you can only see and use channels you are a member of. Call these with your
-Paperclip API credentials, the same way you call the Paperclip API:
+Mattermost, and you can only see and use channels you are a member of. Use it whenever you need
+to reach a person or another agent in Mattermost, including from a task or a scheduled run: to
+ping someone, DM them, or post in a channel. Call it with your Paperclip API credentials:
 
-  <your Paperclip API URL>/api/plugins/mattermost-bridge/api/mm/...
+  B="\${PAPERCLIP_API_URL%/}"; B="\${B%/api}/api/plugins/mattermost-bridge/api"
+  curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" "$B/mm/channels"
+  curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" -H "content-type: application/json" \\
+    -d '{"person":"username","text":"..."}' "$B/mm/dm"
 
 Answers are JSON. A 202 with "waiting_for_approval" means a person has been asked to approve;
 tell whoever you are working with and carry on. A 403 says why something is not allowed.
@@ -45479,6 +45483,15 @@ Channels (POST, JSON body):
 
 {channel} is a channel's id, its URL name (inc-checkout-5xx) or its display name.
 `;
+var SKILL = `---
+name: mattermost
+description: >
+  Use to talk to people and agents in Mattermost as your own bot: DM someone, post or reply in
+  a channel, read and search channels you are in, hand work to another agent by mentioning it,
+  and open a work channel for an investigation, incident or project tied to a Paperclip task.
+---
+
+${HELP}`;
 
 // src/worker.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -46198,7 +46211,7 @@ var route = (routeKey, method, path3) => ({ routeKey, method, path: path3, auth:
 var manifest = {
   id: "mattermost-bridge",
   apiVersion: 1,
-  version: "0.13.0",
+  version: "0.15.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",
@@ -46224,7 +46237,8 @@ var manifest = {
     "issue.comments.create",
     "issue.comments.create_human_attributed",
     "issue.comments.read",
-    "api.routes.register"
+    "api.routes.register",
+    "skills.managed"
   ],
   entrypoints: { worker: "./dist/worker.js", ui: "./dist/ui" },
   // Replaces the generated form: approvers picked from members, URL detected and checked.
@@ -46248,6 +46262,8 @@ var manifest = {
     route("update-channel", "POST", "/mm/channels/:channel/update"),
     route("archive", "POST", "/mm/channels/:channel/archive")
   ],
+  // Installed in each company's skill library; the settings page adds it to every agent with a bot.
+  skills: [{ skillKey: "mattermost", displayName: "Mattermost", slug: "mattermost", description: "Talk to people and agents in Mattermost as your own bot.", markdown: SKILL }],
   webhooks: [
     { endpointKey: "actions", displayName: "Mattermost buttons", description: "Approve / Reject clicks on approval posts. Every click carries a signature the plugin checks." }
   ],
@@ -46350,6 +46366,8 @@ var Tenant = class {
   work = null;
   key = "";
   approvers = /* @__PURE__ */ new Map();
+  paperclipUrl = "";
+  approvalsChannel = "";
   timers = [];
   agents() {
     const companyId = this.companyId;
@@ -46539,7 +46557,7 @@ var Tenant = class {
       task: async (issueId) => await ctx.issues.get(issueId, companyId),
       comments: async (issueId) => (await ctx.issues.listComments(issueId, companyId)).map((c) => ({ id: c.id, body: c.body, authorAgentId: c.authorAgentId }))
     });
-    Object.assign(this, { manager, bots: roster, bridge, approvals, cards, actions, work, key, approvers });
+    Object.assign(this, { manager, bots: roster, bridge, approvals, cards, actions, work, key, approvers, paperclipUrl, approvalsChannel });
     this.status = `connecting to ${url2} as @${manager.botUsername}`;
     detached(() => {
       manager.connect(onPosted);
@@ -46551,6 +46569,7 @@ var Tenant = class {
       });
       void sync();
       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) {
         const poll = () => cards.poll().catch((err) => warn("decision cards poll failed", { err: errText(err) }));
         this.timers.push(setTimeout(poll, 2e4), setInterval(poll, CARDS_EVERY_MS));
@@ -46585,6 +46604,17 @@ 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. */
+  async computerNeedsPerson(p) {
+    if (!this.manager || !this.bots || !this.bridge || !p.agentId) return;
+    const poster = this.poster(this.manager, this.bots);
+    const where = this.bridge.activeThread(p.agentId) ?? (this.approvalsChannel ? await poster.channel(this.approvalsChannel).then((id) => id ? { channelId: id, rootId: "" } : null) : null);
+    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 my browser${on}: ${p.reason ?? "I am stuck"}. ${link ? `[Take over](${link})` : "Take over from Computers in Paperclip"}, then hand it back.`;
+    await poster.post(p.agentId, where, message2, { ...FROM_PAPERCLIP });
+  }
   async notify(req, notice) {
     if (notice && req.user_id && req.channel_id) {
       await this.manager?.request("POST", "/posts/ephemeral", { user_id: req.user_id, post: { channel_id: req.channel_id, message: notice } }).catch(() => {
@@ -46675,6 +46705,11 @@ function configure(companyId, config2) {
   });
   return run;
 }
+async function ensureSkill(companyId) {
+  let r = await ctx.skills.managed.reconcile("mattermost", companyId);
+  if (r.skill && r.defaultDrift?.changedFiles.length) r = await ctx.skills.managed.reset("mattermost", companyId);
+  return r.skill?.key ?? null;
+}
 async function saveBoot(companyId, config2) {
   const all = await ctx.state.get(BOOT) ?? {};
   all[companyId] = config2;
@@ -46704,6 +46739,10 @@ var plugin = definePlugin({
       }
       return { detectedUrl: await detectPublicUrl(), connected: Boolean(manager), status: tenant?.status ?? null, versionNote, channels, accounts };
     });
+    ctx.actions.register("skill", async (params) => {
+      if (typeof params.companyId !== "string") throw new Error("companyId is required");
+      return { key: await ensureSkill(params.companyId) };
+    });
     ctx.actions.register("verify-url", async (params) => verifyUrl(String(params.url ?? ""), PLUGIN_KEY));
     const quietly = (what, fn) => fn().catch((err) => ctx.logger.warn(what, { err: errText(err) }));
     ctx.events.on("approval.created", (e) => quietly("could not post approval", async () => {
@@ -46716,6 +46755,9 @@ var plugin = definePlugin({
     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);
     }));
+    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 ?? {});
+    }));
     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.13.0",
+  "version": "0.15.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",