@lightupai/polaris 0.0.33 → 0.0.34
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/design-mentions.md +109 -0
- package/package.json +1 -1
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Design: @Mentions
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
|
|
5
|
+
Users want to tag teammates while working in a coding session — "get Krishna's opinion on this approach." The tag should be a real Slack mention that triggers a notification, not plain text.
|
|
6
|
+
|
|
7
|
+
## UX Goal
|
|
8
|
+
|
|
9
|
+
As close to native Slack `@mention` as possible. The agent knows the team, resolves names accurately, and the tagged person gets a real notification.
|
|
10
|
+
|
|
11
|
+
## Design Decisions
|
|
12
|
+
|
|
13
|
+
1. **Discovery**: Agent has the full team member list available (via `polaris_team` tool). No guessing or fuzzy matching.
|
|
14
|
+
2. **Resolution**: Agent resolves `@krishna` → Slack user ID inline when constructing the message. The team list is fetched at session start or on demand.
|
|
15
|
+
3. **Semantics**: Start as a Slack mention (notification only). Extend later to invitations, review requests, tracked consultations.
|
|
16
|
+
4. **Inbound mentions**: When Slack users @mention other users in messages to sessions, the floor captures the mention semantically (who was tagged, in what context).
|
|
17
|
+
|
|
18
|
+
## Implementation
|
|
19
|
+
|
|
20
|
+
### polaris_team tool
|
|
21
|
+
|
|
22
|
+
New MCP tool that returns the org's team members with their Slack user IDs.
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
{
|
|
26
|
+
name: "polaris_team",
|
|
27
|
+
description: "List team members with their Slack identities. Use this to resolve @mentions.",
|
|
28
|
+
inputSchema: { type: "object", properties: {} },
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Response:
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"members": [
|
|
36
|
+
{ "name": "Krishna Patel", "participant_id": "user:krishna.patel", "slack_id": "U0XXXXXXX", "slack_display": "krishna" },
|
|
37
|
+
{ "name": "Tuhin Roy", "participant_id": "user:tuhin.roy", "slack_id": "U0YYYYYYY", "slack_display": "tuhin" },
|
|
38
|
+
{ "name": "Manu Bansal", "participant_id": "user:manu.bansal", "slack_id": "UCUHHNJDT", "slack_display": "manu" }
|
|
39
|
+
]
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Data source
|
|
44
|
+
|
|
45
|
+
The team list comes from:
|
|
46
|
+
1. **Slack workspace members** — `users.list` API call, cached by the bridge/API
|
|
47
|
+
2. **Polaris users table** — users who have signed up, with their participant IDs
|
|
48
|
+
|
|
49
|
+
The API needs a new endpoint: `GET /team` that joins Slack workspace members with Polaris users. The daemon proxies this like other API calls.
|
|
50
|
+
|
|
51
|
+
### Mention in polaris_reply
|
|
52
|
+
|
|
53
|
+
When the agent calls `polaris_reply` with text containing `<@UXXXXXXX>`, the bridge posts it as-is — Slack renders the mention natively.
|
|
54
|
+
|
|
55
|
+
The agent's flow:
|
|
56
|
+
1. User says "tag krishna about this auth approach"
|
|
57
|
+
2. Agent calls `polaris_team` (or uses cached result)
|
|
58
|
+
3. Finds Krishna → `slack_id: U0XXXXXXX`
|
|
59
|
+
4. Calls `polaris_reply` with `"<@U0XXXXXXX> what do you think about this auth approach?"`
|
|
60
|
+
5. Bridge posts to Slack, Krishna gets a notification
|
|
61
|
+
|
|
62
|
+
### Mention resolution in the bridge (outbound)
|
|
63
|
+
|
|
64
|
+
As a fallback, the bridge can also resolve `@krishna` → `<@U0XXXXXXX>` in message text before posting. This handles cases where the agent or hooks include plain `@name` without resolution.
|
|
65
|
+
|
|
66
|
+
Resolution logic:
|
|
67
|
+
1. Scan message text for `@word` patterns
|
|
68
|
+
2. Look up each word against Slack display names (cached)
|
|
69
|
+
3. Replace with `<@slack_id>` if unique match
|
|
70
|
+
4. Leave as plain text if no match or ambiguous
|
|
71
|
+
|
|
72
|
+
### Inbound mention tracking
|
|
73
|
+
|
|
74
|
+
When a Slack message is injected into a session and contains `<@UXXXXXXX>` patterns:
|
|
75
|
+
1. The bridge resolves the Slack ID to a display name
|
|
76
|
+
2. The inject event payload includes a `mentions` array: `["user:krishna.patel"]`
|
|
77
|
+
3. The floor records who was consulted on what
|
|
78
|
+
|
|
79
|
+
This is metadata on the event — no schema change needed (it goes in the JSONB payload).
|
|
80
|
+
|
|
81
|
+
## Caching
|
|
82
|
+
|
|
83
|
+
The Slack user list is expensive to fetch (paginated API call). Cache it:
|
|
84
|
+
- **Bridge**: on startup and every 30 minutes
|
|
85
|
+
- **API /team endpoint**: cache for 5 minutes
|
|
86
|
+
- **Agent**: fetches once per session via `polaris_team`, uses for all mentions in that session
|
|
87
|
+
|
|
88
|
+
## Skill update
|
|
89
|
+
|
|
90
|
+
The skill instructions should tell the agent:
|
|
91
|
+
- When the user mentions someone by name, call `polaris_team` to resolve their Slack ID
|
|
92
|
+
- Use `<@slack_id>` format in `polaris_reply` messages
|
|
93
|
+
- If unsure which person, present the matches and ask
|
|
94
|
+
|
|
95
|
+
## Future extensions
|
|
96
|
+
|
|
97
|
+
- **Mention as invitation**: tagging someone could auto-invite them as an advisor to the session
|
|
98
|
+
- **Review request**: `@krishna review this PR` creates a tracked review request
|
|
99
|
+
- **Mention analytics**: dashboard shows who was consulted most, on which projects
|
|
100
|
+
- **Agent-to-person tagging**: named agents like Dean could tag humans when they need input
|
|
101
|
+
|
|
102
|
+
## Implementation Order
|
|
103
|
+
|
|
104
|
+
1. `GET /team` API endpoint (join Slack users with Polaris users)
|
|
105
|
+
2. Daemon `/team` proxy endpoint
|
|
106
|
+
3. `polaris_team` MCP tool
|
|
107
|
+
4. Bridge fallback mention resolution (outbound)
|
|
108
|
+
5. Inbound mention tracking in inject events
|
|
109
|
+
6. Skill update with mention instructions
|