@lightupai/polaris 0.0.12 → 0.0.13

package/docs/design-named-agents.md

@@ -0,0 +1,303 @@
+# Design: Named Agents as Teammates
+
+## Vision
+
+Named agents are persistent, specialized participants in the Polaris workspace. They're peers alongside humans — they observe, contribute, and can be addressed by name. Unlike human sessions (transient, one project at a time), named agents are long-running services that participate across multiple projects simultaneously.
+
+## Examples
+
+| Agent | Identity | Specialty | Joins projects that... |
+|-------|----------|-----------|----------------------|
+| Dean | `agent:dean` | Data engineering, SQL, pipelines | interact with databases or data warehouses |
+| Martha | `agent:martha` | Marketing copy, campaigns, email | need marketing content or strategy |
+| Sean | `agent:sean` | Sales enablement, CRM, outreach | involve sales workflows or customer data |
+| Sage | `agent:sage` | Security review, compliance | touch auth, encryption, or PII handling |
+
+## How They Differ from Human Sessions
+
+| Dimension | Human session | Named agent |
+|-----------|--------------|-------------|
+| Lifecycle | Transient — open, work, close | Persistent — always running |
+| Projects | One at a time (join/leave) | Multiple simultaneously |
+| Hosting | Client machine (Claude Code, Cursor) | Server-side (cloud container, sandbox) |
+| Identity | `user:manu.bansal` | `agent:dean` |
+| Invocation | Manual (`/polaris join`) | Auto-join on invite or project match |
+| Driver role | Can be driver | Typically advisor, sometimes driver |
+| Hooks | Captures via local hooks | Events posted directly via API |
+
+## Participation Model
+
+A named agent's relationship to a project:
+
+```
+                    ┌─────────────────┐
+                    │   THE FLOOR     │
+                    │                 │
+                    │  polaris-dev    │
+                    │  ┌───────────┐  │
+                    │  │ manu      │──── driver (human, transient)
+                    │  │ dean      │──── advisor (agent, persistent)
+                    │  │ sage      │──── advisor (agent, persistent)
+                    │  └───────────┘  │
+                    │                 │
+                    │  data-pipeline  │
+                    │  ┌───────────┐  │
+                    │  │ alice     │──── driver (human, transient)
+                    │  │ dean      │──── advisor (agent, persistent)
+                    │  └───────────┘  │
+                    │                 │
+                    └─────────────────┘
+```
+
+Dean appears in both projects. He monitors the event stream and responds when data-related questions arise or when addressed directly.
+
+## Agent Behaviors
+
+### Passive monitoring
+Agent watches the event stream. When it sees a prompt or response related to its domain, it can inject an advisory message:
+
+```
+[user:manu.bansal] I need to add a Snowflake table for user events
+[agent:dean] → fxm: The user_events schema already exists in warehouse.analytics. 
+              Here's the current DDL: ...
+```
+
+### Direct addressing
+A human or another agent addresses the agent by name on Slack or in a session:
+
+```
+@dean what tables have PII columns?
+```
+
+### Autonomous work
+Agent is assigned as driver of its own session. It works independently, posting progress to the floor. Humans observe and advise.
+
+## Identity Model
+
+### Current
+```
+ParticipantId = /^(user|agent):[a-z0-9][a-z0-9._-]*$/
+```
+This already supports `agent:dean`. No change needed to the type system.
+
+### Agent registry (new)
+A table or config that defines named agents:
+
+```
+agents:
+  - id: agent:dean
+    name: Dean
+    display_name: "Dean (Data)"
+    icon: 📊
+    description: "Data engineering specialist"
+    skills: [sql, snowflake, dbt, airflow]
+    auto_join: [projects with tag "data"]
+    hosting: server  # or "sandbox"
+```
+
+This is metadata — it tells the system who Dean is, what icon to show on Slack, and which projects he should auto-join.
+
+### Slack personas
+Named agents already work with our persona system:
+- `agent:dean` → username: "Dean (Data)", icon: 📊
+- `agent:martha` → username: "Martha (Marketing)", icon: 📣
+
+The `displayName()` function in `format.ts` handles this. Would need a lookup from the agent registry instead of the current string parsing.
+
+## Identity Model
+
+Every interaction on the floor has two distinct identities: the human and the agent. These are never conflated.
+
+### Identity types
+
+| Prefix | Meaning | Examples |
+|--------|---------|---------|
+| `user:*` | A human | `user:manu.bansal`, `user:alice.chen` |
+| `agent:*` | An AI agent | `agent:claude`, `agent:dean`, `agent:cursor` |
+| `slack:*` | A Slack user (advisor) | `slack:krishna` |
+
+### Who sends what
+
+In a coding session, the human and agent alternate. The `sender` field must reflect who actually produced the content:
+
+| Hook event | Sender | Why |
+|-----------|--------|-----|
+| `UserPromptSubmit` | `user:manu.bansal` | The human typed the prompt |
+| `Stop` | `agent:claude` | The agent produced the response |
+| `PreToolUse` | `agent:claude` | The agent decided to use a tool |
+| `PostToolUse` | `agent:claude` | The agent received the tool result |
+| `inject` | `slack:krishna` or `user:alice.chen` | An advisor sent a message |
+
+### Agent identity in a session
+
+When a human connects a session, two identities are established:
+- **Driver** (human): `user:manu.bansal` — from the participant ID in credentials
+- **Agent**: `agent:claude` — the coding tool's agent identity
+
+The agent identity could be:
+- Generic: `agent:claude`, `agent:cursor`, `agent:copilot` (identifies the tool)
+- Named: `agent:dean` (a named specialist agent)
+- Session-specific: derived automatically from the tool being used
+
+For local coding sessions, the agent identity defaults to the tool name (Claude Code → `agent:claude`). For named agents like Dean, it's explicitly `agent:dean`.
+
+### On Slack
+
+The Slack formatter uses the sender identity to pick the persona:
+- `user:manu.bansal` → "Manu Bansal (session-name)" with 👤
+- `agent:claude` → "Claude (session-name)" with 🤖
+- `agent:dean` → "Dean (Data)" with 📊 (from agent registry)
+- `slack:krishna` → "Krishna" with 💬
+
+This makes the conversation on Slack clearly distinguish human prompts from agent responses.
+
+## Architecture: Daemon as Universal Nexthop
+
+All participants — human sessions and cloud agents alike — connect through a daemon. The daemon is the universal transit layer.
+
+### Why always a daemon
+
+1. **Fault tolerance**: If the API is slow or down, the daemon buffers events locally. No data loss.
+2. **Auth**: Daemon handles token management. Agents and tools don't need to deal with auth.
+3. **Cutover**: Switching from dev to prod is a daemon restart. Nothing else changes.
+4. **Identity**: Daemon knows both the human and agent identity for a session. It stamps the correct sender on each event.
+5. **Logging**: Every event passes through the daemon JSONL log for recovery.
+
+### Local agent (human coding session)
+
+```
+┌──────────────┐     ┌──────────┐     ┌─────────────┐
+│ Claude Code  │────▶│  Daemon  │────▶│ Polaris API │
+│              │     │ :4322    │     │             │
+│ hooks fire   │     │          │     │             │
+│ MCP tools    │     │ buffers  │     │             │
+│              │     │ auth     │     │             │
+│ on laptop    │     │ logging  │     │ on Hetzner  │
+└──────────────┘     └──────────┘     └─────────────┘
+```
+
+### Cloud agent (named agent like Dean)
+
+```
+┌──────────────┐     ┌──────────┐     ┌─────────────┐
+│ Dean process │────▶│  Daemon  │────▶│ Polaris API │
+│              │     │ (sidecar)│     │             │
+│ listens for  │     │          │     │             │
+│ events,      │     │ buffers  │     │             │
+│ responds     │     │ auth     │     │             │
+│              │     │ logging  │     │             │
+│ on server    │     └──────────┘     │ on Hetzner  │
+└──────────────┘                      └─────────────┘
+```
+
+Same architecture. The daemon runs as a sidecar container for cloud agents. The agent process talks to localhost, same as a human's Claude Code talks to localhost.
+
+### Comparison
+
+| Dimension | Local agent | Cloud agent |
+|-----------|------------|-------------|
+| Agent process | Claude Code / Cursor | Custom process or Claude API |
+| Daemon | Runs on laptop | Sidecar container |
+| Hook capture | Shell hooks (capture.sh) | Agent posts events directly to daemon |
+| Human in the loop | Yes (the user) | Optional (can run autonomous) |
+| Identity | `user:*` + `agent:claude` | `agent:dean` (no human) |
+| Lifecycle | Transient | Persistent |
+| Session creation | `/polaris join` | Auto-join or API call |
+
+From the floor's perspective: identical. Events flow in, show up on Slack, appear on the dashboard. The source doesn't matter.
+
+## Hosting Options
+
+Given the daemon-always architecture, hosting becomes about where the daemon + agent pair runs:
+
+### Option A: Self-hosted (any machine)
+Agent + daemon run on any server the customer controls. Agent connects to daemon on localhost, daemon connects to Polaris API.
+
+### Option B: Polaris-hosted
+Polaris spawns a container pair (agent + daemon sidecar) in its own infrastructure. Admin configures the agent in the dashboard.
+
+### Recommendation
+Start with **Option A** — self-hosted. The customer runs the agent wherever they want. Polaris doesn't need to manage compute. Option B comes later when customers want managed agents.
+
+## What to Implement Now
+
+### 1. Agent registry table (small, foundational)
+```sql
+CREATE TABLE agents (
+  id TEXT PRIMARY KEY,            -- e.g., "agent:dean"
+  org_id TEXT NOT NULL REFERENCES orgs(id),
+  name TEXT NOT NULL,             -- "Dean"
+  display_name TEXT,              -- "Dean (Data)"
+  icon TEXT,                      -- emoji or URL
+  description TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+Just metadata. No behavior yet. Used by the Slack formatter for richer personas.
+
+### 2. Update Slack formatting to use agent registry
+Instead of deriving "Agent: Dean" from string parsing, look up the agent's display name and icon from the registry.
+
+### 3. Agent identity in the dashboard
+Show registered agents alongside users in the profile/team section.
+
+### Defer for later
+- Auto-join logic (which projects an agent participates in)
+- Agent hosting (Option B WebSocket client)
+- Agent spawning and lifecycle management
+- Skills/capability matching
+- Autonomous driver mode
+
+## Context Model
+
+### Phase 1: Shared context, no isolation (ship first)
+One Dean instance per org. Dean participates in all projects and accumulates context across them. No boundaries between projects.
+
+This matches the small-team reality: one data expert who knows everything about the company's data. Everyone has the same access level. Dean's cross-project knowledge is a feature, not a bug — "Dean, you set up the schema for Project A, can we reuse it in Project B?"
+
+### Phase 2: Per-project isolation (add when needed)
+As the team grows and projects have different confidentiality levels, Dean gets isolated per-project instances. Each instance only sees its own project's context.
+
+Dean's identity stays the same on Slack ("Dean (Data)"), but behind the name, each project gets a fresh instance with no cross-project memory.
+
+### Phase 3: Controlled sharing (enterprise)
+Admin-curated shared knowledge base (schemas, conventions, docs) that all Dean instances can read. Per-project context stays isolated. Sharing policies control what crosses boundaries.
+
+### Phase 4: Agent hierarchy (northstar)
+Dean becomes the head of a data team. He delegates to specialized subagents:
+
+```
+agent:dean (Data Lead)
+  ├── agent:dean.snowflake   — Snowflake schema, queries, optimization
+  ├── agent:dean.spark       — Spark jobs, pipeline tuning
+  ├── agent:dean.dbt         — dbt models, lineage, testing
+  └── agent:dean.quality     — Data quality checks, anomaly detection
+```
+
+Dean is the public face — humans address "Dean" and he routes to the right subagent. Subagents have:
+- **Limited context**: only their specialty area, not the full org
+- **Project isolation**: each subagent instance is scoped to one project
+- **Dean as arbiter**: Dean sees across all subagents and synthesizes answers that span specialties
+
+On the floor and Slack, subagent messages appear as "Dean (Data)" — the hierarchy is an implementation detail. Humans don't need to know which subagent answered.
+
+When to introduce hierarchy:
+- Team has 50+ projects and one Dean can't keep up
+- Different projects need different levels of data expertise
+- Compliance requires that certain subagents don't see certain data
+- Response latency matters — subagents work in parallel
+
+### Design principle
+Start with the simplest model that matches how small teams actually work. Add isolation as a response to real customer needs, not speculatively. The architecture supports all phases — the difference is what context gets loaded when Dean starts participating in a project.
+
+## Open Questions
+
+1. **Multi-project sessions**: Dean is in all projects simultaneously. One session per project (`dean-polaris-dev`, `dean-data-pipeline`) keeps the model simple and isolation-ready for Phase 2.
+
+2. **Agent-to-agent communication**: Can Dean ask Sage a question? The floor already supports this — any participant can inject into any session. But should there be a direct channel?
+
+3. **Rate limiting**: A busy agent in 10 projects could flood the floor. Should agents have throttling or priority levels?
+
+4. **Configuration UI**: Where do admins define named agents? Dashboard page? Config file? API?
+
+5. **Credentials/secrets**: Dean needs database credentials. Sage needs access to security tools. How are agent-specific secrets managed?

package/docs/design-sessions.md

@@ -0,0 +1,143 @@
+# Design: Sessions
+
+## What is a Session
+
+A session is a single continuous conversation thread between a human and/or an agent. It represents a unit of work with continuity of context — the back-and-forth of prompts, responses, tool calls, and advisor messages that together tell the story of a task being worked on.
+
+A session is **not** a person, a device, or a feature. People come and go (handoff). Devices reconnect. Features span multiple sessions. The session is the conversation itself.
+
+## Session Identity
+
+### Name
+A short random slug: `s-7a3f`, `s-b2e1`, `s-c9d0`.
+
+- 4 hex characters (65K possibilities per project)
+- Generated by the daemon on join
+- No human identity, no timestamp, no semantics
+- Collision on create → regenerate and retry (max 3 attempts)
+- Users can still pass an explicit name for scripts/tests
+
+### Why not human-readable names?
+Earlier designs used `manu-260610a` or user-chosen names like `fxm`. Problems:
+- User-chosen names collide (two people pick `fxm`)
+- Identity-based names break on driver handoff
+- Date-based names imply lifecycle boundaries that don't exist
+- Named sessions create an obligation to manage them (rename, archive, clean up)
+
+Random slugs are disposable. Nobody manages them. They're just routing handles.
+
+## Participants
+
+A session has participants, not owners. At any point:
+
+| Role | Who | Count |
+|------|-----|-------|
+| Driver | The human or agent actively working in the session | Exactly one (or none if open) |
+| Agent | The AI tool responding to the driver | One per session |
+| Advisors | Observers who can inject messages | Zero or more |
+
+### Driver
+The driver is the entity currently "at the keyboard." For a local coding session, the human starts as driver. For an autonomous agent session, the agent is the driver.
+
+Drivers can hand off: `POST /projects/:proj/sessions/:sess/handoff` clears the driver, `POST /projects/:proj/sessions/:sess/driver` claims it. The session continues — same thread, new driver.
+
+### Agent identity
+Every session has an associated agent identity, even if the agent hasn't responded yet. For local coding sessions, this defaults to the tool name (`agent:claude`, `agent:cursor`). For named agents, it's explicit (`agent:dean`).
+
+The agent identity is set on session creation and stored alongside the driver.
+
+### Advisors
+Anyone who injects a message into a session is an advisor. Advisors are not registered — they're identified by their sender identity on the inject event (`slack:krishna`, `user:alice.chen`).
+
+## Lifecycle
+
+### Creation
+A session is created when someone runs `/polaris join <project>`. The daemon:
+1. Generates a random slug
+2. Calls the API to create the session with the driver and agent identity
+3. Returns the session name to the user
+
+### Active use
+Events flow into the session: prompts, responses, tool calls, advisor injections. The daemon stamps the correct sender identity on each event (human or agent).
+
+### Idle
+A session with no events for some period is idle. No special handling — it just sits there. The conversation can resume at any time.
+
+### Handoff
+The driver releases the session. Another human or agent claims it. The conversation thread continues with a new driver. This is useful for:
+- Shift changes ("I'm done for the day, Alice takes over")
+- Escalation ("This needs a senior engineer")
+- Agent takeover ("Let the agent finish this autonomously")
+
+### Closure
+There is no explicit close. Sessions are never deleted. They age out of relevance naturally. The dashboard could eventually hide sessions with no recent activity, but the data persists.
+
+### Reconnection
+If a daemon restarts or a user's machine disconnects, they can rejoin the same session by name (if they know it) or start a new one. Starting a new session is preferred — it's a clean conversation thread.
+
+## Relationship to Projects
+
+A session belongs to exactly one project. A project has many sessions. Sessions within the same project share the floor — their events are all visible to each other and to Slack.
+
+```
+Project: polaris-dev
+  ├── Session s-7a3f (driver: user:manu.bansal, agent: agent:claude)
+  ├── Session s-b2e1 (driver: user:alice.chen, agent: agent:claude)
+  └── Session s-c9d0 (driver: agent:dean, agent: agent:dean)
+```
+
+## What Shows on Slack
+
+The Slack channel is per project. Events from all sessions in the project appear in the same channel. The session name appears in the poster's display name:
+
+```
+Manu Bansal (s-7a3f): Can we add a retry mechanism to the ETL pipeline?
+Claude (s-7a3f): I'll add exponential backoff to the S3 upload step...
+Alice Chen (s-b2e1): I'm working on the monitoring dashboard for this pipeline
+Dean (Data) (s-c9d0): The pipeline's target table has a NOT NULL constraint on...
+```
+
+The session slug disambiguates when multiple sessions are active.
+
+## What Shows on the Dashboard
+
+The project card lists sessions with:
+- Session name (slug)
+- Current driver
+- Agent identity
+- Prompt count
+- Last activity timestamp
+
+```
+polaris-dev                          #polaris-dev
+├── s-7a3f  Manu Bansal   Claude    34 prompts  2 min ago
+├── s-b2e1  Alice Chen    Claude    12 prompts  15 min ago
+└── s-c9d0  Dean (Data)   Dean       8 prompts  1 min ago
+```
+
+## Schema
+
+Current sessions table (no changes needed for naming):
+```sql
+CREATE TABLE sessions (
+  name TEXT NOT NULL,
+  project_id UUID NOT NULL REFERENCES projects(id),
+  org_id TEXT NOT NULL,
+  driver TEXT,              -- participant ID of current driver (nullable)
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (project_id, name)
+);
+```
+
+Future addition for agent identity:
+```sql
+ALTER TABLE sessions ADD COLUMN agent TEXT;  -- e.g., "agent:claude", "agent:dean"
+```
+
+## Open Questions
+
+1. **Session display name**: Should users be able to attach a label to a session after creation? e.g., `s-7a3f → "ETL retry fix"`. Optional metadata, not the primary key.
+
+2. **Session limit**: Should there be a max number of active sessions per project? Probably not — let it grow naturally.
+
+3. **Session search**: As sessions accumulate, how do you find a past conversation? By date? By participant? By content? This is a future search/filter feature.

package/package.json

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

package/skills/polaris/SKILL.md

@@ -2,7 +2,7 @@
 name: polaris
 description: Connect to a Polaris multiplayer collaboration session
 allowed-tools: polaris_connect polaris_disconnect polaris_status polaris_reply polaris_context polaris_rename
-argument-hint: [join <project> <session> | rename <new-name> | disconnect | (no args for status)]
+argument-hint: [join <project> | rename <new-name> | disconnect | (no args for status)]
 ---
 
 ## Polaris — Multiplayer Collaboration
@@ -13,10 +13,10 @@ Manage your connection to a Polaris collaboration session.
 
 Based on the arguments provided, do ONE of the following:
 
-**`/polaris join <project> <session>`** — Connect to a session:
-1. Call `polaris_connect` with the given project, session, and user identity
-2. If `.polaris.json` exists in the repo root, read the `user` field from it. Otherwise ask the user for their participant ID (e.g., `user:manu`).
-3. Report the connection status
+**`/polaris join <project>`** — Connect to a session:
+1. Call `polaris_connect` with the given project and user identity `user:manu.bansal`
+2. A session name is auto-generated (e.g., `s-7a3f`)
+3. Report the connection status including the session name
 
 **`/polaris rename <new-name>`** — Rename the current project:
 1. Call `polaris_rename` with the new name

package/src/client/client.ts

@@ -54,10 +54,11 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         type: "object" as const,
         properties: {
           project: { type: "string", description: "Project name" },
-          session: { type: "string", description: "Session name" },
           user: { type: "string", description: "Your participant ID (e.g., user:manu)" },
+          session: { type: "string", description: "Session name (optional — auto-generated if omitted)" },
+          agent: { type: "string", description: "Agent identity (optional — defaults to agent:claude)" },
         },
-        required: ["project", "session", "user"],
+        required: ["project", "user"],
       },
     },
     {
@@ -116,22 +117,23 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
   const { name, arguments: args } = req.params;
 
   if (name === "polaris_connect") {
-    const { project, session, user } = args as { project: string; session: string; user: string };
+    const { project, user, session, agent } = args as { project: string; user: string; session?: string; agent?: string };
     try {
       const res = await daemonPost("/connect", {
         ccSessionId: CC_SESSION_ID,
         project,
-        session,
         user,
+        ...(session ? { session } : {}),
+        ...(agent ? { agent } : {}),
       });
-      const body = await res.json();
+      const body = await res.json() as { status?: string; project?: string; session?: string; user?: string; agent?: string; error?: string };
       if (res.ok) {
-        currentProject = project;
-        currentSession = session;
+        currentProject = body.project ?? project;
+        currentSession = body.session ?? session ?? "";
         currentUser = user;
-        return { content: [{ type: "text", text: `Connected to ${project}/${session} as ${user}.` }] };
+        return { content: [{ type: "text", text: `Connected to ${currentProject}/${currentSession} as ${user}.` }] };
       }
-      return { content: [{ type: "text", text: `Failed to connect: ${(body as { error?: string }).error ?? "unknown error"}` }] };
+      return { content: [{ type: "text", text: `Failed to connect: ${body.error ?? "unknown error"}` }] };
     } catch {
       return { content: [{ type: "text", text: "Failed to connect — is the Polaris daemon running? Start it with `polaris daemon` or `bun run src/daemon/daemon.ts`." }] };
     }

package/src/daemon/daemon.ts

@@ -10,10 +10,15 @@ interface SessionMapping {
   project: string;
   session: string;
   user: string;
+  agent: string;
   slackChannel?: string;
   ws: WebSocket | null;
 }
 
+function generateSessionName(): string {
+  return `s-${crypto.randomUUID().slice(0, 4)}`;
+}
+
 const sessions = new Map<string, SessionMapping>(); // keyed by ccSessionId
 
 // IPC callbacks for MCP servers to receive advisor messages
@@ -188,6 +193,7 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
               project: "",
               session: "",
               user: "",
+              agent: "",
               ws: null,
             });
           }
@@ -203,22 +209,28 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
           const body = (await req.json()) as {
             ccSessionId: string;
             project: string;
-            session: string;
+            session?: string;
             user: string;
+            agent?: string;
           };
           await logEvent("/connect", body);
-          if (!body.ccSessionId || !body.project || !body.session || !body.user) {
-            return error("ccSessionId, project, session, and user are required", 400);
+          if (!body.ccSessionId || !body.project || !body.user) {
+            return error("ccSessionId, project, and user are required", 400);
           }
 
+          // Generate session name if not provided
+          const sessionName = body.session || generateSessionName();
+          const agentId = body.agent || "agent:claude";
+
           // Disconnect existing cloud WS if switching sessions
           disconnectCloudWs(body.ccSessionId);
 
           const mapping: SessionMapping = {
             ccSessionId: body.ccSessionId,
             project: body.project,
-            session: body.session,
+            session: sessionName,
             user: body.user,
+            agent: agentId,
             ws: null,
           };
           sessions.set(body.ccSessionId, mapping);
@@ -232,24 +244,39 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
           }); // Ignore 409 (already exists)
 
           // Ensure the session exists (create if not, claim driver)
-          const sessionRes = await fetch(`${serviceUrl}/projects/${body.project}/sessions`, {
-            method: "POST",
-            headers: await authHeaders(),
-            body: JSON.stringify({ name: body.session, driver: body.user }),
-          });
-          if (!sessionRes.ok && sessionRes.status !== 409) {
-            const err = await sessionRes.text();
-            await logEvent("/connect", body, { status: sessionRes.status, body: err });
-            return error(`Failed to create session: ${err}`, 500);
-          }
-
-          // If session already existed, try to claim driver
-          if (sessionRes.status === 409) {
-            await fetch(`${serviceUrl}/projects/${body.project}/sessions/${body.session}/driver`, {
+          // Retry with new name on 409 (collision with generated name)
+          let attempts = 0;
+          let created = false;
+          while (!created && attempts < 3) {
+            const sessionRes = await fetch(`${serviceUrl}/projects/${body.project}/sessions`, {
               method: "POST",
               headers: await authHeaders(),
-              body: JSON.stringify({ driver: body.user }),
-            }); // Ignore errors (might already be driver)
+              body: JSON.stringify({ name: mapping.session, driver: body.user }),
+            });
+            if (sessionRes.ok) {
+              created = true;
+            } else if (sessionRes.status === 409) {
+              if (body.session) {
+                // Explicit session name — claim driver instead of retrying
+                await fetch(`${serviceUrl}/projects/${body.project}/sessions/${mapping.session}/driver`, {
+                  method: "POST",
+                  headers: await authHeaders(),
+                  body: JSON.stringify({ driver: body.user }),
+                });
+                created = true;
+              } else {
+                // Generated name collision — retry with new name
+                mapping.session = generateSessionName();
+                attempts++;
+              }
+            } else {
+              const err = await sessionRes.text();
+              await logEvent("/connect", body, { status: sessionRes.status, body: err });
+              return error(`Failed to create session: ${err}`, 500);
+            }
+          }
+          if (!created) {
+            return error("Failed to generate unique session name", 500);
           }
 
           // Fetch Slack channel name for status display
@@ -268,9 +295,10 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
 
           return json({
             status: "connected",
-            project: body.project,
-            session: body.session,
-            user: body.user,
+            project: mapping.project,
+            session: mapping.session,
+            user: mapping.user,
+            agent: mapping.agent,
           });
         } catch {
           return error("Invalid JSON", 400);
@@ -333,6 +361,10 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
             }
           }
 
+          // Determine sender: human for prompts, agent for everything else
+          const hookEvent = body.hook_event_name as string | undefined;
+          const sender = hookEvent === "UserPromptSubmit" ? mapping.user : mapping.agent;
+
           // Relay to cloud service
           const serviceUrl = getServiceUrl();
           const res = await fetch(
@@ -340,7 +372,7 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
             {
               method: "POST",
               headers: await authHeaders(),
-              body: JSON.stringify({ sender: mapping.user, payload: body }),
+              body: JSON.stringify({ sender, payload: body }),
             }
           );
 

package/src/types.ts

@@ -5,8 +5,8 @@ import { z } from "zod";
 export const ParticipantId = z
   .string()
   .regex(
-    /^(user|agent):[a-z0-9][a-z0-9._-]*$/,
-    "Must be user:<name> or agent:<name> (lowercase alphanumeric, dots, hyphens, underscores)"
+    /^(user|agent|slack):[a-z0-9][a-z0-9._-]*$/,
+    "Must be user:<name>, agent:<name>, or slack:<name> (lowercase alphanumeric, dots, hyphens, underscores)"
   );
 
 export type ParticipantId = z.infer<typeof ParticipantId>;

package/src/web/views.ts

@@ -208,7 +208,7 @@ function renderProjectsSessionsSection(ctx: ViewContext, sessions: SessionFixtur
           <summary class="text-xs text-polaris-700 hover:text-polaris-800 font-medium cursor-pointer select-none">+ Join another session</summary>
           <div class="mt-2 bg-white border border-gray-200 rounded-lg p-4">
             <p class="text-sm text-gray-500">Inside your AI agent, run:</p>
-            ${copyBlock("/polaris join &lt;project&gt; &lt;session&gt;")}
+            ${copyBlock("/polaris join &lt;project&gt;")}
           </div>
         </details>
         <div class="space-y-4">
@@ -231,7 +231,7 @@ function renderProjectsSessionsSection(ctx: ViewContext, sessions: SessionFixtur
           : "Inside your AI agent (Claude Code, Cursor, etc.), run:"}</p>
         ${ctx.hasConnectedSession
           ? ""
-          : copyBlock("/polaris join my-project my-session")}
+          : copyBlock("/polaris join my-project")}
       </div>
     </div>`);
 }

