fleetlens 0.15.7 → 0.16.0

package/app/apps/web/lib/agent/index-store.ts

@@ -0,0 +1,206 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { agentSources, cclensPath, invalidateFile } from "@claude-lens/parser/fs";
+import type { SessionMeta } from "@claude-lens/parser";
+import { parseEntryKey } from "@claude-lens/entries";
+import { listEntryKeys, readEntry } from "@claude-lens/entries/fs";
+import { extractIndexDoc } from "./extract";
+import { INDEX_VERSION, type IndexDoc } from "./types";
+
+export type IndexProgress = { built: number; reused: number; total: number };
+export type IndexStats = { sessions: number; lastRefreshMs: number | null; building: boolean };
+
+function indexDir(): string {
+  return cclensPath("agent-index");
+}
+
+function docPath(sessionId: string): string {
+  return join(indexDir(), `${sessionId}.json`);
+}
+
+/** Next compiles each route into its own module graph, so plain module
+ *  state would give every API route a private copy of the index (and its
+ *  own inflight latch → concurrent full rebuilds). globalThis is the one
+ *  store they all share — same trick as the canonical dev-safe singleton. */
+type Store = {
+  memory: Map<string, IndexDoc>;
+  lastRefreshMs: number | null;
+  inflight: Promise<IndexDoc[]> | null;
+  progressListeners: Set<(p: IndexProgress) => void>;
+};
+const store: Store = ((globalThis as Record<string, unknown>).__fleetlensAgentIndex ??= {
+  memory: new Map<string, IndexDoc>(),
+  lastRefreshMs: null,
+  inflight: null,
+  progressListeners: new Set(),
+}) as Store;
+
+function readDiskDoc(sessionId: string): IndexDoc | null {
+  try {
+    const raw = readFileSync(docPath(sessionId), "utf8");
+    const doc = JSON.parse(raw) as IndexDoc;
+    return doc.version === INDEX_VERSION ? doc : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeDiskDoc(doc: IndexDoc): void {
+  mkdirSync(indexDir(), { recursive: true });
+  const final = docPath(doc.sessionId);
+  const tmp = `${final}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(doc), "utf8");
+  renameSync(tmp, final);
+}
+
+/** brief_summary chunks from enriched entries — a free semantic layer on top
+ *  of the raw transcript text. Read only for the sessions being (re)built. */
+function entrySummaries(sessionIds: Set<string>): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  if (sessionIds.size === 0) return out;
+  for (const key of listEntryKeys()) {
+    const parsed = parseEntryKey(key);
+    if (!parsed || !sessionIds.has(parsed.session_id)) continue;
+    const entry = readEntry(parsed.session_id, parsed.local_day);
+    const brief = entry?.enrichment?.brief_summary;
+    if (!brief) continue;
+    const list = out.get(parsed.session_id) ?? [];
+    list.push(brief);
+    out.set(parsed.session_id, list);
+  }
+  return out;
+}
+
+async function refresh(onProgress?: (p: IndexProgress) => void): Promise<IndexDoc[]> {
+  const metaLists = await Promise.all(agentSources.map((s) => s.listSessions().catch(() => [] as SessionMeta[])));
+  type Pending = { meta: SessionMeta; source: (typeof agentSources)[number]; mtimeMs: number; sizeBytes: number };
+  const alive = new Set<string>();
+  const pending: Pending[] = [];
+  let reused = 0;
+
+  for (let i = 0; i < agentSources.length; i++) {
+    for (const meta of metaLists[i]!) {
+      alive.add(meta.id);
+      let st;
+      try {
+        st = statSync(meta.filePath);
+      } catch {
+        continue;
+      }
+      // Version check matters for memory hits too: the globalThis store
+      // outlives hot reloads, so a bumped INDEX_VERSION must evict them.
+      const cached = store.memory.get(meta.id) ?? readDiskDoc(meta.id);
+      if (cached && cached.version === INDEX_VERSION && cached.mtimeMs === st.mtimeMs && cached.sizeBytes === st.size) {
+        store.memory.set(meta.id, cached);
+        reused++;
+        continue;
+      }
+      pending.push({ meta, source: agentSources[i]!, mtimeMs: st.mtimeMs, sizeBytes: st.size });
+    }
+  }
+
+  // Drop sessions whose transcripts were pruned so search can't surface
+  // ghosts — from memory AND disk (a stale disk doc would re-inflate the
+  // indexStats readdir count on the next cold boot).
+  for (const id of store.memory.keys()) {
+    if (!alive.has(id)) store.memory.delete(id);
+  }
+  try {
+    for (const f of readdirSync(indexDir())) {
+      if (!f.endsWith(".json")) continue;
+      const id = f.slice(0, -".json".length);
+      if (!alive.has(id)) rmSync(join(indexDir(), f), { force: true });
+    }
+  } catch {
+    /* index dir may not exist yet */
+  }
+
+  const total = pending.length + reused;
+  const summaries = entrySummaries(new Set(pending.map((p) => p.meta.id)));
+  let built = 0;
+  onProgress?.({ built, reused, total });
+
+  for (const { meta, source, mtimeMs, sizeBytes } of pending) {
+    try {
+      const detail = await source.getSession(meta.id);
+      if (!detail) continue;
+      const doc = extractIndexDoc(detail, { mtimeMs, sizeBytes });
+      for (const brief of summaries.get(meta.id) ?? []) {
+        doc.chunks.unshift({ role: "summary", text: brief });
+      }
+      writeDiskDoc(doc);
+      store.memory.set(meta.id, doc);
+      // Keep the parser's unbounded detail cache from ballooning during a
+      // full first build over hundreds of transcripts.
+      invalidateFile(meta.filePath);
+    } catch {
+      /* one broken transcript must not sink the whole index */
+    }
+    built++;
+    if (built % 20 === 0 || built === pending.length) onProgress?.({ built, reused, total });
+  }
+
+  store.lastRefreshMs = Date.now();
+  return Array.from(store.memory.values());
+}
+
+/** A refresh is stat-cheap but still lists + stats every transcript; one
+ *  agent turn calls several tools back-to-back, so results this fresh are
+ *  served from memory. */
+const FRESH_MS = 15_000;
+
+/** Incrementally refresh and return every IndexDoc. Fast when nothing
+ *  changed (one stat per transcript); first-ever call parses everything. */
+export function ensureIndex(
+  onProgress?: (p: IndexProgress) => void,
+  opts?: { force?: boolean },
+): Promise<IndexDoc[]> {
+  // Join the inflight refresh rather than returning its bare promise — a
+  // joiner's onProgress must still fire or its progress stream sits silent.
+  if (onProgress) store.progressListeners.add(onProgress);
+  if (store.inflight) return store.inflight;
+  if (
+    !opts?.force &&
+    store.memory.size > 0 &&
+    store.lastRefreshMs !== null &&
+    Date.now() - store.lastRefreshMs < FRESH_MS
+  ) {
+    if (onProgress) store.progressListeners.delete(onProgress);
+    return Promise.resolve(Array.from(store.memory.values()));
+  }
+  store.inflight = refresh((p) => {
+    for (const fn of store.progressListeners) {
+      try {
+        fn(p);
+      } catch {
+        /* one broken listener must not stall the build */
+      }
+    }
+  }).finally(() => {
+    store.inflight = null;
+    store.progressListeners.clear();
+  });
+  return store.inflight;
+}
+
+/** Whatever is in memory right now — no refresh, no blocking. Empty until
+ *  the first ensureIndex() of this server process completes. */
+export function peekDocs(): IndexDoc[] {
+  return Array.from(store.memory.values());
+}
+
+export function indexStats(): IndexStats {
+  let sessions = store.memory.size;
+  if (sessions === 0) {
+    try {
+      sessions = readdirSync(indexDir()).filter((f) => f.endsWith(".json")).length;
+    } catch {
+      sessions = 0;
+    }
+  }
+  return { sessions, lastRefreshMs: store.lastRefreshMs, building: store.inflight !== null };
+}
+
+export function indexIsEmpty(): boolean {
+  return store.memory.size === 0 && !existsSync(indexDir());
+}

package/app/apps/web/lib/agent/links.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "vitest";
+import { classifyHref } from "./links";
+
+describe("classifyHref", () => {
+  test("session links render as internal links", () => {
+    expect(classifyHref("/sessions/abc-123")).toBe("session");
+    expect(classifyHref("/sessions/abc-123?day=2026-07-01")).toBe("session");
+  });
+
+  test("absolute http(s) links render as external links", () => {
+    expect(classifyHref("https://github.com/cowcow02/fleetlens/pull/88")).toBe("external");
+    expect(classifyHref("http://example.com")).toBe("external");
+  });
+
+  test("relative and unknown hrefs are unwrapped to plain text", () => {
+    expect(classifyHref("project_team_onboarding_wizard.md")).toBe("text");
+    expect(classifyHref("docs/some-notes.md")).toBe("text");
+    expect(classifyHref("/projects/foo")).toBe("text");
+    expect(classifyHref("")).toBe("text");
+    expect(classifyHref(undefined)).toBe("text");
+  });
+
+  test("javascript and data urls are never rendered as links", () => {
+    expect(classifyHref("javascript:alert(1)")).toBe("text");
+    expect(classifyHref("data:text/html,hi")).toBe("text");
+  });
+});

package/app/apps/web/lib/agent/links.ts

@@ -0,0 +1,10 @@
+/** The model sometimes cites things that aren't linkable — memory-file
+ *  names, repo paths — and a relative href silently resolves against the
+ *  page origin into a dead localhost URL. Only two destinations are real:
+ *  session pages and absolute web URLs; everything else renders as text. */
+export function classifyHref(href: string | undefined): "session" | "external" | "text" {
+  if (!href) return "text";
+  if (href.startsWith("/sessions/")) return "session";
+  if (/^https?:\/\//.test(href)) return "external";
+  return "text";
+}

package/app/apps/web/lib/agent/mcp.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "vitest";
+import { handleMcpMessage, type McpTools } from "./mcp";
+
+const TOOLS: McpTools = {
+  defs: [
+    {
+      name: "search_sessions",
+      description: "Search sessions",
+      inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+    },
+  ],
+  call: async (name, args) => {
+    if (name === "search_sessions") return JSON.stringify({ echo: (args as { query: string }).query });
+    throw new Error(`unknown tool: ${name}`);
+  },
+};
+
+function rpc(method: string, params?: unknown, id: number | string | null = 1) {
+  return { jsonrpc: "2.0", id, method, ...(params !== undefined ? { params } : {}) };
+}
+
+describe("handleMcpMessage", () => {
+  test("initialize returns protocol version, capabilities, and server info", async () => {
+    const res = (await handleMcpMessage(
+      rpc("initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "claude", version: "1" } }),
+      TOOLS,
+    )) as { jsonrpc: string; id: number; result: { protocolVersion: string; capabilities: { tools: object }; serverInfo: { name: string } } };
+    expect(res.jsonrpc).toBe("2.0");
+    expect(res.id).toBe(1);
+    expect(res.result.protocolVersion).toBe("2025-06-18");
+    expect(res.result.capabilities.tools).toBeDefined();
+    expect(res.result.serverInfo.name).toBe("fleetlens");
+  });
+
+  test("notifications get no response", async () => {
+    const res = await handleMcpMessage({ jsonrpc: "2.0", method: "notifications/initialized" }, TOOLS);
+    expect(res).toBeNull();
+  });
+
+  test("tools/list returns the tool definitions", async () => {
+    const res = (await handleMcpMessage(rpc("tools/list"), TOOLS)) as {
+      result: { tools: Array<{ name: string; inputSchema: object }> };
+    };
+    expect(res.result.tools).toHaveLength(1);
+    expect(res.result.tools[0]!.name).toBe("search_sessions");
+  });
+
+  test("tools/call dispatches and wraps the result as text content", async () => {
+    const res = (await handleMcpMessage(
+      rpc("tools/call", { name: "search_sessions", arguments: { query: "daemon" } }),
+      TOOLS,
+    )) as { result: { content: Array<{ type: string; text: string }>; isError?: boolean } };
+    expect(res.result.content[0]!.type).toBe("text");
+    expect(JSON.parse(res.result.content[0]!.text)).toEqual({ echo: "daemon" });
+    expect(res.result.isError).toBeUndefined();
+  });
+
+  test("tools/call surfaces tool failures as isError results, not protocol errors", async () => {
+    const res = (await handleMcpMessage(
+      rpc("tools/call", { name: "does_not_exist", arguments: {} }),
+      TOOLS,
+    )) as { result: { content: Array<{ type: string; text: string }>; isError: boolean } };
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0]!.text).toContain("unknown tool");
+  });
+
+  test("unknown methods return JSON-RPC method-not-found", async () => {
+    const res = (await handleMcpMessage(rpc("resources/list"), TOOLS)) as {
+      error: { code: number; message: string };
+    };
+    expect(res.error.code).toBe(-32601);
+  });
+
+  test("malformed bodies return JSON-RPC invalid-request", async () => {
+    const res = (await handleMcpMessage("not an object", TOOLS)) as { error: { code: number } };
+    expect(res.error.code).toBe(-32600);
+  });
+
+  test("ping returns an empty result", async () => {
+    const res = (await handleMcpMessage(rpc("ping"), TOOLS)) as { result: object };
+    expect(res.result).toEqual({});
+  });
+});

package/app/apps/web/lib/agent/mcp.ts

@@ -0,0 +1,85 @@
+/**
+ * MCP (Model Context Protocol) message handler: initialize / tools/list /
+ * tools/call over plain JSON-RPC (streamable-HTTP transport). No SDK
+ * dependency — the claude CLI is the only client this will ever serve.
+ */
+
+import pkg from "../../package.json" with { type: "json" };
+
+export type McpToolDef = {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+};
+
+export type McpTools = {
+  defs: McpToolDef[];
+  /** Returns the tool's text payload; throw to signal a tool error. */
+  call: (name: string, args: unknown) => Promise<string>;
+};
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+type RpcRequest = {
+  jsonrpc?: string;
+  id?: number | string | null;
+  method?: string;
+  params?: Record<string, unknown>;
+};
+
+function result(id: number | string | null, payload: unknown) {
+  return { jsonrpc: "2.0", id, result: payload };
+}
+
+function error(id: number | string | null, code: number, message: string) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+/** Handle one JSON-RPC message. Returns the response object, or null for
+ *  notifications (no id → nothing to send back). */
+export async function handleMcpMessage(body: unknown, tools: McpTools): Promise<unknown | null> {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return error(null, -32600, "invalid request");
+  }
+  const msg = body as RpcRequest;
+  if (typeof msg.method !== "string") {
+    return error(msg.id ?? null, -32600, "invalid request");
+  }
+
+  const isNotification = msg.id === undefined;
+  if (isNotification) return null;
+  const id = msg.id ?? null;
+
+  switch (msg.method) {
+    case "initialize": {
+      const requested = msg.params?.protocolVersion;
+      return result(id, {
+        protocolVersion: typeof requested === "string" ? requested : PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: "fleetlens", version: pkg.version },
+      });
+    }
+    case "ping":
+      return result(id, {});
+    case "tools/list":
+      return result(id, { tools: tools.defs });
+    case "tools/call": {
+      const name = msg.params?.name;
+      const args = msg.params?.arguments ?? {};
+      if (typeof name !== "string") {
+        return error(id, -32602, "tools/call requires params.name");
+      }
+      try {
+        const text = await tools.call(name, args);
+        return result(id, { content: [{ type: "text", text }] });
+      } catch (err) {
+        return result(id, {
+          content: [{ type: "text", text: (err as Error).message }],
+          isError: true,
+        });
+      }
+    }
+    default:
+      return error(id, -32601, `method not found: ${msg.method}`);
+  }
+}

package/app/apps/web/lib/agent/prompt.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "vitest";
+import { buildUserPrompt, type ChatMessage } from "./prompt";
+
+const user = (text: string): ChatMessage => ({ role: "user", text });
+const assistant = (text: string): ChatMessage => ({ role: "assistant", text });
+
+describe("buildUserPrompt", () => {
+  test("a single message passes through verbatim with no history framing", () => {
+    expect(buildUserPrompt([user("find my daemon work")])).toBe("find my daemon work");
+  });
+
+  test("prior turns are framed as conversation history before the new message", () => {
+    const out = buildUserPrompt([user("first question"), assistant("first answer"), user("follow-up")]);
+    expect(out).toContain("Conversation so far:");
+    expect(out).toContain("User: first question");
+    expect(out).toContain("You (assistant): first answer");
+    expect(out.endsWith("User's new message: follow-up")).toBe(true);
+  });
+
+  test("history is trimmed to the most recent 12 messages", () => {
+    const messages: ChatMessage[] = [];
+    for (let i = 0; i < 20; i++) messages.push(user(`message ${i}`));
+    const out = buildUserPrompt(messages);
+    expect(out).not.toContain("message 7");
+    expect(out).toContain("message 8");
+    expect(out.endsWith("User's new message: message 19")).toBe(true);
+  });
+
+  test("overlong messages are truncated with an ellipsis", () => {
+    const out = buildUserPrompt([user("x".repeat(5000)), user("short")]);
+    expect(out).toContain("x".repeat(4000) + "…");
+    expect(out).not.toContain("x".repeat(4001));
+  });
+
+  test("empty input yields an empty prompt", () => {
+    expect(buildUserPrompt([])).toBe("");
+  });
+});

package/app/apps/web/lib/agent/prompt.ts

@@ -0,0 +1,44 @@
+export type ChatMessage = { role: "user" | "assistant"; text: string };
+
+const HISTORY_MAX_MESSAGES = 12;
+const HISTORY_MSG_MAX_CHARS = 4000;
+
+export function agentSystemPrompt(): string {
+  const today = new Date();
+  const day = today.toLocaleDateString("en-CA"); // YYYY-MM-DD in local tz
+  const weekday = today.toLocaleDateString("en-US", { weekday: "long" });
+  return `You are the Fleetlens Agent. Fleetlens is a local, privacy-first dashboard over the user's coding-agent history: every Claude Code, Codex, Gemini (and other) session recorded on this machine. You have tools that search and read those sessions.
+
+Today is ${weekday}, ${day}. All session data is local; nothing you do leaves this machine.
+
+What users come to you for:
+1. **Find** — locate past sessions: "where did I fix the daemon crash?", "what did I do last Tuesday?"
+2. **Synthesize** — explain what happened across sessions: decisions made, approaches tried, gotchas hit.
+3. **Draft a prompt** — package findings into a self-contained prompt the user can paste into a fresh coding-agent session as context for their next task.
+
+Rules:
+- Your ONLY tools are the four fleetlens session tools (search_sessions, get_session, list_sessions, list_projects). You have no filesystem, Bash, memory directory, or web access — never attempt Write, Edit, Read, or any other tool, and never claim you'll "update memory".
+- Invoke tools through real tool calls only — never write function-call syntax or XML tags into your text response, and never simulate or invent tool output. If a tool fails or returns nothing, say so.
+- Ground every claim about past work in tool results. Search before answering; if the first query is inconclusive, retry with different wording (synonyms, file names, error text). Never invent sessions or details.
+- Don't re-fetch a session you already read this conversation — its content won't change.
+- Cite sessions inline as markdown links using each hit's url, e.g. [fix daemon crash](/sessions/abc-123). Cite the sessions you actually drew from — not every hit. These session urls (and real web URLs from tool results) are the ONLY things you may link; never link file names, paths, or documents — mention them as plain text.
+- When asked for a prompt / context pack / handoff, output it as a single fenced code block tagged \`prompt\` (\`\`\`prompt … \`\`\`). Make it self-contained: goal, relevant repo/file paths, decisions already made, known gotchas, and what to do next. No session links inside the block — the next agent can't open them.
+- Be concise. Lead with the answer, then supporting detail. Don't narrate your tool use.
+- If searches genuinely turn up nothing, say so plainly and suggest a better query.`;
+}
+
+/** Flatten prior turns into the user prompt — the subprocess is stateless
+ *  across turns, so the conversation rides along in text form. */
+export function buildUserPrompt(messages: ChatMessage[]): string {
+  const trimmed = messages.slice(-HISTORY_MAX_MESSAGES).map((m) => ({
+    role: m.role,
+    text: m.text.length > HISTORY_MSG_MAX_CHARS ? m.text.slice(0, HISTORY_MSG_MAX_CHARS) + "…" : m.text,
+  }));
+  const last = trimmed.pop();
+  if (!last) return "";
+  if (trimmed.length === 0) return last.text;
+  const history = trimmed
+    .map((m) => `${m.role === "user" ? "User" : "You (assistant)"}: ${m.text}`)
+    .join("\n\n");
+  return `Conversation so far:\n\n${history}\n\n---\n\nUser's new message: ${last.text}`;
+}