@desplega.ai/agent-swarm 1.80.3 → 1.81.0

package/plugin/commands/user-management.md

@@ -1,5 +1,5 @@
 ---
-description: "How to manage the user registry — creating users for new Slack/GitHub/GitLab identities, managing aliases, resolving users across platforms. Use when a new human interacts with the swarm or when user identity needs updating."
+description: "How to manage the user registry — creating users for new Slack/GitHub/GitLab/Linear identities, managing aliases, resolving users across platforms. Use when a new human interacts with the swarm or when user identity needs updating."
 argument-hint: [action]
 ---
 
@@ -7,16 +7,18 @@ argument-hint: [action]
 
 Manage the swarm's user registry — creating, updating, resolving, and listing users. Users link human identities across platforms (Slack, GitHub, GitLab, Linear, email) so the swarm can track who requested work.
 
+> **Migration note (2026-05)**: the old top-level identity fields (`slackUserId`, `linearUserId`, `githubUsername`, `gitlabUsername`) and the fuzzy `name` lookup were removed in lockstep with the user-identity refactor. Use the new `{kind, externalId}` shape instead. Old payloads now fail Zod validation at runtime — there is no compatibility shim.
+
 ## When to Create Users
 
 Create a new user when:
-- An **unknown Slack user** sends a message to the swarm (no `resolveUser` match for their `slackUserId`)
+- An **unknown Slack user** sends a message to the swarm (`resolve-user` with `{kind: "slack", externalId: "<U_X>"}` returns no match)
 - An **unknown GitHub user** opens an issue or PR that triggers a task
 - An **unknown GitLab user** creates an issue or MR
 - An **unknown Linear user** is assigned to or creates a synced issue
 - A human explicitly asks to be registered
 
-**Do NOT** create duplicate users. Always call `resolve-user` first to check if the person already exists under a different platform identity.
+**Do NOT** create duplicate users. Always call `resolve-user` first — by `{kind, externalId}` AND, when you have it, by `email` — to check if the person already exists under a different platform identity.
 
 ## Tools
 
@@ -24,41 +26,62 @@ Two MCP tools handle user management:
 
 ### `resolve-user` — Find an existing user
 
-Looks up a user by any platform identity. Use this BEFORE creating a new user.
+Looks up a user by an `(kind, externalId)` pair OR by email (primary or alias). Use this BEFORE creating a new user. Caller MUST supply either `(kind + externalId)` OR `email` — empty input is rejected.
 
 ```
+# Lookup by platform identity
+resolve-user with:
+  kind: "slack"
+  externalId: "U12345"
+
+# OR
+resolve-user with:
+  kind: "github"
+  externalId: "octocat"
+
+# OR
+resolve-user with:
+  kind: "gitlab"
+  externalId: "octocat"
+
+# OR
+resolve-user with:
+  kind: "linear"
+  externalId: "uuid-from-linear"
+
+# OR lookup by email (primary or alias)
 resolve-user with:
-  slackUserId: "U12345"       # Slack member ID
-  # OR
-  githubUsername: "octocat"    # GitHub username
-  # OR
-  gitlabUsername: "octocat"    # GitLab username
-  # OR
-  linearUserId: "uuid"        # Linear user UUID
-  # OR
-  email: "user@example.com"   # Primary email or alias
-  # OR
-  name: "Jane Doe"            # Fuzzy name search (least specific)
+  email: "user@example.com"
 ```
 
-Priority order: platform IDs > email > name. Platform IDs are exact matches; email checks aliases (case-insensitive); name is substring match.
+Email lookup is case-insensitive and checks the primary `email` column AND every entry in `emailAliases`.
 
 ### `manage-user` — CRUD operations
 
