@open-everywhere/provider-slack 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your Exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tommy Long
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,21 @@
+Open Everywhere
+Copyright 2026 Tommy Long
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+---
+
+Built on Vercel Eve (https://github.com/vercel/eve), licensed under the
+Apache License, Version 2.0.
+
+@open-everywhere/core also ships a patch that modifies Vercel Eve (the file in
+its patches/ directory), with the oe-eve-patch command that applies it to a
+consumer's own installed copy. The patch is licensed under the Apache License,
+Version 2.0. No modified Vercel Eve files are distributed.
+
+---
+
+Open Everywhere is an independent, open-source project. It is NOT affiliated
+with, endorsed by, or sponsored by Anthropic. "Claude", "Claude Code", and
+"Claude Tag" are referenced only to describe the prior art Open Everywhere is
+inspired by, and are trademarks of their respective owner.

package/README.md

@@ -0,0 +1,47 @@
+# @open-everywhere/provider-slack
+
+Slack channel and DM surfaces for Open Everywhere.
+
+Part of [Open Everywhere](https://github.com/open-everywhere/open-everywhere) — an open, self-hostable autonomous teammate you tag where your
+team works. This package is the Slack provider. It supplies the identity mapper, the capability manifest, the post arm, the wake-origin codec, the channel and DM read adapter, the reaction surface, the approval and connector cards, and the slash commands.
+
+`@open-everywhere/core` owns the runtime — access and approvals, identity, memory, spend, the
+audit chain. This package holds the Slack half. The boundary between them is a vendor-coupling
+one, and `packages/core/scripts/boundary-test.ts` checks it per provider: it names one or more
+vendor fingerprint strings, asserts that **at least one** of them appears under this package, and
+asserts that **every** one of them is absent from `packages/core/agent`. For Slack those strings are
+`SLACK_SIGNING_SECRET` and `SLACK_BOT_TOKEN`. Core's registries refuse a provider the deployment has not selected.
+
+## Install
+
+```sh
+npm i @open-everywhere/core @open-everywhere/provider-slack eve@0.54.3
+npx oe-eve-patch
+```
+
+**Both commands are required.** Core refuses to boot on an unpatched `eve`. A registry `eve` carries
+no patch, so `npx oe-eve-patch` applies the copy `@open-everywhere/core` ships.
+
+`eve` is a peer dependency, pinned to the exact version above, which is the pin
+`@open-everywhere/core` declares as `peerDependencies.eve`. `undici` is a dependency. Node 24 or newer.
+
+## Use
+
+One call registers the bundle:
+
+```ts
+import { registerSlackProvider } from "@open-everywhere/provider-slack/agent/register.js";
+
+registerSlackProvider();
+```
+
+Credentials, the webhook and the Slack app setup are in the runbook below.
+
+## Docs
+
+- [Slack runbook](https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/surfaces/slack.md)
+- [Documentation index](https://github.com/open-everywhere/open-everywhere/blob/main/docs/README.md)
+
+## Licence
+
+Apache 2.0. The tarball carries `LICENSE` and `NOTICE`.

package/agent/access/slack-attachment-fetch.ts

@@ -0,0 +1,168 @@
+// Trusted-provenance Slack attachment fetch — the ONE seam that attaches the Slack BOT TOKEN to
+// a file download, and ONLY ever sends it to a validated Slack file host.
+//
+// WHY THIS EXISTS, DISTINCT FROM oeFetch (access/host-egress.ts). `oeFetch` is the guard for a
+// MODEL-SUPPLIED URL: it sends NO credentials, precisely because a model-chosen destination must
+// never receive one (P0-1, the EXFIL leg). But a Slack image sits behind `url_private`, which
+// 302/403s without the bot token — so pasted Slack screenshots (the main describe_image use case)
+// are unfetchable credential-less. This helper closes that gap under two hard constraints that
+// oeFetch's blanket "send nothing" rule made moot there:
+//
+//   1. TRUSTED PROVENANCE — the URL is NOT a tool argument. It arrives as an already-resolved
+//      record whose `urlPrivate` came from a Slack event's `files[].url_private`
+//      (channels/slack-attachments.ts, populated only by parseMessageEvent). describe_image
+//      resolves a model-named FILE ID through that registry and passes the resulting record here.
+//      A model-chosen URL string can never reach this function — the signature takes a record, not
+//      a raw URL, and describe_image only ever builds that record from the registry.
+//
+//   2. HOST-PINNED CREDENTIAL — the bot token rides ONLY to a Slack file host (files.slack.com).
+//      Any other host is refused and the token is NEVER sent (nor is the host even resolved). So
+//      even if provenance were somehow subverted, the credential cannot leak to an attacker host.
+//
+// Plus the SAME SSRF posture as oeFetch: resolve-then-check-then-PIN (reusing
+// `assertSafeFetchUrl`) so even files.slack.com gets the DNS-rebind check — a poisoned resolver
+// pointing files.slack.com at an internal IP is refused — and `redirect:"error"` so a 3xx can't
+// bounce the token to another host.
+//
+// ONE TIER-DEPENDENT CAVEAT (OPE-322). `assertSafeFetchUrl` now routes through the forward proxy
+// when `*_PROXY` is set (the self-host/docker stack), because the app container has no WAN route at
+// all — without it this download simply fails there. On that path the IP-pin cannot operate (the
+// proxy resolves the CONNECT target itself) and anti-rebind is delegated to the proxy's default-deny
+// ACL; the returned `antiRebind` says which held, and this seam records it on the allow row. The
+// HOST-PIN above — the property that actually protects the token — is unaffected, and it is decided
+// before any dispatch. The token does traverse the operator's own proxy: Tier A tunnels it
+// undecrypted (CONNECT), Tier B decrypts with the operator's CA, which is what Tier B is for.
+
+import {
+  assertSafeFetchUrl,
+  auditToolAction,
+  hostCallAuditFields,
+  type BindableContext,
+  type EgressDispatch,
+  type EgressRefusalCause,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+// THE CREDENTIAL'S IDENTITY, FOR THE AUDIT ROW (OPE-1547) — the ref NAME, never the value. This is
+// the one host-side seam that attaches a credential, so before this ticket it was the one place
+// where a plane both saw the call and knew whose credential rode it, and said neither on the row.
+// The shared cross-plane row shape (core access/egress.ts) is what it fills now.
+const SLACK_BOT_TOKEN_REF = "SLACK_BOT_TOKEN";
+
+/** Every attachment download is a GET — Slack's `url_private` is a file read. */
+const ATTACHMENT_VERB = "GET";
+
+// Slack serves `url_private` downloads from `files.slack.com` (Enterprise Grid included — same
+// host). The bot token is sent to NO other host. If Slack ever documents a second legitimate file
+// host, add it here — the pin is a closed set on purpose (a `*.slack.com` wildcard would let the
+// API host `slack.com` receive the token, which it must not).
+const SLACK_FILE_HOSTS: ReadonlySet<string> = new Set(["files.slack.com"]);
+
+/** Is `hostname` a Slack file host the bot token may be sent to? Exact-match, case-insensitive. */
+function isSlackFileHost(hostname: string): boolean {
+  return SLACK_FILE_HOSTS.has(hostname.toLowerCase());
+}
+
+/** A resolved, TRUSTED attachment reference: its `urlPrivate` came from a Slack event's
+ *  `files[].url_private`, never a model-supplied string (see the file header). */
+export interface TrustedSlackAttachment {
+  readonly urlPrivate: string;
+  /** Slack file id — for the audit trail only; the fetch decision is the URL's host. */
+  readonly id?: string;
+}
+
+/**
+ * Download a Slack attachment with the bot token, host-pinned to a Slack file host and SSRF-guarded.
+ * Refuses (and never sends the token) if the URL is not HTTPS on a Slack file host. Returns the raw
+ * Response — the caller (describe_image) reads the bytes.
+ */
+export async function fetchSlackAttachment(ctx: BindableContext, ref: TrustedSlackAttachment): Promise<Response> {
+  let url: URL;
+  try {
+    url = new URL(ref.urlPrivate);
+  } catch {
+    throw new Error("describe_image: the Slack attachment URL is not a valid URL.");
+  }
+  // HTTPS-only: a bearer token must never ride cleartext.
+  if (url.protocol !== "https:") {
+    throw new Error(`describe_image: refusing to send the Slack bot token over a non-HTTPS URL ("${url.protocol}").`);
+  }
+  // HOST-PIN (before any DNS): the token may ONLY go to a Slack file host. A non-Slack host is
+  // refused HERE — the token is never sent and the host isn't even resolved.
+  if (!isSlackFileHost(url.hostname)) {
+    await auditToolAction(ctx, "slack.attachment.deny", {
+      // `credential: null` is the load-bearing claim on every deny here: the host-pin is decided
+      // BEFORE the token is read, so a refused download never had one attached.
+      ...hostCallAuditFields({ host: url.hostname, verb: ATTACHMENT_VERB, outcome: "denied" }),
+      reason: "not-slack-file-host",
+      id: ref.id,
+    });
+    throw new Error(`describe_image: refusing to send the Slack bot token to non-Slack host "${url.hostname}".`);
+  }
+  // SSRF resolve-then-check-then-PIN — even Slack's own host gets the rebind check, and the
+  // connection is pinned to the validated public IP so it can't be re-resolved between check and
+  // connect. `redirect:"error"` (below) stops a 3xx bouncing the token to another host.
+  let safe: EgressDispatch;
+  try {
+    safe = await assertSafeFetchUrl(ref.urlPrivate);
+  } catch (err) {
+    const resolveFailed = (err as { oeEgressCause?: EgressRefusalCause })?.oeEgressCause === "resolve-failed";
+    await auditToolAction(ctx, "slack.attachment.deny", {
+      // `denied` rather than `failed` — the SSRF guard refuses on POLICY before any dispatch. A
+      // resolver that could not ANSWER is a different event and core tags it, so this seam reports
+      // it as `failed` under its own reason rather than as an SSRF refusal.
+      ...hostCallAuditFields({ host: url.hostname, verb: ATTACHMENT_VERB, outcome: resolveFailed ? "failed" : "denied" }),
+      reason: resolveFailed ? "resolve-failed" : "ssrf",
+      id: ref.id,
+    });
+    throw err;
+  }
+  // Defence-in-depth: assertSafeFetchUrl preserves the hostname, but re-assert it so the token can
+  // NEVER ride a host that isn't a Slack file host, whatever the parse produced.
+  if (!isSlackFileHost(safe.url.hostname)) {
+    await auditToolAction(ctx, "slack.attachment.deny", {
+      ...hostCallAuditFields({ host: safe.url.hostname, verb: ATTACHMENT_VERB, outcome: "denied" }),
+      reason: "not-slack-file-host",
+      id: ref.id,
+    });
+    throw new Error(`describe_image: refusing to send the Slack bot token to non-Slack host "${safe.url.hostname}".`);
+  }
+  const token = process.env.SLACK_BOT_TOKEN;
+  if (!token) {
+    throw new Error("describe_image: SLACK_BOT_TOKEN is not set — the bot token is required to download a Slack attachment.");
+  }
+  // ONE row per call, carrying the OUTCOME — so it is written after the dispatch settles, not
+  // before it starts (the same trade core's `oeFetch` states: the refusal paths above still record
+  // before anything leaves, and what is lost is a process death mid-flight).
+  //
+  // 🔴 `credential` NAMES THE REF, NEVER THE TOKEN. `token` is read one line above and is not
+  // referenced here; the row carries the ref name only, which is the identity an operator looks up.
+  // `route` is the dispatch route — it was called `via` until OPE-1547, the same field name the
+  // SANDBOX plane used for the stamping connection.
+  const row = (outcome: "allowed" | "failed", extra: Record<string, unknown> = {}): Record<string, unknown> => ({
+    ...hostCallAuditFields({
+      host: safe.url.hostname,
+      verb: ATTACHMENT_VERB,
+      outcome,
+      credential: SLACK_BOT_TOKEN_REF,
+    }),
+    id: ref.id,
+    route: safe.via,
+    antiRebind: safe.antiRebind,
+    ...extra,
+  });
+  let response: Response;
+  try {
+    // Bot token ONLY to the pinned Slack file host; NO redirect follow (a 3xx must not bounce the
+    // token elsewhere); connection pinned to the validated IP.
+    response = await fetch(safe.url, {
+      dispatcher: safe.dispatcher,
+      redirect: "error",
+      headers: { authorization: `Bearer ${token}` },
+    } as unknown as RequestInit);
+  } catch (err) {
+    await auditToolAction(ctx, "slack.attachment.allow", row("failed"));
+    throw err;
+  }
+  await auditToolAction(ctx, "slack.attachment.allow", row("allowed", { status: response.status }));
+  return response;
+}

package/agent/app-manifest.ts

@@ -0,0 +1,149 @@
+// THE Slack app manifest — one definition, three readers (OPE-1603).
+//
+// This file is the only place the manifest exists. The install wizard's Slack step
+// (packages/create/src/steps/slack.ts) prints it, the ops MCP tool `surface_manifest` serves it
+// with this deployment's host substituted, and `scripts/slack-scope-audit-test.ts` parses the bot
+// scope array below against the runbook's documented scopes. It used to live in the wizard, where
+// the ops server could not reach it at all.
+//
+// 🔴 THIS MODULE IMPORTS NOTHING, DELIBERATELY. The install wizard depends on the bundle for this
+// document alone, so a leaf module costs it no transitive weight — not the adapter-api barrel, not
+// eve, not the Slack Web API client. `agent/ops.ts` does the typed registration; this file holds
+// only the vendor's own knowledge.
+
+/** The token the request URLs carry where the deployment's own host belongs. The ops plane
+ *  substitutes it (packages/core/agent/ops/surface-manifest.ts); the wizard leaves it for the
+ *  operator, who has usually not deployed yet when they run it. */
+export const SLACK_DEPLOY_HOST_PLACEHOLDER = "YOUR-DEPLOY-URL";
+
+/** A ready-to-paste Slack app manifest (Slack's "create from manifest" flow) with the minimal
+ *  scope/event set docs/deploy/surfaces/slack.md walks through by hand. */
+export function slackAppManifestTemplate(): string {
+  return JSON.stringify(
+    {
+      display_information: { name: "Open Everywhere" },
+      features: {
+        bot_user: { display_name: "Open Everywhere", always_online: true },
+        // The "/oe" ZERO-INFERENCE control command (agent/commands/core.ts). Declared here rather
+        // than left to a manual setup step because one of its subcommands is `/oe stop` (OPE-418),
+        // and stop is not a convenience: it is the affordance a person reaches for when the agent
+        // is doing the wrong thing. An install where stop has to be wired by hand is an install
+        // where stop is missing. NOTE the request URL is the SLASH-COMMAND endpoint, which Slack
+        // configures SEPARATELY from the Events request URL above.
+        slash_commands: [
+          {
+            command: "/oe",
+            url: `https://${SLACK_DEPLOY_HOST_PLACEHOLDER}/eve/v1/slack/commands`,
+            description: "Open Everywhere control commands — status, budget, stop.",
+            usage_hint: "stop | status | budget",
+            should_escape: false,
+          },
+        ],
+        // SHORTCUTS AS A WAKE (OPE-1376). Both kinds are declared, because they answer two
+        // different needs and neither substitutes for the other: the MESSAGE shortcut hands the
+        // agent one message somebody is looking at, and the GLOBAL shortcut starts a conversation
+        // from the composer with no room in scope (it wakes the invoker's own DM window). Both
+        // arrive on the interactivity Request URL declared under `settings` below, which is why
+        // that block is no longer optional in this manifest.
+        //
+        // The `callback_id`s are free-form: the front route owns EVERY shortcut payload the app
+        // receives, so renaming one here changes only the trigger name the model is told about.
+        shortcuts: [
+          {
+            name: "Send to Open Everywhere",
+            type: "message",
+            callback_id: "oe_message_shortcut",
+            description: "Wake the agent on this message.",
+          },
+          {
+            name: "Ask Open Everywhere",
+            type: "global",
+            callback_id: "oe_global_shortcut",
+            description: "Wake the agent in a DM.",
+          },
+        ],
+      },
+      oauth_config: {
+        scopes: {
+          bot: [
+            "app_mentions:read",
+            "chat:write",
+            "channels:history",
+            // Slack's own description: "Add shortcuts and slash commands that people can use". It
+            // grants no read access — it is what lets this manifest DECLARE the `/oe` command above
+            // and the two shortcuts beside it. Both entry points are wakes an install needs.
+            "commands",
+            // conversations.info/conversations.members (channel trust gate, join intros, the
+            // governance roster) — public and private channel halves. Without these, EVERY
+            // channel binds `external` (fail-closed) on a fresh install, silently (OPE-175).
+            "channels:read",
+            "groups:read",
+            "im:history",
+            // conversations.info/conversations.members on a `D…` DM — the `im` half of the SAME two
+            // calls channels:read/groups:read cover for channels. The governance roster
+            // (slackGovernanceRoster) is keyed on whatever room a click or a card lands in, and DMs
+            // are rooms: on a member-tier approve-click in a DM the roster resolves the `D…` id, so
+            // without this both calls return `missing_scope`, the roster comes back unresolved, and
+            // the clicker floor's beneficiary leg refuses the click citing the roster (OPE-332,
+            // live-proven 2026-08-09). channels:read/groups:read do NOT cover an `im`.
+            "im:read",
+            // conversations.open — the governance DM-delivery arm (OPE-44): org-scope admin output
+            // asked in an ordinary room is delivered to the requester's DM, never rendered there.
+            "im:write",
+            "groups:history",
+            // The group-DM (`mpim`) half of `im:read` — same two calls, same call sites. Code-derived
+            // rather than live-proven: the roster/disclosure paths are keyed on the room, and a
+            // member-tier click or a card can land in a group DM exactly as it can in a 1:1.
+            "mpim:read",
+            "reactions:write",
+            "reactions:read",
+            "pins:read",
+            "pins:write",
+            // users.info — the DM-partner trust check. Without this, EVERY DM binds `external`
+            // (fail-closed) on a fresh install, silently (OPE-175).
+            "users:read",
+          ],
+        },
+      },
+      settings: {
+        event_subscriptions: {
+          request_url: `https://${SLACK_DEPLOY_HOST_PLACEHOLDER}/eve/v1/slack`,
+          bot_events: ["app_mention", "message.im", "reaction_added", "reaction_removed"],
+        },
+        // The INTERACTIVITY Request URL — the SAME public route Event Subscriptions uses. Every
+        // button click and every shortcut lands here, and the front route classifies which handler
+        // owns it. Required by the `shortcuts` above; without it Slack refuses to deliver a
+        // shortcut at all, and the approval / connector / "Set API key" cards' buttons fail with
+        // "the app is not configured to handle interactive responses".
+        interactivity: {
+          is_enabled: true,
+          request_url: `https://${SLACK_DEPLOY_HOST_PLACEHOLDER}/eve/v1/slack`,
+        },
+        org_deploy_enabled: false,
+        socket_mode_enabled: false,
+        token_rotation_enabled: false,
+      },
+    },
+    null,
+    2,
+  );
+}
+
+/** Where the operator pastes the manifest. */
+export const SLACK_APP_CONSOLE_URL = "https://api.slack.com/apps";
+
+/** The ordered clicks. Slack reserves every one of them for a workspace admin. */
+export const SLACK_APP_MANIFEST_STEPS: readonly string[] = [
+  "Open https://api.slack.com/apps and sign in to the workspace that will host the agent.",
+  "Create New App → From an app manifest.",
+  "Pick the workspace, choose JSON, and paste the manifest below.",
+  "Next → Create.",
+  "Install to Workspace, and approve the scopes Slack lists.",
+];
+
+/** What the operator brings back. Both are environment variables, not credential-store secrets:
+ *  the bundle reads them from the environment (agent/ops.ts). */
+export const SLACK_APP_MANIFEST_COLLECT: readonly string[] = [
+  "OAuth & Permissions → Bot User OAuth Token (xoxb-…) = SLACK_BOT_TOKEN",
+  "Basic Information → App Credentials → Signing Secret = SLACK_SIGNING_SECRET",
+];