@fezchat/slack 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# Slack → Fez → the same Slack thread
+
+An explicit mention of your custom Slack app by an approved user becomes a task for one selected Fez agent. The bridge acknowledges the task, posts a generic progress message when that agent replies to the request, and returns its correlated terminal success or error to the original Slack thread. Ordinary messages, bot messages, other users/channels/workspaces, and shared Slack Connect channels do not start work. Follow-up app mentions in the same Slack thread stay in the same Fez thread.
+
+## Set up
+
+1. Create a custom app in your Slack workspace using [app-manifest.json](./app-manifest.json). Name its bot `fez`. This is a custom Socket Mode app; this extension does not ship a centrally hosted OAuth service.
+2. In **Basic Information → App-Level Tokens**, generate an `xapp-…` token with **connections:write**. The manifest enables Socket Mode and subscribes to `app_mention` with the bot scopes **app_mentions:read** and **chat:write**. Install the app to your workspace and copy its **Bot User OAuth Token** (`xoxb-…`). Workspace administrator approval may be required by your Slack policy.
+3. Invite `@fez` to the one Slack channel you want to use. Copy the workspace ID (`T…`), channel ID (`C…`, or `G…` for a private channel), and allowed users' member IDs (`U…`/`W…`). An empty allowed-user list never grants access.
+4. In Fez's **Slack** extension settings, enter those IDs, select an existing Fez channel and your attested agent, and paste the two tokens. Enable the bridge and save. Tokens are written to the macOS Keychain service `fez-skill-env`, accounts `fez-slack.bot_token` and `fez-slack.app_token`; the settings panel has no read-token operation. Settings are self-encrypted on the relay.
+5. Keep the local Fez sentinel running. Only its scheduled task opens the socket; opening the TUI or settings panel does not. It checks settings every minute and subscribes to changes. The selected agent must be owner-attested, a workspace member, and unbanned. The owner must also remain a member with permission to submit work.
+6. From an allowed Slack account, mention the app in the configured channel, for example `@fez review the proposed API`. For a follow-up, mention it again inside the original Slack thread. The agent must use Fez's `complete_work` result operation for the final answer to return.
+
+Disable and save to stop the connection and cancel pending exports. Every settings save creates a new revision and cancels old pending work, including changes made while the sentinel was offline; it cannot undo tasks already published to Fez or posts Slack has already accepted. Re-enable after choosing new settings to accept new mentions. Revoke the Slack tokens in Slack to disconnect the app permanently.
+
+## Delivery and boundaries
+
+Incoming envelopes are acknowledged after a durable local journal write, before agent work. Replayed Slack event IDs do not create a second Fez task. Signed Fez requests are persisted before publication, so a retry after an ambiguous publish uses the same Nostr event ID. State and Slack/Fez thread correlations survive restart, scoped to the owner's pubkey, relay, Slack workspace, and Slack channel. Already accepted pending tasks can resume; unseen events older than five minutes or from before the current bridge startup are ignored. No Slack history is fetched or imported. API rate limits honor Slack’s Retry-After cooldown without blocking the sentinel.
+
+The agent's `fez_complete_work.summary` contains the actual answer shown in Slack, not a narration of its activity. Successful replies show that answer directly; errors are prefixed with `Failed:`. Terminal replies include up to eight validated HTTPS artifact URLs, with a note to open Fez for any additional artifacts. Only signature-verified replies from the assigned agent with matching channel, thread, request, recipient and terminal status are exported as results. Progress is a fixed status sentence, not arbitrary conversation text. Imported text has Fez mention syntax neutralized to prevent extra owner-signed summons. Answers use Slack's native Markdown blocks for formatting and code. Messages over Slack's 12,000-character Markdown limit or containing Slack mention syntax retain plain-text rendering; explicit mention controls are escaped. Automatic mentions and link/media unfurls remain disabled.
+
+A local journal cannot make Slack's HTTP acceptance and a filesystem write atomic. Posts use a stable `client_msg_id`; after a connection failure, a Slack reply may be repeated if Slack does not deduplicate the retry. This never creates another Fez task. Run one sentinel for a given binding; state is local to that machine. The journal retains event IDs and correlations indefinitely; remove the extension's local data only when deliberately resetting this history.
+
+This first version binds one Slack workspace/channel to one Fez channel/agent and reads credentials from the macOS keychain. It does not implement Slack OAuth distribution, DMs, history search, arbitrary channel mirroring, or automatic agent selection.
+
+## Development
+
+```sh
+npm run build --prefix packages/fez-slack
+npm run check --prefix packages/fez-slack
+npm exec --prefix packages/fez-evals -- vitest --run --root packages/fez-evals tests/slack-bridge.test.ts tests/slack-gui.test.ts
+```
+
+Tests use mocked Slack transport and local signed Nostr fixtures; they do not connect accounts or send live Slack messages. The Node bundle includes the existing `ws` dependency and the GUI shares the host's React in the isolated settings runtime.
+
+Protocol references: [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode/), [app mentions](https://docs.slack.dev/reference/events/app_mention/), [posting in a thread](https://docs.slack.dev/reference/methods/chat.postMessage/).

package/app-manifest.json

@@ -0,0 +1,15 @@
+{
+  "display_information": {
+    "name": "Fez",
+    "description": "Ask your Fez agent from an approved Slack channel",
+    "background_color": "#252525"
+  },
+  "features": { "bot_user": { "display_name": "fez", "always_online": false } },
+  "oauth_config": { "scopes": { "bot": ["app_mentions:read", "chat:write"] } },
+  "settings": {
+    "socket_mode_enabled": true,
+    "event_subscriptions": { "bot_events": ["app_mention"] },
+    "org_deploy_enabled": false,
+    "token_rotation_enabled": false
+  }
+}

package/dist/gui.js

@@ -0,0 +1,99 @@
+"use strict";
+var __fezExt = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/gui.tsx
+  var gui_exports = {};
+  __export(gui_exports, {
+    default: () => activate
+  });
+
+  // src/config.ts
+  var EMPTY = { revision: "", enabled: false, teamId: "", channelId: "", allowedUsers: [], fezChannel: "", worker: "" };
+  function parseConfig(raw) {
+    const v = raw && typeof raw === "object" ? raw : {};
+    const text = (key) => typeof v[key] === "string" ? v[key].trim() : "";
+    const config = { revision: text("revision").slice(0, 128), enabled: v.enabled === true, teamId: text("teamId"), channelId: text("channelId"), allowedUsers: Array.isArray(v.allowedUsers) ? [...new Set(v.allowedUsers.filter((id) => typeof id === "string" && /^[UW][A-Z0-9]+$/.test(id)))].sort() : [], fezChannel: text("fezChannel"), worker: text("worker") };
+    config.enabled &&= /^T[A-Z0-9]+$/.test(config.teamId) && /^[CG][A-Z0-9]+$/.test(config.channelId) && config.allowedUsers.length > 0 && !!config.fezChannel && /^[a-f0-9]{64}$/.test(config.worker);
+    return config;
+  }
+
+  // src/gui.tsx
+  function activate(api) {
+    const { client, secrets } = api, h = api.React.createElement;
+    const { useState, useEffect } = api.React;
+    if (!client || typeof client.agents !== "function" || typeof client.listChannels !== "function" || typeof client.extensionConfig !== "function" || typeof client.saveExtensionConfig !== "function") throw new Error("Update Fez to configure Slack channel and agent access");
+    const host = client;
+    function Panel() {
+      const [config, setConfig] = useState(EMPTY);
+      const [users, setUsers] = useState("");
+      const [channels, setChannels] = useState([]);
+      const [agents, setAgents] = useState([]);
+      const [bot, setBot] = useState(""), [app, setApp] = useState("");
+      const [stored, setStored] = useState(false), [loaded, setLoaded] = useState(false), [busy, setBusy] = useState(false);
+      const [notice, setNotice] = useState(""), [error, setError] = useState("");
+      useEffect(() => {
+        let active = true;
+        void Promise.all([host.extensionConfig("fez-slack"), host.listChannels(), secrets.has("bot_token"), secrets.has("app_token")]).then(([saved, available, hasBot, hasApp]) => {
+          if (!active) return;
+          const next = parseConfig(saved);
+          setConfig(next);
+          setUsers(next.allowedUsers.join(", "));
+          setChannels(available.filter((channel) => !channel.archived));
+          setAgents([...host.agents()]);
+          setStored(hasBot && hasApp);
+          setLoaded(true);
+        }).catch(() => {
+          if (active) setError("Could not load Slack settings. Check relay and keychain access.");
+        });
+        return () => {
+          active = false;
+        };
+      }, []);
+      async function save() {
+        setBusy(true);
+        setError("");
+        setNotice("");
+        try {
+          const allowedUsers = users.split(/[\s,]+/).filter(Boolean);
+          const next = parseConfig({ ...config, allowedUsers, revision: crypto.randomUUID() });
+          if (config.enabled && (!next.enabled || allowedUsers.some((user) => !/^[UW][A-Z0-9]+$/.test(user)) || !channels.some((channel) => channel.id === next.fezChannel) || !agents.some(([key]) => key === next.worker))) throw new Error("settings");
+          if (bot && !bot.trim().startsWith("xoxb-") || app && !app.trim().startsWith("xapp-")) throw new Error("tokens");
+          if (config.enabled && !stored && (!bot || !app)) throw new Error("tokens");
+          if (bot) await secrets.set("bot_token", bot.trim());
+          if (app) await secrets.set("app_token", app.trim());
+          await host.saveExtensionConfig("fez-slack", next);
+          if (bot && app) setStored(true);
+          setBot("");
+          setApp("");
+          setConfig(next);
+          setNotice(next.enabled ? "Saved. The local Fez sentinel connects and checks access within one minute." : "Saved. Slack bridge disabled.");
+        } catch {
+          setError("Could not save. Check IDs, allowed users, selected channel and agent, tokens, and relay access.");
+        } finally {
+          setBusy(false);
+        }
+      }
+      const field = (key, title, placeholder) => /* @__PURE__ */ h("label", { style: { display: "grid", gap: 4 } }, title, /* @__PURE__ */ h("input", { value: config[key], placeholder, onChange: (event) => setConfig((previous) => ({ ...previous, [key]: event.target.value })) }));
+      return /* @__PURE__ */ h("section", { style: { display: "grid", gap: 12, maxWidth: 560 } }, /* @__PURE__ */ h("p", null, "Approved Slack users can mention your Fez app in one channel to ask the selected agent for work. Progress and results return to that Slack thread."), /* @__PURE__ */ h("fieldset", { disabled: !loaded || busy, style: { display: "grid", gap: 12, border: 0, padding: 0 } }, field("teamId", "Slack workspace ID", "T\u2026"), field("channelId", "Slack channel ID", "C\u2026"), /* @__PURE__ */ h("label", { style: { display: "grid", gap: 4 } }, "Allowed Slack user IDs", /* @__PURE__ */ h("input", { value: users, placeholder: "U\u2026, U\u2026", onChange: (event) => setUsers(event.target.value) })), /* @__PURE__ */ h("label", { style: { display: "grid", gap: 4 } }, "Fez channel", /* @__PURE__ */ h("select", { value: config.fezChannel, onChange: (event) => setConfig((previous) => ({ ...previous, fezChannel: event.target.value })) }, /* @__PURE__ */ h("option", { value: "" }, "Choose channel"), channels.map((channel) => /* @__PURE__ */ h("option", { key: channel.id, value: channel.id }, channel.name)))), /* @__PURE__ */ h("label", { style: { display: "grid", gap: 4 } }, "Fez agent", /* @__PURE__ */ h("select", { value: config.worker, onChange: (event) => setConfig((previous) => ({ ...previous, worker: event.target.value })) }, /* @__PURE__ */ h("option", { value: "" }, "Choose agent"), agents.map(([key, name]) => /* @__PURE__ */ h("option", { key, value: key }, name)))), /* @__PURE__ */ h("label", { style: { display: "grid", gap: 4 } }, "Bot token", /* @__PURE__ */ h("input", { type: "password", autoComplete: "off", value: bot, placeholder: stored ? "Stored; leave blank to keep" : "xoxb-\u2026", onChange: (event) => setBot(event.target.value) })), /* @__PURE__ */ h("label", { style: { display: "grid", gap: 4 } }, "App token", /* @__PURE__ */ h("input", { type: "password", autoComplete: "off", value: app, placeholder: stored ? "Stored; leave blank to keep" : "xapp-\u2026", onChange: (event) => setApp(event.target.value) })), /* @__PURE__ */ h("label", null, /* @__PURE__ */ h("input", { type: "checkbox", checked: config.enabled, onChange: (event) => setConfig((previous) => ({ ...previous, enabled: event.target.checked })) }), " Enable Slack bridge"), /* @__PURE__ */ h("button", { onClick: () => void save() }, busy ? "Saving\u2026" : "Save Slack settings")), /* @__PURE__ */ h("small", null, "Create a custom Slack app from this extension's app-manifest.json, enable Socket Mode, install it, and invite it to the selected channel. Tokens are stored in your local keychain and cannot be read back into this panel."), error && /* @__PURE__ */ h("p", { role: "alert" }, error), notice && /* @__PURE__ */ h("p", { role: "status" }, notice));
+    }
+    api.registerSettingsPanel("Slack", () => h(Panel), { source: "slack" });
+  }
+  return __toCommonJS(gui_exports);
+})();