@lightupai/polaris 0.0.30 → 0.0.32

package/docs/design-backfill.md

@@ -139,6 +139,23 @@ Response:
 3. **Slack recovery summary** — nice to have, reuse the pattern from the manual recovery we did
 4. **Deduplication** — important for correctness, add after basic replay works
 
+## Name Changes During Gap
+
+Project renames, session changes, and Slack channel renames can happen during a gap. Backfill must handle these correctly.
+
+**Key insight**: The daemon log stores raw hook payloads, not project/session names. The daemon adds the project/session from its session mapping at relay time. So on replay, the daemon should use the *current* mapping, not reconstruct a historical one.
+
+| Change during gap | Impact | Handling |
+|---|---|---|
+| Project renamed | Log doesn't contain project name — daemon resolves it from current mapping | Works automatically |
+| Slack channel renamed | Bridge looks up channel by project → channel ID in DB | Works if DB mapping is current |
+| User switched projects | Log has events for both time periods | Filter by timestamp range per project |
+| Session handed off to new driver | Sender identity changes | Use current session's driver/agent at replay time |
+
+**Transcript fallback complication**: The transcript doesn't know about Polaris projects/sessions at all. When parsing the transcript, backfill must ask: "which project was this CC session connected to at this timestamp?" The daemon log has `/connect` entries that establish the timeline of project associations. If the daemon log is also missing, the current session mapping is the only reference — which may not reflect historical state.
+
+**Recommendation**: Always log `/connect` and `/disconnect` events to a separate persistent file (`~/.polaris/session-history.jsonl`) that survives daemon restarts. This gives backfill a reliable timeline of which CC session was in which project at what time.
+
 ## Open Questions
 
 1. **Should backfill be automatic?** The daemon could detect gaps on startup (compare last log entry to last API event) and auto-backfill. Risk: could replay stale events unintentionally.
@@ -148,3 +165,5 @@ Response:
 3. **Multi-day gaps**: The daemon log is per-day. A multi-day outage requires reading multiple files. The transcript spans the whole session.
 
 4. **Cross-session backfill**: If the user was in session A, disconnected, joined session B, and wants to backfill A — the daemon log has events for both. Need to filter by session/project.
+
+5. **Session history persistence**: Should we add `~/.polaris/session-history.jsonl` now (cheap, foundational for backfill) or defer until backfill is implemented?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightupai/polaris",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "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
-argument-hint: [join #channel | rename <new-name> | disconnect | (no args for status)]
+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)]
 ---
 
 ## Polaris — Multiplayer Collaboration
@@ -22,6 +22,10 @@ Based on the arguments provided, do ONE of the following:
 1. Call `polaris_rename` with the new name
 2. Report the result
 
