SETUP_AGENT.md

Rama main · réplica de lectura del repositorio original.

# Slack setup runbook

Use the private setup link printed by the deployment. Chickpea creates the customer-owned Slack app, installs it, verifies its Events URL, and uses Slack itself for the first Owner identity. There is no password, Cloudflare Access, shared Admin token, or manual bot-token paste in the normal journey.

## Before starting

For source builds, local Node hosting, or the CLI, use Node 24.x, minimum
24.22.1. Run `nvm install && nvm use` in the checkout to select `.nvmrc`.
A Cloudflare Worker itself runs in workerd, independently of build-time Node.

- Know the Slack workspace where Chickpea should live. The installed `team_id` becomes the deployment's immutable workspace boundary.
- Be signed in to Slack as the person who should become Chickpea's first Owner.
- Slack decides whether that person may create/install apps. Chickpea does not require the installer to hold Slack's Owner or Admin label.
- Keep the private setup link in the same browser tab. The capability is removed from the URL and kept only in same-tab storage.

## Steps

1. Open the private `/admin/setup#setup=…` link.
2. Choose **Create the Slack app**. Chickpea uses the short-lived Slack configuration token supplied in the form to create exactly one app from the reviewed manifest. The token is not stored.
3. If Slack creation returns an ambiguous network result, inspect your Slack apps. Adopt the matching app or explicitly restart; do not create another app blindly.
4. Continue to Slack and choose the intended workspace. Review the requested bot permissions and select **Allow**. If the workspace requires app approval, request it and resume from the same setup page after approval.
5. Return to setup and use **Verify and continue** after Slack accepts and saves the Events URL. Chickpea promotes the encrypted credential revision only after the exact app/team OAuth result and a revision-bound signed Slack challenge agree.
6. Select **Become the first Owner with Slack**. The OIDC result must carry the same `team_id` as the installed app; the signed-in Slack `user_id` is bound atomically as the first Chickpea Owner.
7. Finish the in-app setup: choose a model provider and a model. A fresh deployment has no user Agent yet; `@Chickpea`, the built-in workspace assistant, answers direct messages and base mentions until you create one.
8. Open a direct message with `@Chickpea` and ask for a first teammate, as the setup page suggests. Chickpea offers a few starters that work without any connected account; replying with a number creates that Agent. Setup is complete only after a real Slack reply from Chickpea succeeds.
9. Connect your coding agent, and any scripts, to the management MCP server, so the workspace can be managed there as well as in Admin and Slack. Every deployment serves an OAuth-protected management MCP server at `https://<deployment>/mcp`, and the client signs in through Slack by itself. The fastest path is to paste `Connect my coding agent to my Chickpea using https://<deployment>/connect.md` into the agent; the public page `https://<deployment>/connect` shows that prompt, and Admin **Settings → MCP** (`/admin/settings/agents-clients`) has the exact snippet for Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, the Claude app, ChatGPT, or generic JSON, with one-click install for Claude, Cursor, and VS Code. From a shell, `npx chickpea-cli doctor https://<deployment>` confirms the public surface is up (it reports a 404 as unfinished setup until step 6 completes), `npx chickpea-cli mcp config https://<deployment>` prints the same snippets, and `npx chickpea-cli login https://<deployment>` gives scripts the same access. See [the workspace management runbook](docs/runbooks/workspace-management-mcp.md).

For Meta Ads, configure an installation-owned Meta App ID before connecting an Agent. See [Meta Ads setup](docs/runbooks/meta-ads-connector.md).

Optional: to let Agents open websites, create a Browserbase project, copy its API key (**Settings → API keys** in Browserbase), and paste it in Admin **Settings → Browser** (`/admin/settings/browser`). Nothing is enabled per Agent; website logins are added on an Agent's **Websites** tab. See [the browser runbook](docs/runbooks/browser-feature.md).

## Manual adoption

Manual app adoption is a secondary recovery path on the setup page. Use the same reviewed manifest and unchanged deployment callback URLs. Client secret and signing secret inputs are write-only and encrypted before persistence. Do not use an app-level `xapp-` token; Chickpea uses Slack's HTTP Events API and a bot OAuth token issued by the install flow.

Create the app, then add its credentials and exported JSON manifest in
Chickpea. If the app already exists, use **Already created the app? Add its
credentials** instead of creating another one. Continue through Slack OAuth;
the following setup screen directs you to verify and save the Events URL in
Slack. Do not attempt Events verification before credential adoption: Chickpea cannot authenticate
Slack's signed challenge without the signing secret.

### Agent handle prerequisite for a customer-owned app

