tinybeeai 0.0.0-stage → 0.16.1

package/docs/SLACK.md

@@ -0,0 +1,80 @@
+# Slack
+
+With Slack connected, people ask a dot questions by mentioning the bot, and dots post outage and digest notices to their channel. localdost connects over Socket Mode, so Slack needs no public URL and no webhook.
+
+## Connect from the app
+
+Open Setup and press **Connect** on the Slack row. The flow has four steps:
+
+1. Copy or download the app manifest. It sets the bot name, the scopes, the `app_mention` event, and Socket Mode.
+2. Open Slack apps from the flow, create an app from the manifest, and install it to your workspace.
+3. In OAuth and Permissions, copy the Bot User OAuth Token (`xoxb-...`).
+4. In Basic Information, App-Level Tokens, generate a token with the `connections:write` scope (`xapp-...`).
+
+Paste both tokens, press **Test**, then **Connect**, and pick the channel for notices. Slack connects at once, with no restart. Invite the bot to each channel where it should answer or post: `/invite @<bot name>`.
+
+## Create the Slack app by hand
+
+Skip this section when you used the manifest in Setup.
+
+1. Create an app at api.slack.com/apps, from scratch, in your workspace.
+2. Under Socket Mode, turn Socket Mode on. Create an app-level token with the `connections:write` scope. This is `SLACK_APP_TOKEN` (`xapp-...`).
+3. Under OAuth and Permissions, add the bot scopes `app_mentions:read` and `chat:write`.
+4. Under Event Subscriptions, turn events on and subscribe to the bot event `app_mention`.
+   Under Interactivity and Shortcuts, turn interactivity on. Socket Mode carries the Approve and Reject buttons, so no request URL is needed.
+5. Install the app to the workspace. The Bot User OAuth Token is `SLACK_BOT_TOKEN` (`xoxb-...`).
+   An app made before this step existed shows Approve and Reject, but Slack refuses the click until you open api.slack.com/apps, pick the app, and turn on Interactivity and Shortcuts. Socket Mode needs no request URL. Until then, decide drafts in the localdost Inbox.
+6. Invite the bot to each channel where it should answer or post: `/invite @<bot name>`.
+
+Paste both tokens in Setup as above. Or export them in the shell that runs localdost, or reference them from `.env.localdost` with `${env:SLACK_APP_TOKEN}` and `${env:SLACK_BOT_TOKEN}`, and restart the server. The environment wins over tokens saved in the app. The log prints "slack: connected in Socket Mode", and Setup shows Slack as ready.
+
+## Who may ask
+
+Without an allowlist, anyone in the installed workspace can ask the dots, and the server logs a warning once. Set one or both lists to narrow it:
+
+| Variable | Value |
+|---|---|
+| `SLACK_ALLOWED_TEAM` | Comma list of workspace ids, for example `T0123ABCD` |
+| `SLACK_ALLOWED_USERS` | Comma list of user ids, for example `U0123ABCD,U0456EFGH`. Only these users, and each dot's own Slack user, can press Approve or Reject on a draft in Slack; with no list, anyone may mention the dot but nobody can decide drafts from Slack. |
+
+A mention from outside the lists gets no answer, and the server logs it.
+
+## Mentions
+
+The bot answers in the thread of the mention. It picks the dot in this order:
+
+1. A dot whose name appears in the message. The longest matching name wins.
+2. The dot that answered earlier in the same thread.
+3. The dot whose `slackChannel` matches the channel.
+
+With no match, the answer comes from localdost without a dot. The reply uses the same chat as the app, with the same tools: list runs, read a run, list reviewed tickets, rerun tests, read and add memory, check probe status, and the dot's MCP tools.
+
+## Links in answers and updates
+
+A link in a Slack message is clickable only when the server built its exact address. This holds for a chat answer, an update, and the error reply of a mention.
+
+- **Answers.** The server writes the links of a PR, an issue, a commit, a ticket, and a run itself (titled references). Those addresses, and the app links the answer carries from tools built by code (the release call, the designed test cases), are the live links of that turn. The designed test cases link is an app page; in Slack it becomes the whole address under `LOCALDOST_PUBLIC_URL`, and with no public address the answer shows no link for it. Everything else the answer holds shows as text: a Markdown link `[x](https://...)` shows `x` and the address in a code span, and so do a bare address, a Slack `<url|x>` or `<url>` link, a `www.` address, a host name with no scheme (`evil.com/login`, `evil.studio`, `login.bank`: any dotted name that does not end like a file name such as `app.ts` or `package.json`, with or without a path, since Slack links those by itself), a `mailto:` link, and an e-mail address. Slack never turns the inside of a code span into a link. A tool result grants no trust: a tool passes along text that a PR author or a ticket writer typed. An address with `?next=...`, a fragment, or a longer path added to a trusted one is another address and is not trusted.
+- **Updates.** An update joins server links with titles and errors of PRs, tickets, and tests. A link in it stays live when its address is a page of the app under `LOCALDOST_PUBLIC_URL` that the app builds into its messages, with only the settings the app writes for that page (a run with `?section=`, the trace with `?dot=` and `?milestone=`), or the exact address of a PR, an issue, or a commit of a repo one of the dots holds, or of a Jira ticket of a tracker one of them uses. Any other link shows as text, among them a page that is not listed, `?next=`, `#/dots?new=1&repo=...` (it fills the new dot form) and `#/setup?error=...` (it shows the text in the address). In the app chat the same title shows each of these as label and address, and a path such as `/\evil.com/login`, which a browser reads as another site, shows its address too.
+- **Brackets.** The Slack text of an update swaps `[` and `]` outside of links for the full-width look-alikes `［` and `］`, so text from a PR title cannot start a link. The phone alert, the title of an update in the app, and the digest rows keep the brackets as written. The swap changes nothing when it runs twice on the same text.
+- **Size limit.** A message over the Slack limit is cut where no code span or link is open, so no piece of an address stays outside a span. A code block of the model keeps its own three backticks at each end and loses any backtick inside it, so the cut never reads a stray one as the end of a span.
+- **In the app.** The chat in the app shows the address next to the label for a link in the title or body of an update unless the address is one the server built, so a label cannot hide where a link goes.
+
+## Notices
+
+Set a dot's `slackChannel` (in the dot's settings, or `PATCH /api/dots/:id`) to post its outage and digest notices there. Each post is an outward action of kind `slack_post` and passes the rules gate. The gate lets a Slack post go out on its own only when its producer built it from fixed text and marked it as templated. Any other Slack text can carry model output shaped by ticket, PR, or log content, so the gate treats `act` as `ask` for it. Outage and digest notices include the model's summary today, so under the default rule each one waits in the Inbox until you approve it.
+
+Without Slack tokens, `slack_post` actions go to the outbox, like the other integrations in demo mode.
+
+## Updates
+
+A running server sends each dot's updates through one router (`src/updates`). It reads run, approval, defect, probe, and queue events and gives each update a level:
+
+- Right away: a decision waiting for approval, a critical or high bug, prod down or back up, and blocked work. A decision carries Approve and Reject buttons; pressing one follows the same allowlist as mentions.
+- In the thread: work someone asked for in Slack replies in that thread. The suspected cause of an outage replies under the prod down post.
+- In the digest: the rest, every few hours (`LOCALDOST_UPDATE_DIGEST_HOURS`, default 3), plus a morning note at the end of quiet hours (08:00 without them).
+
+A passing run nobody asked about sends no message. Each update has one key, so it reaches each channel once. Updates go to the dot's `slackChannel`, or to one member as a direct message when the dot's Slack updates setting says so, or nowhere. Every post is a templated `slack_post` and passes the rules gate. Settings > Updates sets each person's level (Everything, Only what needs me, Off) and quiet hours, which hold the phone and Slack direct messages. `LOCALDOST_UPDATES=0` turns the router off and brings back the older notices.
+
+## Data
+
+Chat answers and notices go to Slack. localdost masks common secret shapes in templated notices before it sends them, and an auto-review pass reads each Slack draft before it goes out.