+**`/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
+
 **`/polaris disconnect`** — Disconnect:
 1. Call `polaris_disconnect`
 2. Confirm disconnection

package/src/client/client.ts

@@ -110,6 +110,17 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["session"],
       },
     },
+    {
+      name: "polaris_backfill",
+      description: "Recover lost events from local daemon logs. Use when events were lost due to disconnection or API downtime.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          duration: { type: "string", description: "Time range to backfill (e.g., '2h', '30m', '1d'). Auto-detects if omitted." },
+          from: { type: "string", description: "ISO timestamp to backfill from. Overrides duration." },
+        },
+      },
+    },
   ],
 }));
 
@@ -228,6 +239,28 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     }
   }
 
+  if (name === "polaris_backfill") {
+    if (!currentProject) {
+      return { content: [{ type: "text", text: "Not connected to a Polaris session. Use polaris_connect first." }] };
+    }
+    const { duration, from } = (args ?? {}) as { duration?: string; from?: string };
+    try {
+      const res = await daemonPost("/backfill", {
+        ccSessionId: CC_SESSION_ID,
+        ...(duration ? { duration } : {}),
+        ...(from ? { from } : {}),
+      });
+      const body = await res.json() as { recovered: number; source: string; gaps: string[] };
+      if (res.ok) {
+        const gapInfo = body.gaps.length > 0 ? `\nGaps: ${body.gaps.join(", ")}` : "";
+        return { content: [{ type: "text", text: `Backfill complete: ${body.recovered} events recovered from ${body.source}.${gapInfo}` }] };
+      }
+      return { content: [{ type: "text", text: `Backfill failed: ${(body as unknown as { error?: string }).error ?? "unknown error"}` }] };
+    } catch {
+      return { content: [{ type: "text", text: "Failed to reach the daemon." }] };
+    }
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 });
 

package/src/daemon/daemon.ts

@@ -154,6 +154,114 @@ async function logEvent(endpoint: string, payload: unknown, response?: { status:
   } catch { /* best-effort — don't break the request */ }
 }
 
+// --- Session history (persistent connect/disconnect log for backfill) ---
+
+const SESSION_HISTORY_FILE = join(homedir(), ".polaris", "session-history.jsonl");
+
+async function logSessionChange(action: "connect" | "disconnect", ccSessionId: string, project: string, session: string, user: string, agent: string): Promise<void> {
+  try {
+    await ensureLogDir();
+    const entry = JSON.stringify({ t: new Date().toISOString(), action, ccSessionId, project, session, user, agent });
+    await appendFile(SESSION_HISTORY_FILE, entry + "\n");
+  } catch { /* best-effort */ }
+}
+
+// --- Backfill: recover lost events from daemon log ---
+
+async function backfill(mapping: SessionMapping, duration?: string, from?: string): Promise<{ recovered: number; source: string; gaps: string[] }> {
+  const now = new Date();
+  let since: Date;
+
+  if (from) {
+    since = new Date(from);
+  } else if (duration) {
+    const match = duration.match(/^(\d+)(h|m|d)$/);
+    if (!match) return { recovered: 0, source: "none", gaps: ["invalid duration format"] };
+    const val = parseInt(match[1]);
+    const unit = match[2];
+    since = new Date(now.getTime() - val * (unit === "h" ? 3600000 : unit === "m" ? 60000 : 86400000));
+  } else {
+    // Auto-detect: query API for most recent event, backfill from there
+    try {
+      const serviceUrl = getServiceUrl();
+      const res = await fetch(
+        `${serviceUrl}/projects/${mapping.project}/sessions/${mapping.session}/messages`,
+        { headers: await authHeaders() }
+      );
+      if (res.ok) {
+        const events = (await res.json()) as Array<{ timestamp: string }>;
+        if (events.length > 0) {
+          since = new Date(events[events.length - 1].timestamp);
+        } else {
+          since = new Date(now.getTime() - 3600000); // default 1h
+        }
+      } else {
+        since = new Date(now.getTime() - 3600000);
+      }
+    } catch {
+      since = new Date(now.getTime() - 3600000);
+    }
+  }
+
+  // Read daemon log files covering the time range
+  const logEntries: Array<{ t: string; endpoint: string; payload: Record<string, unknown> }> = [];
+  const startDate = since.toISOString().slice(0, 10);
+  const endDate = now.toISOString().slice(0, 10);
+
+  // Collect all dates in range
+  const dates: string[] = [];
+  const d = new Date(startDate);
+  while (d.toISOString().slice(0, 10) <= endDate) {
+    dates.push(d.toISOString().slice(0, 10));
+    d.setDate(d.getDate() + 1);
+  }
+
+  for (const date of dates) {
+    const logFile = join(LOG_DIR, `daemon-${date}.jsonl`);
+    try {
+      const content = await readFile(logFile, "utf-8");
+      for (const line of content.split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          const entry = JSON.parse(line);
+          if (entry.endpoint !== "/events") continue;
+          if (new Date(entry.t) <= since) continue;
+          if (new Date(entry.t) > now) continue;
+          logEntries.push(entry);
+        } catch { /* skip malformed lines */ }
+      }
+    } catch { /* log file doesn't exist for this date — not an error */ }
+  }
+
+  if (logEntries.length === 0) {
+    return { recovered: 0, source: "daemon_log", gaps: [`no log entries found since ${since.toISOString()}`] };
+  }
+
+  // Replay events to the API
+  let recovered = 0;
+  const serviceUrl = getServiceUrl();
+  const headers = await authHeaders();
+
+  for (const entry of logEntries) {
+    const hookEvent = entry.payload.hook_event_name as string | undefined;
+    const sender = hookEvent === "UserPromptSubmit" ? mapping.user : mapping.agent;
+
+    try {
+      const res = await fetch(
+        `${serviceUrl}/projects/${mapping.project}/sessions/${mapping.session}/events`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ sender, payload: entry.payload }),
+        }
+      );
+      if (res.ok) recovered++;
+    } catch { /* skip failed replays */ }
+  }
+
+  return { recovered, source: "daemon_log", gaps: [] };
+}
+
 // --- HTTP Server ---
 
 function json(data: unknown, status = 200): Response {
@@ -294,6 +402,7 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
 
           // Connect to cloud WebSocket
           connectCloudWs(mapping);
+          await logSessionChange("connect", mapping.ccSessionId, mapping.project, mapping.session, mapping.user, mapping.agent);
 
           return json({
             status: "connected",
@@ -314,7 +423,8 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
           if (!body.ccSessionId) return error("ccSessionId required", 400);
           disconnectCloudWs(body.ccSessionId);
           const mapping = sessions.get(body.ccSessionId);
-          if (mapping) {
+          if (mapping && mapping.project) {
+            await logSessionChange("disconnect", body.ccSessionId, mapping.project, mapping.session, mapping.user, mapping.agent);
             mapping.project = "";
             mapping.session = "";
             mapping.user = "";
@@ -541,6 +651,21 @@ export function startDaemon(port = Number(process.env.POLARIS_DAEMON_PORT ?? 432
         return json(data);
       }
 
+      // POST /backfill — recover lost events from daemon log
+      if (method === "POST" && pathname === "/backfill") {
+        try {
+          const body = (await req.json()) as { ccSessionId: string; duration?: string; from?: string };
+          if (!body.ccSessionId) return error("ccSessionId required", 400);
+          const mapping = sessions.get(body.ccSessionId);
+          if (!mapping || !mapping.project) return error("Not connected", 400);
+
+          const result = await backfill(mapping, body.duration, body.from);
+          return json(result);
+        } catch {
+          return error("Invalid JSON", 400);
+        }
+      }
+
       return error("Not found", 404);
     },
   });