Slack app

Push to Slack creates the agent's app in the tenant's workspace from its row — name, role line, scopes, events, commands — and installs it.

Several agents of one tenant live in the same workspace, each with its own app, name and commands. Binding a second leaves the first serving.

e.g. Echo and Golf in test-a's workspace → both serving; each answers its own DMs and mentions.

A Slack app, and its bot, serve one agent. Tokens of an app another agent already holds are refused, and that agent keeps them.

A push without the tenant's workspace token stored (TENANT-WORKSPACE-TOKEN-PROVED) is refused and nothing is created in Slack.

An agent that already has an app refuses a second push and names the app it has.

When the workspace refuses the automatic install, the app still exists and the Hub says to install it and paste both tokens.

The tenant's workspace token renews itself; nobody re-pastes one to keep pushing and renaming apps.

An app made before the tenant had a workspace token can be given its own, which also brings that app's scopes, name and commands up to date.

The app and its bot are called what the agent is called, with its suffix in brackets: Atlas, or Atlas (dev).

Every one of the app's slash commands starts with the same word, the suffix first: /sapien-status, or /dev-sapien-status.

An agent with no suffix of its own (AGENT-SUFFIX-ONE-WORD) takes the environment it runs in, so a dev stack's apps are marked and production's are not.

Two agents in one workspace never share a command name. Creating or renaming an agent whose commands would clash is refused, and the other agent's commands are untouched. Today this is checked whether or not either app registers commands; an app with them switched off is to reserve nothing.

e.g. a second agent named Echo in the same workspace, with the same suffix → refused before anything reaches Slack.

An agent's picture is set on its Slack app from the registry, with the token that manages the app (the app's own, or the tenant's workspace token), kept alive the same way a rename keeps it; Slack refuses an app the token did not create, and the refusal is said as Slack said it.

e.g. Nova's portrait sent for her app → her app and its bot show it in Slack; no reinstall.

A rename that reaches Slack (AGENT-RENAME-REACHES-SLACK) registers the commands under the new prefix and removes the old ones. It does this unconditionally today; a rename is to move only the commands an app still has.

Saving anything but the agent's name or suffix leaves the Slack app untouched.

The app asks for what an agent needs: mentions, messages, direct messages, channel history, users and their emails, files, and its own commands.

Sync pushes the scopes, events and commands the agent needs, adds only what is missing, and sends nothing when the app already has them. "Adds only" is about scopes and events: the command list is made to match what is declared, so a command no longer declared — an old prefix after a rename — is already removed. What it cannot do yet is remove them ALL.

When a sync adds a scope, somebody in the workspace must approve a reinstall; the Hub shows that link.

The app dials out to Slack: a customer sets up no address, certificate or webhook.

The app keeps one continuing direct-message surface rather than a fresh thread each time it is opened.

Both tokens must be of the right kind and the bot token must answer Slack, or nothing is stored.

e.g. a bot token that is not xoxb-… → refused, nothing stored.

e.g. a dead bot token → refused with what Slack said.

The app's tokens are stored sealed and only ever reported as set or missing.

An app somebody made by hand in Slack is connected by pasting its app id and its two tokens.

The agent's General tab says which state its app is in and shows the app name, its commands, its workspace, its app id and whether each token is set.

When Slack refuses something, Slack's own words are shown, including which part of the app it objected to.

Only an owner, an admin or an operator may push an app, sync it or paste tokens (AGENT-READ-ONLY-MEMBER).

An agent starts answering in Slack within seconds of its tokens being stored (AGENT-RELOAD-IN-SECONDS).

The Slack connection is remade only when a token, the harness, the channel or the list of who may speak changes; every other edit leaves it open.

Switching the agent or its binding off stops it answering and leaves the app and its tokens in place.

An agent whose tokens cannot be read is skipped and the rest of the fleet keeps answering.

On a dev stack only the dev app is served: every other seeded binding is off and the worker is given one agent.