+Identities are managed via a declarative `identities: [{kind, externalId}, ...]` array:
+
+- On **create**: every entry in `identities` is linked (each emits `identity_added`).
+- On **update**: `identities` is treated as the full desired set. Helper computes a diff against the user's current identities — adds emit `identity_added`, removes emit `identity_removed`. Omit the field entirely to leave identities untouched.
+
 ```
 # Create a new user
 manage-user with:
   action: "create"
-  name: "Jane Doe"                          # Required
-  email: "jane@company.com"                 # Optional
-  role: "engineering lead"                  # Optional, free-form
-  slackUserId: "U12345"                     # Optional
-  githubUsername: "janedoe"                 # Optional
-  gitlabUsername: "janedoe"                 # Optional
-  linearUserId: "uuid-from-linear"          # Optional
-  emailAliases: ["jane.doe@company.com"]    # Optional
-  timezone: "America/New_York"              # Optional
-  notes: "Prefers async communication"      # Optional
+  name: "Jane Doe"                            # Required
+  email: "jane@company.com"                   # Optional
+  role: "engineering lead"                    # Optional, free-form
+  identities:                                 # Optional
+    - kind: "slack"
+      externalId: "U12345"
+    - kind: "github"
+      externalId: "janedoe"
+    - kind: "linear"
+      externalId: "uuid-from-linear"
+  emailAliases: ["jane.doe@company.com"]      # Optional
+  timezone: "America/New_York"                # Optional
+  notes: "Prefers async communication"        # Optional
+  dailyBudgetUsd: 25.0                        # Optional — null/omitted = unlimited
+  status: "active"                            # Optional — "invited" | "active" | "suspended"
 
 # List all users
 manage-user with:
@@ -69,11 +92,16 @@ manage-user with:
   action: "get"
   userId: "<uuid>"
 
-# Update a user (only send fields to change)
+# Update a user (declarative — pass the FULL desired set for `identities`)
 manage-user with:
   action: "update"
   userId: "<uuid>"
-  githubUsername: "new-username"
+  identities:                                 # FULL desired set; diff is applied
+    - kind: "slack"
+      externalId: "U12345"
+    - kind: "github"
+      externalId: "janedoe-new"               # renamed → identity_added + identity_removed
+  emailAliases: ["jane.doe@company.com", "jd@example.com"]   # emits email_added/email_removed per delta
 
 # Delete a user
 manage-user with:
@@ -83,37 +111,48 @@ manage-user with:
 
 ## Workflow: New Slack User
 
-1. Receive a message from an unknown Slack user (e.g., `slackUserId: "U_NEW123"`)
-2. Call `resolve-user` with `slackUserId: "U_NEW123"` — returns null
-3. Get the user's Slack profile (name, email) via `slack-read` or from the message metadata
-4. Call `resolve-user` with `email: "<their-email>"` — check if they exist under a different platform
-5. If found: call `manage-user` with `action: "update"` to add their `slackUserId`
-6. If not found: call `manage-user` with `action: "create"` including name, email, and slackUserId
+1. Receive a message from an unknown Slack user (e.g., external ID `U_NEW123`).
+2. Call `resolve-user` with `{kind: "slack", externalId: "U_NEW123"}` — returns null.
+3. Get the user's Slack profile (name, email) via `slack-read` or from the message metadata.
+4. Call `resolve-user` with `{email: "<their-email>"}` — check if they exist under a different platform.
+5. If found: call `manage-user` with `action: "update"`, passing the user's FULL identity set including the new Slack entry.
+6. If not found: call `manage-user` with `action: "create"`, including `name`, `email`, and `identities: [{kind: "slack", externalId: "U_NEW123"}]`.
 
 ## Workflow: New GitHub User
 
-1. Receive a webhook from an unknown GitHub user (e.g., `githubUsername: "octocat"`)
-2. Call `resolve-user` with `githubUsername: "octocat"` — returns null
-3. Call `manage-user` with `action: "create"` including at minimum `name` and `githubUsername`
-4. If you know their email (from the webhook payload), include it
+1. Receive a webhook from an unknown GitHub user (e.g., login `octocat`).
+2. Call `resolve-user` with `{kind: "github", externalId: "octocat"}` — returns null.
+3. Call `manage-user` with `action: "create"`, including at minimum `name` and `identities: [{kind: "github", externalId: "octocat"}]`.
+4. If you know their email (from the webhook payload), include it.
 
 ## Workflow: Linking Identities
 
 When you discover a known user is also active on another platform:
 
-1. Call `resolve-user` to find them by their known identity
-2. Call `manage-user` with `action: "update"` to add the new platform identity
+1. Call `resolve-user` to find them by their known identity.
+2. Call `manage-user` with `action: "update"`, passing the FULL desired `identities` set (existing + the new one).
+
+Example: You know "Jane" by Slack ID, and discover her GitHub login:
 
-Example: You know "Jane" by Slack ID, and discover her GitHub username:
 ```
