mercury-agent 0.5.0 → 0.5.2

package/docs/permissions.md

@@ -1,217 +1,217 @@
-# Permissions
-
-Mercury uses role-based access control (RBAC) per space. Each user has a role, and each role has a set of permissions.
-
-## How It Works
-
-```
-Message arrives
-  │
-  ├─► Resolve caller's role
-  │     • System caller? → role = "system"
-  │     • Seeded admin? → grant admin, store in DB
-  │     • Existing role in DB? → use it
-  │     • Otherwise → "member"
-  │
-  ├─► Load role's permissions
-  │     • Check space_config for override
-  │     • Fall back to built-in defaults
-  │
-  └─► Check permission for action
-        • Has permission → proceed
-        • Denied → return error
-```
-
-## Roles
-
-| Role | Default Permissions | Description |
-|------|---------------------|-------------|
-| `system` | All | Internal system caller (scheduler, etc.) — not assignable |
-| `admin` | All | Full control over the space |
-| `member` | `prompt`, `prefs.get` | Can chat and read space preferences (default for new users) |
-
-Custom roles can be created by assigning permissions to any role name.
-
-## Permissions
-
-| Permission | Description |
-|------------|-------------|
-| `prompt` | Send messages to the assistant |
-| `stop` | Abort running agent and clear queue |
-| `compact` | Reset session boundary (fresh context) |
-| `tasks.list` | View scheduled tasks |
-| `tasks.create` | Create new scheduled tasks |
-| `tasks.pause` | Pause scheduled tasks |
-| `tasks.resume` | Resume paused tasks |
-| `tasks.delete` | Delete scheduled tasks |
-| `config.get` | Read space configuration |
-| `config.set` | Modify space configuration |
-| `prefs.get` | Read space preferences (`mrctl prefs list/get`) |
-| `prefs.set` | Create, update, or delete space preferences (`mrctl prefs set/delete`) |
-| `roles.list` | View roles in the space |
-| `roles.grant` | Assign roles to users |
-| `roles.revoke` | Remove roles from users |
-| `permissions.get` | View role permissions |
-| `permissions.set` | Modify role permissions |
-| `spaces.list` | View all spaces |
-| `spaces.rename` | Rename a space and link/unlink conversations |
-| `spaces.delete` | Delete current space and all related DB data |
-
-## Mutes
-
-Muted users’ messages are dropped for the space until the mute expires or is cleared. The agent can mute via `mrctl mute` (with API confirmation). **Operators** with dashboard access (`MERCURY_API_SECRET`) can list active mutes, unmute, or add a timed mute from **Spaces → (space) → Muted users**.
-
-## Managing Roles
-
-The agent uses `mrctl` to manage roles:
-
-```bash
-# List all roles in the current space
-mrctl roles list
-
-# Grant admin role to a user
-mrctl roles grant 1234567890@s.whatsapp.net --role admin
-
-# Grant a custom role
-mrctl roles grant 1234567890@s.whatsapp.net --role moderator
-
-# Revoke role (user becomes member)
-mrctl roles revoke 1234567890@s.whatsapp.net
-```
-
-## Managing Permissions
-
-Permissions are per-role, per-space:
-
-```bash
-# Show permissions for all roles
-mrctl permissions show
-
-# Show permissions for a specific role
-mrctl permissions show --role member
-
-# Give members ability to stop the agent
-mrctl permissions set member prompt,stop
-
-# Create a moderator role with task management
-mrctl permissions set moderator prompt,stop,tasks.list,tasks.pause,tasks.resume
-
-# Give a role full task control
-mrctl permissions set taskmaster prompt,tasks.list,tasks.create,tasks.pause,tasks.resume,tasks.delete
-```
-
-## Managing Spaces
-
-Spaces can be listed and managed via `mrctl`:
-
-```bash
-# List all spaces with their names
-mrctl spaces list
-
-# Get current space's display name
-mrctl spaces name
-
-# Set current space's display name
-mrctl spaces name "Startup Buddies"
-
-# Delete current space (tasks, messages, roles, config)
-mrctl spaces delete
-
-# List discovered conversations
-mrctl conversations list
-
-# Show only conversations that are not yet linked
-mrctl conversations list --unlinked
-```
-
-Space names are stored in the database and shown in logs/dashboard for easier identification. Conversations remain platform-native and are linked into spaces. Conversation listing uses `spaces.list`; linking and unlinking use `spaces.rename`.
-
-## Seeding Admins
-
-Pre-configure admin users via environment variable. They're granted admin on first interaction with each space:
-
-```bash
-MERCURY_ADMINS=1234567890@s.whatsapp.net,0987654321@s.whatsapp.net
-```
-
-This is useful for bootstrapping — the first admin can then grant roles to others.
-
-## Storage
-
-Roles and permissions are stored in SQLite:
-
-| Table | Purpose |
-|-------|---------|
-| `space_roles` | Maps `(space_id, platform_user_id)` → `role` |
-| `space_config` | Stores `role.<name>.permissions` overrides |
-
-Built-in defaults (`admin` = all, `member` = `prompt` + `prefs.get`) are not stored — they're applied when no override exists.
-
-## System Caller
-
-The `system` role is special:
-
-- Always has all permissions
-- Cannot be modified or assigned
-- Used for internal callers: scheduled tasks, system triggers
-
-```typescript
-if (isSystemCaller(callerId)) return "system";
-```
-
-## Extension Permissions
-
-Extensions register additional permissions at runtime via the extension API:
-
-```typescript
-mercury.permission({ defaultRoles: ["admin", "member"] });
-```
-
-This registers a permission named after the extension (e.g., `napkin`). The behavior:
-
-- **Admin** always gets all permissions (built-in + extension)
-- **Extension `defaultRoles`** are respected — if `["member"]` is specified, members get that permission by default
-- **Per-space overrides** still take precedence over defaults
-- **Built-in permission names** cannot be overridden by extensions
-
-Extension CLIs are called directly by the agent in bash. Permission enforcement is handled by a pi extension that blocks denied CLIs at the bash tool level, based on the caller's role and the `MERCURY_DENIED_CLIS` environment variable set by Mercury's runtime.
-
-Extensions that declare env vars via `mercury.env()` also have those vars gated by permission — they are only injected into containers when the caller has the extension's permission. This prevents credential leakage (e.g., a blocked `gh` CLI's `GH_TOKEN` being used via `curl`).
-
-### API
-
-```typescript
-registerPermission(name, { defaultRoles })   // Register (called by extension loader)
-getAllPermissions()                            // Built-in + extension permissions
-isValidPermission(name)                       // Check if name is valid
-resetPermissions()                            // Clear registered (test isolation)
-```
-
-## Scope
-
-Permissions are **per-space**:
-
-- A user can be `admin` in one space and `member` in another
-- Custom role permissions are space-specific
-- No global roles (except seeded admins, which apply on first interaction per space)
-
-## API
-
-### `resolveRole(db, spaceId, platformUserId, seededAdmins)`
-
-Determines a caller's role:
-1. System caller → `"system"`
-2. Seed admins if needed
-3. Upsert member record
-4. Return stored role or `"member"`
-
-### `getRolePermissions(db, spaceId, role)`
-
-Returns the permission set for a role:
-1. System role → all permissions
-2. Check `space_config` for `role.<name>.permissions`
-3. Fall back to built-in defaults
-
-### `hasPermission(db, spaceId, role, permission)`
-
-Returns `true` if the role has the specified permission.
+# Permissions
+
+Mercury uses role-based access control (RBAC) per space. Each user has a role, and each role has a set of permissions.
+
+## How It Works
+
+```
+Message arrives
+  │
+  ├─► Resolve caller's role
+  │     • System caller? → role = "system"
+  │     • Seeded admin? → grant admin, store in DB
+  │     • Existing role in DB? → use it
+  │     • Otherwise → "member"
+  │
+  ├─► Load role's permissions
+  │     • Check space_config for override
+  │     • Fall back to built-in defaults
+  │
+  └─► Check permission for action
+        • Has permission → proceed
+        • Denied → return error
+```
+
+## Roles
+
+| Role | Default Permissions | Description |
+|------|---------------------|-------------|
+| `system` | All | Internal system caller (scheduler, etc.) — not assignable |
+| `admin` | All | Full control over the space |
+| `member` | `prompt`, `prefs.get` | Can chat and read space preferences (default for new users) |
+
+Custom roles can be created by assigning permissions to any role name.
+
+## Permissions
+
+| Permission | Description |
+|------------|-------------|
+| `prompt` | Send messages to the assistant |
+| `stop` | Abort running agent and clear queue |
+| `compact` | Reset session boundary (fresh context) |
+| `tasks.list` | View scheduled tasks |
+| `tasks.create` | Create new scheduled tasks |
+| `tasks.pause` | Pause scheduled tasks |
+| `tasks.resume` | Resume paused tasks |
+| `tasks.delete` | Delete scheduled tasks |
+| `config.get` | Read space configuration |
+| `config.set` | Modify space configuration |
+| `prefs.get` | Read space preferences (`mrctl prefs list/get`) |
+| `prefs.set` | Create, update, or delete space preferences (`mrctl prefs set/delete`) |
+| `roles.list` | View roles in the space |
+| `roles.grant` | Assign roles to users |
+| `roles.revoke` | Remove roles from users |
+| `permissions.get` | View role permissions |
+| `permissions.set` | Modify role permissions |
+| `spaces.list` | View all spaces |
+| `spaces.rename` | Rename a space and link/unlink conversations |
+| `spaces.delete` | Delete current space and all related DB data |
+
+## Mutes
+
+Muted users’ messages are dropped for the space until the mute expires or is cleared. The agent can mute via `mrctl mute` (with API confirmation). **Operators** with dashboard access (`MERCURY_API_SECRET`) can list active mutes, unmute, or add a timed mute from **Spaces → (space) → Muted users**.
+
+## Managing Roles
+
+The agent uses `mrctl` to manage roles:
+
+```bash
+# List all roles in the current space
+mrctl roles list
+
+# Grant admin role to a user
+mrctl roles grant 1234567890@s.whatsapp.net --role admin
+
+# Grant a custom role
+mrctl roles grant 1234567890@s.whatsapp.net --role moderator
+
+# Revoke role (user becomes member)
+mrctl roles revoke 1234567890@s.whatsapp.net
+```
+
+## Managing Permissions
+
+Permissions are per-role, per-space:
+
+```bash
+# Show permissions for all roles
+mrctl permissions show
+
+# Show permissions for a specific role
+mrctl permissions show --role member
+
+# Give members ability to stop the agent
+mrctl permissions set member prompt,stop
+
+# Create a moderator role with task management
+mrctl permissions set moderator prompt,stop,tasks.list,tasks.pause,tasks.resume
+
+# Give a role full task control
+mrctl permissions set taskmaster prompt,tasks.list,tasks.create,tasks.pause,tasks.resume,tasks.delete
+```
+
+## Managing Spaces
+
+Spaces can be listed and managed via `mrctl`:
+
+```bash
+# List all spaces with their names
+mrctl spaces list
+
+# Get current space's display name
+mrctl spaces name
+
+# Set current space's display name
+mrctl spaces name "Startup Buddies"
+
+# Delete current space (tasks, messages, roles, config)
+mrctl spaces delete
+
+# List discovered conversations
+mrctl conversations list
+
+# Show only conversations that are not yet linked
+mrctl conversations list --unlinked
+```
+
+Space names are stored in the database and shown in logs/dashboard for easier identification. Conversations remain platform-native and are linked into spaces. Conversation listing uses `spaces.list`; linking and unlinking use `spaces.rename`.
+
+## Seeding Admins
+
+Pre-configure admin users via environment variable. They're granted admin on first interaction with each space:
+
+```bash
+MERCURY_ADMINS=1234567890@s.whatsapp.net,0987654321@s.whatsapp.net
+```
+
+This is useful for bootstrapping — the first admin can then grant roles to others.
+
+## Storage
+
+Roles and permissions are stored in SQLite:
+
+| Table | Purpose |
+|-------|---------|
+| `space_roles` | Maps `(space_id, platform_user_id)` → `role` |
+| `space_config` | Stores `role.<name>.permissions` overrides |
+
+Built-in defaults (`admin` = all, `member` = `prompt` + `prefs.get`) are not stored — they're applied when no override exists.
+
+## System Caller
+
+The `system` role is special:
+
+- Always has all permissions
+- Cannot be modified or assigned
+- Used for internal callers: scheduled tasks, system triggers
+
+```typescript
+if (isSystemCaller(callerId)) return "system";
+```
+
+## Extension Permissions
+
+Extensions register additional permissions at runtime via the extension API:
+
+```typescript
+mercury.permission({ defaultRoles: ["admin", "member"] });
+```
+
+This registers a permission named after the extension (e.g., `napkin`). The behavior:
+
+- **Admin** always gets all permissions (built-in + extension)
+- **Extension `defaultRoles`** are respected — if `["member"]` is specified, members get that permission by default
+- **Per-space overrides** still take precedence over defaults
+- **Built-in permission names** cannot be overridden by extensions
+
+Extension CLIs are called directly by the agent in bash. Permission enforcement is handled by a pi extension that blocks denied CLIs at the bash tool level, based on the caller's role and the `MERCURY_DENIED_CLIS` environment variable set by Mercury's runtime.
+
+Extensions that declare env vars via `mercury.env()` also have those vars gated by permission — they are only injected into containers when the caller has the extension's permission. This prevents credential leakage (e.g., a blocked `gh` CLI's `GH_TOKEN` being used via `curl`).
+
+### API
+
+```typescript
+registerPermission(name, { defaultRoles })   // Register (called by extension loader)
+getAllPermissions()                            // Built-in + extension permissions
+isValidPermission(name)                       // Check if name is valid
+resetPermissions()                            // Clear registered (test isolation)
+```
+
+## Scope
+
+Permissions are **per-space**:
+
+- A user can be `admin` in one space and `member` in another
+- Custom role permissions are space-specific
+- No global roles (except seeded admins, which apply on first interaction per space)
+
+## API
+
+### `resolveRole(db, spaceId, platformUserId, seededAdmins)`
+
+Determines a caller's role:
+1. System caller → `"system"`
+2. Seed admins if needed
+3. Upsert member record
+4. Return stored role or `"member"`
+
+### `getRolePermissions(db, spaceId, role)`
+
+Returns the permission set for a role:
+1. System role → all permissions
+2. Check `space_config` for `role.<name>.permissions`
+3. Fall back to built-in defaults
+
+### `hasPermission(db, spaceId, role, permission)`
+
+Returns `true` if the role has the specified permission.