@lightupai/polaris 0.0.33 → 0.0.35

package/docs/design-mentions.md

@@ -0,0 +1,133 @@
+# Design: @Mentions
+
+## Context
+
+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.
+
+## UX Goal
+
+As close to native Slack `@mention` as possible. The agent knows the team, resolves names accurately, and the tagged person gets a real notification.
+
+## Design Decisions
+
+1. **Discovery**: Agent has the full team member list available (via `polaris_team` tool). No guessing or fuzzy matching.
+2. **Resolution**: Agent resolves `@krishna` → Slack user ID inline when constructing the message. The team list is fetched at session start or on demand.
+3. **Semantics**: Start as a Slack mention (notification only). Extend later to invitations, review requests, tracked consultations.
+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).
+
+## Implementation
+
+### polaris_team tool
+
+New MCP tool that returns the org's team members with their Slack user IDs.
+
+```typescript
+{
+  name: "polaris_team",
+  description: "List team members with their Slack identities. Use this to resolve @mentions.",
+  inputSchema: { type: "object", properties: {} },
+}
+```
+
+Response:
+```json
+{
+  "members": [
+    { "name": "Krishna Patel", "participant_id": "user:krishna.patel", "slack_id": "U0XXXXXXX", "slack_display": "krishna" },
+    { "name": "Tuhin Roy", "participant_id": "user:tuhin.roy", "slack_id": "U0YYYYYYY", "slack_display": "tuhin" },
+    { "name": "Manu Bansal", "participant_id": "user:manu.bansal", "slack_id": "UCUHHNJDT", "slack_display": "manu" }
+  ]
+}
+```
+
+### Data source
+
+The team list comes from:
+1. **Slack workspace members** — `users.list` API call, cached by the bridge/API
+2. **Polaris users table** — users who have signed up, with their participant IDs
+
+The API needs a new endpoint: `GET /team` that joins Slack workspace members with Polaris users. The daemon proxies this like other API calls.
+
+### Mention in polaris_reply
+
+When the agent calls `polaris_reply` with text containing `<@UXXXXXXX>`, the bridge posts it as-is — Slack renders the mention natively.
+
+The agent's flow:
+1. User says "tag krishna about this auth approach"
+2. Agent calls `polaris_team` (or uses cached result)
+3. Finds Krishna → `slack_id: U0XXXXXXX`
+4. Calls `polaris_reply` with `"<@U0XXXXXXX> what do you think about this auth approach?"`
+5. Bridge posts to Slack, Krishna gets a notification
+
+### Mention resolution in the bridge (outbound)
+
+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.
+
+Resolution logic:
+1. Scan message text for `@word` patterns
+2. Look up each word against Slack display names (cached)
+3. Replace with `<@slack_id>` if unique match
+4. Leave as plain text if no match or ambiguous
+
+### Inbound mention tracking
+
+When a Slack message is injected into a session and contains `<@UXXXXXXX>` patterns:
+1. The bridge resolves the Slack ID to a display name
+2. The inject event payload includes a `mentions` array: `["user:krishna.patel"]`
+3. The floor records who was consulted on what
+
+This is metadata on the event — no schema change needed (it goes in the JSONB payload).
+
+## Caching
+
+The Slack user list is expensive to fetch (paginated API call). Cache it:
+- **Bridge**: on startup and every 30 minutes
+- **API /team endpoint**: cache for 5 minutes
+- **Agent**: fetches once per session via `polaris_team`, uses for all mentions in that session
+
+## Skill update
+
+The skill instructions should tell the agent:
+- When the user mentions someone by name, call `polaris_team` to resolve their Slack ID
+- Use `<@slack_id>` format in `polaris_reply` messages
+- If unsure which person, present the matches and ask
+
+## UX Flow (v1)
+
+Claude Code CLI's `@` is reserved for file references. Instead, use a conversational `/polaris tag` command:
+
+```
+User: /polaris tag
+Agent: Who would you like to tag?
+  1. Krishna Patel (@krishna)
+  2. Tuhin Roy (@tuhin)
+  3. Laura Mowry (@laura)
+User: 1
+Agent: What message?
+User: what do you think about this auth approach?
+Agent: → Posted to #polaris-dev: @krishna what do you think about this auth approach?
+```
+
+The agent calls `polaris_team` to get the list, presents it, and calls `polaris_reply` with the resolved Slack mention.
+
+### Shorthand (future)
+
+Once the flow works, add inline shorthand so the user can skip the interactive steps:
+- `/polaris tag krishna what do you think?` — resolves and posts in one step
+- Custom Claude Code `@` completion provider (feature request to Anthropic)
+
+## Future extensions
+
+- **Mention as invitation**: tagging someone could auto-invite them as an advisor to the session
+- **Review request**: `@krishna review this PR` creates a tracked review request
+- **Mention analytics**: dashboard shows who was consulted most, on which projects
+- **Agent-to-person tagging**: named agents like Dean could tag humans when they need input
+
+## Implementation Order
+
+1. `GET /team` API endpoint (join Slack users with Polaris users)
+2. Daemon `/team` proxy endpoint
+3. `polaris_team` MCP tool
+4. Bridge fallback mention resolution (outbound)
+5. Inbound mention tracking in inject events
+6. Skill update with mention instructions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightupai/polaris",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "type": "module",
   "bin": {
     "polaris": "bin/polaris",

package/skills/polaris/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: polaris
 description: Connect to a Polaris multiplayer collaboration session
-allowed-tools: polaris_connect polaris_disconnect polaris_status polaris_reply polaris_context polaris_rename polaris_backfill
-argument-hint: [join #channel | backfill [duration] | rename <new-name> | disconnect | (no args for status)]
+allowed-tools: polaris_connect polaris_disconnect polaris_status polaris_reply polaris_context polaris_rename polaris_backfill polaris_team
+argument-hint: [join #channel | tag [name] | backfill [duration] | rename <new-name> | disconnect | (no args for status)]
 ---
 
 ## Polaris — Multiplayer Collaboration
@@ -22,6 +22,13 @@ Based on the arguments provided, do ONE of the following:
 1. Call `polaris_rename` with the new name
 2. Report the result
 
+**`/polaris tag [name]`** — Tag a teammate on Slack:
+1. Call `polaris_team` to get the team list with Slack identities
+2. If a name was given, find the matching member. If no name, present a numbered list for the user to pick.
+3. Ask the user what message to send (if not already provided)
+4. Call `polaris_reply` with the message, including the Slack mention in `<@SLACK_ID>` format
+5. Confirm the message was sent
+
 **`/polaris backfill [duration]`** — Recover lost events:
 1. Call `polaris_backfill` with the optional duration (e.g., `2h`, `30m`)
 2. Report how many events were recovered

package/src/client/client.ts

@@ -110,6 +110,14 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["session"],
       },
     },
+    {
+      name: "polaris_team",
+      description: "List team members with their Slack identities. Use this to resolve @mentions before posting to Slack.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {},
+      },
+    },
     {
       name: "polaris_backfill",
       description: "Recover lost events from local daemon logs. Use when events were lost due to disconnection or API downtime.",
@@ -255,6 +263,25 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     }
   }
 