-resolve-user slackUserId: "U_JANE"  → returns user with id "abc-123"
-manage-user action: "update" userId: "abc-123" githubUsername: "janedoe"
+resolve-user kind: "slack" externalId: "U_JANE"
+→ returns user with id "abc-123" (identities currently: [{kind: "slack", externalId: "U_JANE"}])
+
+manage-user action: "update" userId: "abc-123"
+  identities:
+    - kind: "slack"
+      externalId: "U_JANE"
+    - kind: "github"
+      externalId: "janedoe"
+→ adds GitHub identity (emit identity_added). Slack identity unchanged.
 ```
 
 ## Important Notes
 
 - `manage-user` is **lead-only** — workers cannot use it for any action (the lead check happens before action dispatch). Workers must use `resolve-user` for lookups.
-- `slackUserId`, `githubUsername`, `gitlabUsername`, and `linearUserId` have **unique constraints** — duplicates will error.
+- The `(kind, externalId)` PK on `user_external_ids` means the same identifier cannot be linked to two different users — a re-link to a different user surfaces as a PK collision (the operator can investigate via the People page merge flow).
 - Deleting a user clears `requestedByUserId` on all their associated tasks (sets to null).
-- Email aliases are case-insensitive for resolution.
-- The `preferredChannel` field defaults to `"slack"` and can be `"slack"`, `"email"`, `"github"`, or `"gitlab"`.
+- Email aliases are case-insensitive for resolution. Editing them via `manage-user update` emits `email_added` / `email_removed` events per delta.
+- The `preferredChannel` field defaults to `"slack"` and can be `"slack"`, `"email"`, `"github"`, `"gitlab"`, or any custom string.
+- `dailyBudgetUsd` is `null` = unlimited.
+- `status` lifecycle: `invited` → `active` → `suspended`. The CHECK constraint rejects other values.

package/plugin/pi-skills/user-management/SKILL.md

@@ -1,22 +1,24 @@
 ---
 name: user-management
-description: "How to manage the user registry — creating users for new Slack/GitHub/GitLab identities, managing aliases, resolving users across platforms. Use when a new human interacts with the swarm or when user identity needs updating."
+description: "How to manage the user registry — creating users for new Slack/GitHub/GitLab/Linear identities, managing aliases, resolving users across platforms. Use when a new human interacts with the swarm or when user identity needs updating."
 ---
 
 # User Management
 
 Manage the swarm's user registry — creating, updating, resolving, and listing users. Users link human identities across platforms (Slack, GitHub, GitLab, Linear, email) so the swarm can track who requested work.
 
+> **Migration note (2026-05)**: the old top-level identity fields (`slackUserId`, `linearUserId`, `githubUsername`, `gitlabUsername`) and the fuzzy `name` lookup were removed in lockstep with the user-identity refactor. Use the new `{kind, externalId}` shape instead. Old payloads now fail Zod validation at runtime — there is no compatibility shim.
+
 ## When to Create Users
 
 Create a new user when:
-- An **unknown Slack user** sends a message to the swarm (no `resolveUser` match for their `slackUserId`)
+- An **unknown Slack user** sends a message to the swarm (`resolve-user` with `{kind: "slack", externalId: "<U_X>"}` returns no match)
 - An **unknown GitHub user** opens an issue or PR that triggers a task
 - An **unknown GitLab user** creates an issue or MR
 - An **unknown Linear user** is assigned to or creates a synced issue
 - A human explicitly asks to be registered
 
-**Do NOT** create duplicate users. Always call `resolve-user` first to check if the person already exists under a different platform identity.
+**Do NOT** create duplicate users. Always call `resolve-user` first — by `{kind, externalId}` AND, when you have it, by `email` — to check if the person already exists under a different platform identity.
 
 ## Tools
 
@@ -24,41 +26,62 @@ Two MCP tools handle user management:
 
 ### `resolve-user` — Find an existing user
 
-Looks up a user by any platform identity. Use this BEFORE creating a new user.
+Looks up a user by an `(kind, externalId)` pair OR by email (primary or alias). Use this BEFORE creating a new user. Caller MUST supply either `(kind + externalId)` OR `email` — empty input is rejected.
 
 ```
+# Lookup by platform identity
+resolve-user with:
+  kind: "slack"
+  externalId: "U12345"
+
+# OR
+resolve-user with:
+  kind: "github"
+  externalId: "octocat"
+
+# OR
+resolve-user with:
+  kind: "gitlab"
+  externalId: "octocat"
+
+# OR
+resolve-user with:
+  kind: "linear"
+  externalId: "uuid-from-linear"
+
+# OR lookup by email (primary or alias)
 resolve-user with:
-  slackUserId: "U12345"       # Slack member ID
-  # OR
-  githubUsername: "octocat"    # GitHub username
-  # OR
-  gitlabUsername: "octocat"    # GitLab username
-  # OR
-  linearUserId: "uuid"        # Linear user UUID
-  # OR
-  email: "user@example.com"   # Primary email or alias
-  # OR
-  name: "Jane Doe"            # Fuzzy name search (least specific)
+  email: "user@example.com"
 ```
 
-Priority order: platform IDs > email > name. Platform IDs are exact matches; email checks aliases (case-insensitive); name is substring match.
+Email lookup is case-insensitive and checks the primary `email` column AND every entry in `emailAliases`.
 
 ### `manage-user` — CRUD operations
 
+Identities are managed via a declarative `identities: [{kind, externalId}, ...]` array:
+
+- On **create**: every entry in `identities` is linked (each emits `identity_added`).
+- On **update**: `identities` is treated as the full desired set. Helper computes a diff against the user's current identities — adds emit `identity_added`, removes emit `identity_removed`. Omit the field entirely to leave identities untouched.
+
 ```
 # Create a new user
 manage-user with:
   action: "create"
