Modpol/agentic-govbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Slack platform adapter and comprehensive platform skills system

Browse Source 
Major Features:
- Implemented full Slack channel-bot adapter with Socket Mode
- Added 35+ Mastodon platform skills across 7 categories
- Created constitution publishing system for Mastodon

Slack Adapter (NEW):
- Full PlatformAdapter implementation (1071 lines)
- Socket Mode for real-time events
- 16 channel-scoped governance skills
- User group management as channel "roles"
- Channel access control and management
- Message pinning and moderation
- Platform limitations documentation
- Comprehensive setup guide (SLACK_SETUP.md)

Mastodon Platform Skills (ENHANCED):
- Account Moderation (9 skills): suspend, silence, disable, mark sensitive, delete status
- Account Management (4 skills): approve, reject, delete data, create account
- Report Management (4 skills): assign, unassign, resolve, reopen
- Federation Management (4 skills): block/unblock domains, allow/disallow federation
- Security Management (4 skills): block IP/email domains
- Constitution Management (2 skills): publish constitution, update profile
- Documented web-only limitations (role management requires tootctl)

Constitution Publishing:
- Publish constitution as pinned Mastodon thread
- Automatic deprecation of previous versions
- Version control with change summaries
- Thread splitting for long documents
- CLI tool: scripts/publish_constitution.py
- Documentation: CONSTITUTION_PUBLISHING.md

Configuration & Integration:
- Added SlackConfig model with bot_token, app_token, channel_id
- Updated PlatformConfig to support type: slack
- Added slack-sdk>=3.33.0 dependency
- Bot.py now routes to Slack adapter
- Updated example config with Slack section

Documentation:
- SLACK_SETUP.md: Complete Slack setup guide
- PLATFORM_SKILLS.md: All 35+ Mastodon skills documented
- CONSTITUTION_PUBLISHING.md: Constitution publishing guide
- Updated README.md: Merged QUICKSTART, added Slack to supported platforms
- Updated PLATFORMS.md: Slack marked as implemented with examples
- Updated .gitignore: Added instance-specific state files

Security:
- All sensitive files properly gitignored
- Instance-specific state (.constitution_post_id) excluded
- Credentials properly handled in config

Breaking Changes: None

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Nathan Schneider
2026-02-10 22:46:48 -07:00
parent a0785f09cf
commit 54beddb420
16 changed files with 3675 additions and 489 deletions
Download Patch File Download Diff File Expand all files Collapse all files

372
PLATFORM_SKILLS.md Normal file
View File