The manual manifest already includes `usergroups:read` and `usergroups:write`.
Slack's workspace-level **Create and edit user groups** policy is separate;
there is no app-manifest field that can grant it. Agent handles also require a
paid Slack plan. See [Slack's user-group requirements](https://docs.slack.dev/reference/methods/usergroups.create/).

Before creating an Agent, have an Owner or Admin open the **intended workspace**
and go to **Roles & permissions → Account types → Create and edit user groups**.
Allow **Members** and save. This enables human members as well as the app to
manage user groups; disclose that consequence before changing the policy.
Ask an Org Owner if an organization policy locks the setting. A generic
`slack.com/admin` link can open a different signed-in workspace, so confirm the
workspace name before editing anything.

If an Agent was already saved with a permission error, return to it and select
**Retry**. Do not reinstall the app or create a duplicate Agent. Verify recovery
by selecting its real `@handle` in Slack's mention picker and observing a
threaded reply in a channel attached to that Agent.

## Slack's Stop button

While an Agent works, Slack can show a **Stop** button on the thread's working
indicator. Pressing it stops the run, the same as replying `stop` in the
thread, and only people who can use that Agent there can stop it. Slack shows
the button only to apps subscribed to the `agent_session_stopped` bot event.

A customer-owned app created from this release's manifest is already
subscribed. An app created earlier keeps working without it: setup and
recovery still pass, and people stop a run by replying `stop` (or `cancel`)
in its thread. To add the button to such an app, including a local Worker
lane's own app:

1. Open [api.slack.com/apps](https://api.slack.com/apps) and select the app.
2. Go to **Event Subscriptions**, open **Subscribe to bot events**, and choose
   **Add Bot User Event**.
3. Add `agent_session_stopped`, then **Save Changes**.

The event needs only the `chat:write` permission the app already has, so no
new permission is requested. Credential recovery never adds the event: it
keeps the app's subscriptions as they are. Installations on the shared
Chickpea app get the button when its maintainer subscribes that app.

## Group DMs

People can ask Agents in a Slack group DM. Only `@Chickpea` and Agents that
everyone in the workspace can use answer there. A customer-owned app created
from this release's manifest subscribes to the `message.mpim` bot event and
has the `mpim:history` permission. With both, an Agent in a group DM answers
its handle and replies in its thread, and it reads the group's recent
messages before a mention.

An app created earlier keeps working without them: setup and recovery still
pass. In its group DMs only `@Chickpea` mentions arrive, and Agents read no
earlier messages there. To add both to such an app, including a local Worker
lane's own app:

1. Open [api.slack.com/apps](https://api.slack.com/apps) and select the app.
2. Go to **OAuth & Permissions**. Under **Bot Token Scopes**, add
   `mpim:history`.
3. Go to **Event Subscriptions**, open **Subscribe to bot events**, and choose
   **Add Bot User Event**.
4. Add `message.mpim`, then **Save Changes**.
5. When Slack asks to reinstall the app, reinstall it to the workspace so it
   grants the new permission.

Credential recovery never adds either. The shared Chickpea app has both. An
installation on it gets the permission when an Owner or Admin uses
**Reconnect with Slack** in **Settings → Slack**, and hears only `@Chickpea` in
group DMs until then.

## Permissions for upcoming features

A customer-owned app created from this release's manifest requests seven
more permissions: `channels:manage`, `groups:write`, `im:read`,
`mpim:write`, `team:read`, `canvases:read` and `canvases:write`. This
release uses none of them. Upcoming releases will.

An installation on an app created earlier keeps working without them, and
credential recovery still passes. A fresh setup adopts only an app whose
manifest matches this release's, so add them before adopting such an app.
To add them to an app, including a local Worker lane's own app,
add all seven, not some of them. Recovery recognizes an app that holds all
seven or none, and one that holds some of them only while its installed
grant matches its configuration.

1. Open [api.slack.com/apps](https://api.slack.com/apps) and select the app.
2. Go to **OAuth & Permissions**. Under **Bot Token Scopes**, add
   `channels:manage`, `groups:write`, `im:read`, `mpim:write`, `team:read`,
   `canvases:read` and `canvases:write`, then **Save Changes**.
3. When Slack asks to reinstall the app, reinstall it to the workspace so it
   grants the new permissions.

Credential recovery never adds them. An installation on the shared Chickpea
app gets them when an Owner or Admin uses **Reconnect with Slack** in
**Settings → Slack** after its maintainer adds them to that app.

## Recovery

If credential key material or the installed Slack app credentials are lost, use the hidden scoped recovery flow in [docs/runbooks/slack-auth-recovery.md](docs/runbooks/slack-auth-recovery.md). It can repair only the unchanged app and workspace. It cannot create an Owner, grant a role, or sign anyone in.