+  if (name === "polaris_team") {
+    try {
+      const res = await daemonGet("/team");
+      if (res.ok) {
+        const body = await res.json() as { members: Array<{ name: string; participant_id: string; slack_id: string | null; slack_display: string | null }> };
+        if (body.members.length === 0) {
+          return { content: [{ type: "text", text: "No team members found." }] };
+        }
+        const list = body.members.map((m, i) =>
+          `  ${i + 1}. ${m.name} (${m.participant_id})${m.slack_display ? ` — @${m.slack_display}` : ""}${m.slack_id ? ` [${m.slack_id}]` : ""}`
+        ).join("\n");
+        return { content: [{ type: "text", text: `Team members:\n${list}` }] };
+      }
+      return { content: [{ type: "text", text: "Failed to fetch team list." }] };
+    } catch {
+      return { content: [{ type: "text", text: "Failed to reach the daemon." }] };
+    }
+  }
+
   if (name === "polaris_backfill") {
     if (!currentProject) {
       return { content: [{ type: "text", text: "Not connected to a Polaris session. Use polaris_connect first." }] };

package/src/daemon/daemon.ts

@@ -669,6 +669,21 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
         }
       }
 
+      // GET /team — list team members with Slack identities
+      if (method === "GET" && pathname === "/team") {
+        try {
+          const serviceUrl = getServiceUrl();
+          const res = await fetch(`${serviceUrl}/team`, {
+            headers: await authHeaders(),
+          });
+          if (!res.ok) return error("Failed to fetch team", res.status);
+          const data = await res.json();
+          return json(data);
+        } catch {
+          return error("API unreachable", 503);
+        }
+      }
+
       // POST /backfill — recover lost events from daemon log
       if (method === "POST" && pathname === "/backfill") {
         try {

package/src/service/db.ts

@@ -189,6 +189,11 @@ export async function upsertUser(sql: Sql, id: string, email: string, name: stri
   return { ...row, created_at: row.created_at.toISOString() } as User;
 }
 
+export async function listUsers(sql: Sql, orgId: string): Promise<User[]> {
+  const rows = await sql`SELECT * FROM users WHERE org_id = ${orgId} ORDER BY name ASC`;
+  return rows.map((r) => ({ ...r, created_at: r.created_at.toISOString() }) as User);
+}
+
 // --- Projects (org-scoped) ---
 
 export async function createProject(sql: Sql, orgId: string, name: string): Promise<Project> {

package/src/service/server.ts

@@ -444,6 +444,50 @@ export async function startServer(opts: {
         return json({ status: "claimed", driver: parsed.data.driver, session: params.sess });
       }
 
+      // GET /team — list org members with Slack identities
+      if (method === "GET" && pathname === "/team") {
+        const { listUsers, getOrg: getOrgFn } = await import("./db");
+        const users = await listUsers(sql, orgId);
+        const org = await getOrgFn(sql, orgId);
+
+        // Resolve Slack user info if bot token available
+        let slackMembers: Array<{ id: string; name: string; display_name: string }> = [];
+        if (org?.slack_bot_token) {
+          try {
+            const slackRes = await fetch("https://slack.com/api/users.list?limit=200", {
+              headers: { Authorization: `Bearer ${org.slack_bot_token}` },
+            });
+            if (slackRes.ok) {
+              const slackData = (await slackRes.json()) as { members?: Array<{ id: string; real_name?: string; profile?: { display_name?: string }; deleted?: boolean; is_bot?: boolean }> };
+              slackMembers = (slackData.members ?? [])
+                .filter((m) => !m.deleted && !m.is_bot)
+                .map((m) => ({
+                  id: m.id,
+                  name: m.real_name ?? "",
+                  display_name: m.profile?.display_name ?? "",
+                }));
+            }
+          } catch { /* Slack API unavailable */ }
+        }
+
+        // Join Polaris users with Slack members by email match or name match
+        const team = users.map((u) => {
+          const slack = slackMembers.find((m) =>
+            m.name.toLowerCase() === u.name.toLowerCase() ||
+            m.display_name.toLowerCase() === u.name.toLowerCase().replace(/\s+/g, ".")
+          );
+          return {
+            name: u.name,
+            participant_id: u.participant_id,
+            email: u.email,
+            slack_id: slack?.id ?? null,
+            slack_display: slack?.display_name || slack?.name || null,
+          };
+        });
+
+        return json({ members: team });
+      }
+
       if (method === "GET" && pathname === "/status") {
         return json({ ok: true, version: "0.0.1" });
       }

package/src/web/pages.ts

@@ -11,10 +11,11 @@ export function renderLandingPage(): string {
       <!-- Hero -->
       <div class="pt-24 pb-16">
         <h1 class="text-4xl font-bold tracking-tight text-gray-900 sm:text-5xl">
-          Multiplayer collaboration<br>for Claude Code
+          Realtime multiplayer Claude Code<br>sessions and knowledge capture
         </h1>
-        <p class="mt-4 text-lg text-gray-500 max-w-xl">
-          Your teammates see what your agent is doing. They can jump in from Slack and steer it in real time.
+        <p class="mt-2 text-sm font-medium text-polaris-600">It's like Gong for AI.</p>
+        <p class="mt-4 text-lg text-gray-500 max-w-2xl">
+          Move your Claude Code sessions out of private windows and into a shared workspace in Slack. Polaris runs quietly in the background to document your sessions automatically, turning isolated chats into a continuous stream of team intelligence.
         </p>
         <div class="mt-8 flex items-center gap-4">
           <a href="#get-started" class="px-5 py-2.5 bg-gray-900 text-white text-sm font-medium rounded-lg hover:bg-gray-800 transition">Get started</a>

package/tests/web.test.ts

@@ -275,7 +275,7 @@ describe("routes", () => {
     const res = await app.request("/");
     expect(res.status).toBe(200);
     const body = await res.text();
-    expect(body).toContain("Multiplayer collaboration");
+    expect(body).toContain("Polaris");
   });
 
   test("GET /preview returns 200", async () => {