-  name: "Jane Doe"                          # Required
-  email: "jane@company.com"                 # Optional
-  role: "engineering lead"                  # Optional, free-form
-  slackUserId: "U12345"                     # Optional
-  githubUsername: "janedoe"                 # Optional
-  gitlabUsername: "janedoe"                 # Optional
-  linearUserId: "uuid-from-linear"          # Optional
-  emailAliases: ["jane.doe@company.com"]    # Optional
-  timezone: "America/New_York"              # Optional
-  notes: "Prefers async communication"      # Optional
+  name: "Jane Doe"                            # Required
+  email: "jane@company.com"                   # Optional
+  role: "engineering lead"                    # Optional, free-form
+  identities:                                 # Optional
+    - kind: "slack"
+      externalId: "U12345"
+    - kind: "github"
+      externalId: "janedoe"
+    - kind: "linear"
+      externalId: "uuid-from-linear"
+  emailAliases: ["jane.doe@company.com"]      # Optional
+  timezone: "America/New_York"                # Optional
+  notes: "Prefers async communication"        # Optional
+  dailyBudgetUsd: 25.0                        # Optional — null/omitted = unlimited
+  status: "active"                            # Optional — "invited" | "active" | "suspended"
 
 # List all users
 manage-user with:
@@ -69,11 +92,16 @@ manage-user with:
   action: "get"
   userId: "<uuid>"
 
-# Update a user (only send fields to change)
+# Update a user (declarative — pass the FULL desired set for `identities`)
 manage-user with:
   action: "update"
   userId: "<uuid>"
-  githubUsername: "new-username"
+  identities:                                 # FULL desired set; diff is applied
+    - kind: "slack"
+      externalId: "U12345"
+    - kind: "github"
+      externalId: "janedoe-new"               # renamed → identity_added + identity_removed
+  emailAliases: ["jane.doe@company.com", "jd@example.com"]   # emits email_added/email_removed per delta
 
 # Delete a user
 manage-user with:
@@ -83,37 +111,48 @@ manage-user with:
 
 ## Workflow: New Slack User
 
-1. Receive a message from an unknown Slack user (e.g., `slackUserId: "U_NEW123"`)
-2. Call `resolve-user` with `slackUserId: "U_NEW123"` — returns null
-3. Get the user's Slack profile (name, email) via `slack-read` or from the message metadata
-4. Call `resolve-user` with `email: "<their-email>"` — check if they exist under a different platform
-5. If found: call `manage-user` with `action: "update"` to add their `slackUserId`
-6. If not found: call `manage-user` with `action: "create"` including name, email, and slackUserId
+1. Receive a message from an unknown Slack user (e.g., external ID `U_NEW123`).
+2. Call `resolve-user` with `{kind: "slack", externalId: "U_NEW123"}` — returns null.
+3. Get the user's Slack profile (name, email) via `slack-read` or from the message metadata.
+4. Call `resolve-user` with `{email: "<their-email>"}` — check if they exist under a different platform.
+5. If found: call `manage-user` with `action: "update"`, passing the user's FULL identity set including the new Slack entry.
+6. If not found: call `manage-user` with `action: "create"`, including `name`, `email`, and `identities: [{kind: "slack", externalId: "U_NEW123"}]`.
 
 ## Workflow: New GitHub User
 
-1. Receive a webhook from an unknown GitHub user (e.g., `githubUsername: "octocat"`)
-2. Call `resolve-user` with `githubUsername: "octocat"` — returns null
-3. Call `manage-user` with `action: "create"` including at minimum `name` and `githubUsername`
-4. If you know their email (from the webhook payload), include it
+1. Receive a webhook from an unknown GitHub user (e.g., login `octocat`).
+2. Call `resolve-user` with `{kind: "github", externalId: "octocat"}` — returns null.
+3. Call `manage-user` with `action: "create"`, including at minimum `name` and `identities: [{kind: "github", externalId: "octocat"}]`.
+4. If you know their email (from the webhook payload), include it.
 
 ## Workflow: Linking Identities
 
 When you discover a known user is also active on another platform:
 