@@ -0,0 +1,372 @@
# Mastodon Platform Skills
Complete listing of all platform-specific governance skills available through the Mastodon API.
## Overview
The bot now implements **35+ platform skills** organized into 7 categories:
- Account Moderation (9 skills)
- Account Management (4 skills)
- Report Management (4 skills)
- Federation Management (4 skills)
- Security Management (4 skills)
- Instance Administration (2 skills)
- Web-Only Actions (2 skills - informational only)
## Account Moderation Skills
### suspend_account
**Description**: Suspend a user account (reversible, blocks login and hides content)
**Parameters**:
- `account_id` (str): Account ID to suspend
- `reason` (str): Reason for suspension
**Reversible**: Yes (use `unsuspend_account`)
**Authorization**: Requires moderation authority per constitution
### unsuspend_account
**Description**: Lift suspension from an account
**Parameters**:
- `account_id` (str): Account ID to unsuspend
**Reversible**: Yes (can suspend again)
**Authorization**: Requires moderation authority per constitution
### silence_account
**Description**: Silence a user account (hide from public timelines, reversible)
**Parameters**:
- `account_id` (str): Account ID to silence
- `reason` (str): Reason for silencing
**Reversible**: Yes (use `unsilence_account`)
**Authorization**: Requires moderation authority per constitution
### unsilence_account
**Description**: Lift silence from an account
**Parameters**:
- `account_id` (str): Account ID to unsilence
**Reversible**: Yes (can silence again)
**Authorization**: Requires moderation authority per constitution
### disable_account
**Description**: Disable local account login (reversible)
**Parameters**:
- `account_id` (str): Account ID to disable
- `reason` (str): Reason for disabling
**Reversible**: Yes (use `enable_account`)
**Authorization**: Requires moderation authority per constitution
### enable_account
**Description**: Re-enable a disabled local account
**Parameters**:
- `account_id` (str): Account ID to enable
**Reversible**: Yes (can disable again)
**Authorization**: Requires moderation authority per constitution
### mark_account_sensitive
**Description**: Mark account's media as always sensitive
**Parameters**:
- `account_id` (str): Account ID to mark
- `reason` (str): Reason for marking sensitive
**Reversible**: Yes (use `unmark_account_sensitive`)
**Authorization**: Requires moderation authority per constitution
### unmark_account_sensitive
**Description**: Remove sensitive flag from account
**Parameters**:
- `account_id` (str): Account ID to unmark
**Reversible**: Yes (can mark sensitive again)
**Authorization**: Requires moderation authority per constitution
### delete_status
**Description**: Delete a status/post (permanent)
**Parameters**:
- `status_id` (str): Status ID to delete
- `reason` (str): Reason for deletion
**Reversible**: No
**Authorization**: Requires moderation authority per constitution
## Account Management Skills
### approve_account
**Description**: Approve a pending account registration
**Parameters**:
- `account_id` (str): Account ID to approve
**Reversible**: No
**Authorization**: Requires account approval authority per constitution
### reject_account
**Description**: Reject a pending account registration (permanent)
**Parameters**:
- `account_id` (str): Account ID to reject
**Reversible**: No
**Authorization**: Requires account approval authority per constitution
### delete_account_data
**Description**: Permanently delete all data for a suspended account (IRREVERSIBLE)
**Parameters**:
- `account_id` (str): Suspended account ID to delete
**Reversible**: No
**Note**: Account must already be suspended before data deletion
**Authorization**: Requires highest level authority per constitution
### create_account
**Description**: Create a new user account (requires email verification, may need approval)
**Parameters**:
- `username` (str): Desired username
- `email` (str): Email address
- `password` (str): Account password
- `reason` (str, optional): Registration reason (if approval required)
**Reversible**: No
**Limitations**:
- User must verify email before account is active
- May require manual moderator approval depending on instance settings
- Only creates regular user accounts (not admin accounts)
**Authorization**: Requires account creation authority per constitution
## Report Management Skills
### assign_report
**Description**: Assign a report to yourself for handling
**Parameters**:
- `report_id` (str): Report ID to assign
**Reversible**: Yes (use `unassign_report`)
**Authorization**: Requires report management authority per constitution
### unassign_report
**Description**: Unassign a report so others can claim it
**Parameters**:
- `report_id` (str): Report ID to unassign
**Reversible**: Yes (can reassign)
**Authorization**: Requires report management authority per constitution
### resolve_report
**Description**: Mark a report as resolved
**Parameters**:
- `report_id` (str): Report ID to resolve
**Reversible**: Yes (use `reopen_report`)
**Authorization**: Requires report management authority per constitution
### reopen_report
**Description**: Reopen a closed report
**Parameters**:
- `report_id` (str): Report ID to reopen
**Reversible**: Yes (can resolve again)
**Authorization**: Requires report management authority per constitution
## Federation Management Skills
### block_domain
**Description**: Block federation with a domain
**Parameters**:
- `domain` (str): Domain to block
- `severity` (str): Block severity: "silence", "suspend", or "noop"
- `public_comment` (str): Public reason for block
- `private_comment` (str, optional): Internal note
- `reject_media` (bool, optional): Reject media files from domain
- `reject_reports` (bool, optional): Reject reports from domain
- `obfuscate` (bool, optional): Hide domain name publicly
**Reversible**: Yes (use `unblock_domain`)
**Authorization**: Requires federation management authority per constitution
### unblock_domain
**Description**: Remove domain from block list
**Parameters**:
- `block_id` (str): Domain block ID to remove
**Reversible**: Yes (can block again)
**Authorization**: Requires federation management authority per constitution
### allow_domain
**Description**: Add domain to allowlist (for LIMITED_FEDERATION_MODE)
**Parameters**:
- `domain` (str): Domain to allow
**Reversible**: Yes (use `disallow_domain`)
**Authorization**: Requires federation management authority per constitution
### disallow_domain
**Description**: Remove domain from allowlist
**Parameters**:
- `allow_id` (str): Domain allow ID to remove
**Reversible**: Yes (can allow again)
**Authorization**: Requires federation management authority per constitution
## Security Management Skills
### block_ip
**Description**: Block IP address or range
**Parameters**:
- `ip` (str): IP address with CIDR prefix (e.g., "192.168.0.1/24")
- `severity` (str): Block severity: "sign_up_requires_approval", "sign_up_block", or "no_access"
- `comment` (str): Reason for IP block
- `expires_in` (int, optional): Expiration time in seconds
**Reversible**: Yes (use `unblock_ip`)
**Authorization**: Requires security management authority per constitution
### unblock_ip
**Description**: Remove IP block
**Parameters**:
- `block_id` (str): IP block ID to remove
**Reversible**: Yes (can block again)
**Authorization**: Requires security management authority per constitution
### block_email_domain
**Description**: Block email domain from registrations
**Parameters**:
- `domain` (str): Email domain to block (e.g., "spam.com")
**Reversible**: Yes (use `unblock_email_domain`)
**Authorization**: Requires security management authority per constitution
### unblock_email_domain
**Description**: Remove email domain from block list
**Parameters**:
- `block_id` (str): Email domain block ID to remove
**Reversible**: Yes (can block again)
**Authorization**: Requires security management authority per constitution
## Constitution Management Skills
### publish_constitution
**Description**: Post constitution as pinned thread (deprecates previous version)
**Parameters**:
- `constitution_text` (str): Full constitution text in markdown
- `change_summary` (str, optional): Summary of what changed
**Reversible**: No
**Authorization**: Requires constitutional amendment process
**Behavior**:
1. Finds previously pinned constitution (if any)
2. Adds deprecation notice to old version
3. Splits constitution into thread-sized chunks (~450 chars each)
4. Posts as public thread
5. Pins new thread to profile
6. Unpins old thread
7. Saves post ID for future updates
### update_profile
**Description**: Update bot profile information (bio, fields, display name)
**Parameters**:
- `display_name` (str, optional): Display name
- `note` (str, optional): Bio/description
- `fields` (list, optional): Profile fields (max 4, each with 'name' and 'value')
**Reversible**: Yes
**Authorization**: Requires governance approval
**Example fields**:
```json
[
{"name": "Constitution", "value": "📜 See pinned post"},
{"name": "Governance", "value": "Consensus-based"},
{"name": "Source", "value": "github.com/..."}
]
```
## Instance Administration Skills
**⚠️ IMPORTANT**: Role management is **NOT available via the Mastodon API**. See "Platform Limitations" section below for details.
## Web-Only Actions (Not Available via API)
These skills are included in the bot's knowledge so it can explain limitations to users.
### update_instance_rules
**Description**: Update instance rules/code of conduct
**Status**: WEB-ONLY - Must be done through admin interface
**Web Interface**: `/admin/server_settings/rules`
**Note**: Mastodon API does not provide endpoints for managing server rules programmatically
### create_announcement
**Description**: Create an instance-wide announcement
**Status**: WEB-ONLY - Must be done through admin interface
**Web Interface**: `/admin/announcements`
**Note**: Mastodon API does not provide endpoints for creating announcements programmatically
## Platform Limitations
The bot is now aware of the following limitations and can explain them to users:
### Actions Requiring Web Interface
- **Instance Rules**: Creating and editing server rules must be done at `/admin/server_settings/rules`
- **Announcements**: Creating instance-wide announcements must be done at `/admin/announcements`
- **Role Management**: ALL role operations (grant/revoke moderator, admin, or custom roles) must be done at `/admin/roles`
- **Instance Settings**: Modifying instance description, contact info, etc. requires web admin access
### Actions Not Possible via API
- **Role Management**: The Mastodon API does **NOT** support granting or revoking ANY roles (moderator, admin, or custom). You must use:
- **Web interface**: `/admin/roles`
- **Command line**: `tootctl accounts modify username --role RoleName`
- **Admin Account Creation**: Admin accounts cannot be created via API:
```bash
RAILS_ENV=production bin/tootctl accounts create username --email user@example.com --confirmed --role Owner
```
### General Limitations
- **Account Creation**: New accounts require email verification and may require manual approval depending on instance settings
- **Permissions Required**: All admin actions require both OAuth scopes AND appropriate role permissions (Manage Users, Manage Reports, etc.)
- **Rate Limits**: API endpoints are subject to rate limiting
- **Suspended Account Deletion**: Account data can only be deleted for already-suspended accounts
## How It Works
1. **Skill Discovery**: When a user makes a request, the bot receives the full list of platform skills
2. **Limitation Awareness**: The bot also receives information about what's not possible via API
3. **Intelligent Routing**: The LLM agent decides whether to:
- Execute a platform skill (if available and authorized)
- Explain a limitation (if requested action requires web interface)
- Create a governance process (if actor lacks authority)
- Respond with information (if just asking a question)
## Example Interactions
### Successful Platform Skill Execution
```
User: @govbot please suspend account 12345 for spam
Bot: I've suspended account 12345 for spam.
This action is reversible using the unsuspend_account skill.
```
### Web-Only Limitation
```
User: @govbot please update the instance rules
Bot: Instance rules cannot be updated via the API.
To update server rules, please visit:
https://your-instance.com/admin/server_settings/rules
You can add, edit, or remove rules through the admin interface.
```
### Account Creation with Limitations
```
User: @govbot create an account for newuser@example.com
Bot: Account @newuser created successfully.
Important: The user must verify their email before they can log in.
Depending on instance settings, manual approval may also be required.
```
## Technical Implementation
### Code Changes
1. **Mastodon Adapter** (`src/govbot/platforms/mastodon.py`):
- Added 35+ platform skills across 7 categories
- Implemented execution methods for all API-available skills
- Added `get_platform_limitations()` method to document limitations
- Web-only skills return helpful messages with admin interface URLs
2. **Governance Agent** (`src/govbot/agent.py`):
- Updated `process_request()` to accept `platform_limitations` parameter
- Enhanced decision-making prompt to include limitation information
- Agent now explains limitations when users request unavailable actions
3. **Bot Integration** (`src/govbot/bot.py`):
- Retrieves platform limitations alongside platform skills
- Passes limitations to agent for informed decision-making
### API Requirements
All admin skills require:
- Appropriate OAuth scopes (`admin:read`, `admin:write`, etc.)
- Role permissions (Manage Users, Manage Reports, Manage Federation, etc.)
- Active Mastodon.py connection with admin access token
## Documentation Sources
- [Mastodon Admin Accounts API](https://docs.joinmastodon.org/methods/admin/accounts/)
- [Mastodon Admin Reports API](https://docs.joinmastodon.org/methods/admin/reports/)
- [Mastodon Admin Domain Blocks API](https://docs.joinmastodon.org/methods/admin/domain_blocks/)
- [Mastodon Admin IP Blocks API](https://docs.joinmastodon.org/methods/admin/ip_blocks/)
- [Mastodon Admin Email Domain Blocks API](https://docs.joinmastodon.org/methods/admin/email_domain_blocks/)
- [Mastodon Accounts API](https://docs.joinmastodon.org/methods/accounts/)
- [Mastodon OAuth Scopes](https://docs.joinmastodon.org/api/oauth-scopes/)