package/tests/e2e.test.ts

@@ -330,7 +330,7 @@ describe("e2e: capture.sh through daemon", () => {
     const body = await res.json();
     expect(body).toHaveLength(1);
     expect(body[0].payload.stop_response).toBe("Auth middleware is ready");
-    expect(body[0].sender).toBe("user:manu");
+    expect(body[0].sender).toBe("agent:claude"); // Stop events are sent by the agent
   });
 
   test("hook script exits 0 when daemon is down", async () => {

package/tests/web.test.ts

@@ -38,7 +38,7 @@ describe("renderSetupView", () => {
     // Install CLI command is present
     expect(html).toContain("npx @lightupai/polaris");
     // Connect session command is present
-    expect(html).toContain("/polaris join my-project my-session");
+    expect(html).toContain("/polaris join my-project");
   });
 
   test("slack done: floor shows connected, devices is highlighted, sessions grayed", () => {
@@ -66,7 +66,7 @@ describe("renderSetupView", () => {
     const lastHighlight = html.lastIndexOf("border-polaris-300");
     expect(lastHighlight).toBeGreaterThan(sessIdx);
     // Connect session command present
-    expect(html).toContain("/polaris join my-project my-session");
+    expect(html).toContain("/polaris join my-project");
   });
 
   test("includes nav with user info", () => {