-1. Call `resolve-user` to find them by their known identity
-2. Call `manage-user` with `action: "update"` to add the new platform identity
+1. Call `resolve-user` to find them by their known identity.
+2. Call `manage-user` with `action: "update"`, passing the FULL desired `identities` set (existing + the new one).
+
+Example: You know "Jane" by Slack ID, and discover her GitHub login:
 
-Example: You know "Jane" by Slack ID, and discover her GitHub username:
 ```
-resolve-user slackUserId: "U_JANE"  → returns user with id "abc-123"
-manage-user action: "update" userId: "abc-123" githubUsername: "janedoe"
+resolve-user kind: "slack" externalId: "U_JANE"
+→ returns user with id "abc-123" (identities currently: [{kind: "slack", externalId: "U_JANE"}])
+
+manage-user action: "update" userId: "abc-123"
+  identities:
+    - kind: "slack"
+      externalId: "U_JANE"
+    - kind: "github"
+      externalId: "janedoe"
+→ adds GitHub identity (emit identity_added). Slack identity unchanged.
 ```
 
 ## Important Notes
 
 - `manage-user` is **lead-only** — workers cannot use it for any action (the lead check happens before action dispatch). Workers must use `resolve-user` for lookups.
-- `slackUserId`, `githubUsername`, `gitlabUsername`, and `linearUserId` have **unique constraints** — duplicates will error.
+- The `(kind, externalId)` PK on `user_external_ids` means the same identifier cannot be linked to two different users — a re-link to a different user surfaces as a PK collision (the operator can investigate via the People page merge flow).
 - Deleting a user clears `requestedByUserId` on all their associated tasks (sets to null).
-- Email aliases are case-insensitive for resolution.
-- The `preferredChannel` field defaults to `"slack"` and can be `"slack"`, `"email"`, `"github"`, or `"gitlab"`.
+- Email aliases are case-insensitive for resolution. Editing them via `manage-user update` emits `email_added` / `email_removed` events per delta.
+- The `preferredChannel` field defaults to `"slack"` and can be `"slack"`, `"email"`, `"github"`, `"gitlab"`, or any custom string.
+- `dailyBudgetUsd` is `null` = unlimited.
+- `status` lifecycle: `invited` → `active` → `suspended`. The CHECK constraint rejects other values.

package/src/agentmail/handlers.ts

@@ -3,8 +3,8 @@ import {
   getAgentById,
   getAgentMailInboxMapping,
   getAllAgents,
-  resolveUser,
 } from "../be/db";
+import { findOrCreateUserByEmail } from "../be/users";
 import { resolveTemplate } from "../prompts/resolver";
 import { createIngressBuffer } from "../tasks/additive-ingress";
 import { agentmailContextKey } from "../tasks/context-key";
@@ -73,6 +73,16 @@ function extractEmailFromField(from: string): string | undefined {
   return bareMatch?.[0]?.toLowerCase();
 }
 
+/**
+ * Extract display name from a from_ field like "Taras Yarema <t@desplega.ai>".
+ * Returns undefined if no display-name portion is present (bare address).
+ */
+function extractNameFromField(from: string): string | undefined {
+  const angleMatch = from.match(/^\s*"?([^"<]+?)"?\s*<[^>]+@[^>]+>\s*$/);
+  const name = angleMatch?.[1]?.trim();
+  return name && name.length > 0 ? name : undefined;
+}
+
 /**
  * Check if an inbox domain is allowed by the filter.
  * Returns true if no filter is set or the inbox domain matches.
@@ -159,9 +169,21 @@ export async function handleMessageReceived(
   const subject = message.subject || "(no subject)";
   const body = message.text || message.html || "";
 
-  // Resolve canonical user from sender email
+  // Resolve canonical user from sender email — per Q17.F, email is the
+  // primary identifier for inbound email events, so always auto-create when
+  // missing. findOrCreateUserByEmail emits identity_added (new row) or
+  // auto_merge (existing row matched via primary email or emailAliases).
   const senderEmail = extractEmailFromField(from);
-  const requestedByUserId = senderEmail ? resolveUser({ email: senderEmail })?.id : undefined;
+  const senderName = extractNameFromField(from);
+  let requestedByUserId: string | undefined;
+  if (senderEmail) {
+    const { user } = findOrCreateUserByEmail(
+      senderEmail,
+      { name: senderName ?? undefined },
+      { kind: "system", id: "webhook:agentmail" },
+    );
+    requestedByUserId = user.id;
+  }
   const preview = body.length > 500 ? `${body.substring(0, 500)}...` : body;
 
   // Emit workflow trigger event