fleetlens 0.15.7 → 0.16.0

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

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "vitest";
+import type { IndexDoc } from "./types";
+import {
+  FALLBACK_SUGGESTIONS,
+  buildSuggestionContext,
+  deterministicSuggestions,
+  parseSuggestions,
+  suggestionInputKey,
+} from "./suggestions";
+
+function doc(partial: Partial<IndexDoc> & { sessionId: string }): IndexDoc {
+  return {
+    version: 1,
+    agent: "claude-code",
+    project: "/Users/me/Repo/foo",
+    day: "2026-07-08",
+    startIso: "2026-07-08T10:00:00.000Z",
+    title: "untitled",
+    chunks: [],
+    mtimeMs: 0,
+    sizeBytes: 0,
+    ...partial,
+  };
+}
+
+const NOW = Date.parse("2026-07-10T12:00:00.000Z");
+
+describe("deterministicSuggestions", () => {
+  test("steers labels toward the most recently active project", () => {
+    const docs = [
+      doc({ sessionId: "a", project: "/Users/me/Repo/workhub", day: "2026-07-09", startIso: "2026-07-09T10:00:00.000Z" }),
+      doc({ sessionId: "b", project: "/Users/me/Repo/workhub", day: "2026-07-08", startIso: "2026-07-08T10:00:00.000Z" }),
+      doc({ sessionId: "c", project: "/Users/me/Repo/old", day: "2026-06-01", startIso: "2026-06-01T10:00:00.000Z" }),
+    ];
+    const suggestions = deterministicSuggestions(docs, NOW);
+    expect(suggestions).toHaveLength(4);
+    expect(suggestions.map((s) => s.category).sort()).toEqual(["find", "handoff", "recap", "synthesize"]);
+    // the active project's short name appears in at least two labels
+    const mentioning = suggestions.filter((s) => s.label.includes("workhub"));
+    expect(mentioning.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("falls back to the static set when there are no docs", () => {
+    expect(deterministicSuggestions([], NOW)).toEqual(FALLBACK_SUGGESTIONS);
+  });
+
+  test("prefers the git repo name over the folder basename", () => {
+    const docs = [
+      doc({
+        sessionId: "a",
+        project: "/Users/me/Repo/claude-lens",
+        repoName: "fleetlens",
+        day: "2026-07-09",
+        startIso: "2026-07-09T10:00:00.000Z",
+      }),
+    ];
+    const labels = deterministicSuggestions(docs, NOW).map((s) => s.label).join(" | ");
+    expect(labels).toContain("fleetlens");
+    expect(labels).not.toContain("claude-lens");
+  });
+
+  test("spreads across projects: find uses the second most active project", () => {
+    const docs = [
+      doc({ sessionId: "a", project: "/Users/me/Repo/workhub", day: "2026-07-09", startIso: "2026-07-09T10:00:00.000Z" }),
+      doc({ sessionId: "b", project: "/Users/me/Repo/workhub", day: "2026-07-09", startIso: "2026-07-09T11:00:00.000Z" }),
+      doc({ sessionId: "c", project: "/Users/me/Repo/sidegig", day: "2026-07-08", startIso: "2026-07-08T10:00:00.000Z" }),
+    ];
+    const suggestions = deterministicSuggestions(docs, NOW);
+    const find = suggestions.find((s) => s.category === "find")!;
+    expect(find.label).toContain("sidegig");
+    // the top project shows up at most twice so the set doesn't read as a broken record
+    const workhubMentions = suggestions.filter((s) => s.label.includes("workhub"));
+    expect(workhubMentions.length).toBeLessThanOrEqual(2);
+  });
+});
+
+describe("suggestionInputKey", () => {
+  test("changes when the newest session changes, stable otherwise", () => {
+    const docs = [doc({ sessionId: "a", startIso: "2026-07-09T10:00:00.000Z" })];
+    const k1 = suggestionInputKey(docs);
+    expect(suggestionInputKey([...docs])).toBe(k1);
+    const k2 = suggestionInputKey([...docs, doc({ sessionId: "b", startIso: "2026-07-10T09:00:00.000Z" })]);
+    expect(k2).not.toBe(k1);
+  });
+});
+
+describe("buildSuggestionContext", () => {
+  test("includes active projects, recent titles, and summary chunks", () => {
+    const docs = [
+      doc({
+        sessionId: "a",
+        project: "/Users/me/Repo/workhub",
+        day: "2026-07-09",
+        startIso: "2026-07-09T10:00:00.000Z",
+        title: "wire the billing webhook",
+        chunks: [{ role: "summary", text: "Shipped the webhook retry queue." }],
+      }),
+      doc({ sessionId: "c", project: "/Users/me/Repo/old", day: "2026-06-01", startIso: "2026-06-01T10:00:00.000Z", title: "legacy cleanup" }),
+    ];
+    const ctx = buildSuggestionContext(docs, NOW);
+    expect(ctx).toContain("workhub");
+    expect(ctx).toContain("wire the billing webhook");
+    expect(ctx).toContain("Shipped the webhook retry queue.");
+  });
+});
+
+describe("parseSuggestions", () => {
+  const good = JSON.stringify([
+    { label: "What did I ship in workhub yesterday?", category: "recap" },
+    { label: "Find the webhook retry sessions", category: "find" },
+    { label: "Summarize this week's workhub arc", category: "synthesize" },
+    { label: "Draft a prompt to continue the billing work", category: "handoff" },
+  ]);
+
+  test("accepts a valid four-item array, with or without a code fence", () => {
+    expect(parseSuggestions(good)).toHaveLength(4);
+    expect(parseSuggestions("```json\n" + good + "\n```")).toHaveLength(4);
+  });
+
+  test("extracts the array from surrounding prose (haiku loves preambles)", () => {
+    const wrapped = `Here are the four suggestion chips based on the digest:\n\n${good}\n\nLet me know if you'd like different ones!`;
+    expect(parseSuggestions(wrapped)).toHaveLength(4);
+  });
+
+  test("rejects wrong categories, wrong counts, and non-JSON", () => {
+    expect(parseSuggestions(JSON.stringify([{ label: "x", category: "nope" }]))).toBeNull();
+    expect(parseSuggestions(JSON.stringify([]))).toBeNull();
+    expect(parseSuggestions("not json at all")).toBeNull();
+  });
+
+  test("survives trailing prose containing a stray closing bracket", () => {
+    expect(parseSuggestions(`${good}\n\nThese cover [recap] and more!`)).toHaveLength(4);
+  });
+
+  test("rejects duplicate categories", () => {
+    const dup = JSON.stringify([
+      { label: "a", category: "find" },
+      { label: "b", category: "find" },
+      { label: "c", category: "synthesize" },
+      { label: "d", category: "handoff" },
+    ]);
+    expect(parseSuggestions(dup)).toBeNull();
+  });
+
+  test("clamps overlong labels", () => {
+    const long = JSON.stringify([
+      { label: "x".repeat(300), category: "recap" },
+      { label: "b", category: "find" },
+      { label: "c", category: "synthesize" },
+      { label: "d", category: "handoff" },
+    ]);
+    const parsed = parseSuggestions(long);
+    expect(parsed).not.toBeNull();
+    expect(parsed![0]!.label.length).toBeLessThanOrEqual(120);
+  });
+});

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

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import type { IndexDoc } from "./types";
+
+/** One clickable empty-state chip. The four categories are the capability
+ *  menu (recap / find / synthesize / handoff); personalization only changes
+ *  the wording, never the shape. */
+export type Suggestion = {
+  label: string;
+  category: "recap" | "find" | "synthesize" | "handoff";
+};
+
+export const FALLBACK_SUGGESTIONS: Suggestion[] = [
+  { label: "What did I work on yesterday?", category: "recap" },
+  { label: "Find the sessions behind my most recent fix", category: "find" },
+  { label: "Which projects did I touch this week, and what happened in each?", category: "synthesize" },
+  { label: "Draft a prompt to continue my most recent feature work, with full context", category: "handoff" },
+];
+
+const LABEL_MAX = 120;
+const RECENT_WINDOW_MS = 7 * 86_400_000;
+
+function shortName(project: string): string {
+  const parts = project.split("/").filter(Boolean);
+  return parts[parts.length - 1] ?? project;
+}
+
+type ActiveProject = { project: string; display: string; sessions: number; lastDay: string };
+
+function byRecentActivity(docs: IndexDoc[], nowMs: number): ActiveProject[] {
+  const cutoff = nowMs - RECENT_WINDOW_MS;
+  const agg = new Map<string, { display: string; sessions: number; lastDay: string }>();
+  for (const d of docs) {
+    const ms = d.startIso ? Date.parse(d.startIso) : NaN;
+    if (Number.isNaN(ms) || ms < cutoff) continue;
+    const cur = agg.get(d.project) ?? { display: shortName(d.project), sessions: 0, lastDay: "" };
+    cur.sessions++;
+    if (d.day > cur.lastDay) cur.lastDay = d.day;
+    // The git remote's repo name is what the rest of the UI shows.
+    if (d.repoName) cur.display = d.repoName;
+    agg.set(d.project, cur);
+  }
+  return Array.from(agg.entries())
+    .map(([project, v]) => ({ project, ...v }))
+    .sort((a, b) => b.lastDay.localeCompare(a.lastDay) || b.sessions - a.sessions);
+}
+
+/** LLM-free personalization tier: template-fill the four categories from
+ *  recent activity. Used when AI features are off, the LLM call fails, or
+ *  nothing is cached yet. The top project appears at most twice; the find
+ *  chip goes to the runner-up project so the set doesn't read as a loop. */
+export function deterministicSuggestions(docs: IndexDoc[], nowMs: number): Suggestion[] {
+  const active = byRecentActivity(docs, nowMs);
+  const top = active[0];
+  if (!top) return FALLBACK_SUGGESTIONS;
+  const second = active[1];
+  return [
+    { label: "What did I work on yesterday?", category: "recap" },
+    second
+      ? { label: `Find the sessions where I worked on ${second.display}`, category: "find" }
+      : { label: "Find the sessions behind my most recent fix", category: "find" },
+    { label: `Summarize this week's work on ${top.display}`, category: "synthesize" },
+    { label: `Draft a prompt to continue my latest ${top.display} work, with full context`, category: "handoff" },
+  ];
+}
+
+/** Staleness key for the cached LLM suggestions: any new session (or a
+ *  re-indexed newest session) invalidates. */
+export function suggestionInputKey(docs: IndexDoc[]): string {
+  let newestIso = "";
+  let newestId = "";
+  for (const d of docs) {
+    const iso = d.startIso ?? "";
+    if (iso > newestIso) {
+      newestIso = iso;
+      newestId = d.sessionId;
+    }
+  }
+  return `${newestId}|${newestIso}|${docs.length}`;
+}
+
+const CONTEXT_PROJECTS = 3;
+const CONTEXT_TITLES = 8;
+const CONTEXT_BRIEFS = 6;
+
+/** Compact activity digest fed to the suggestion model. */
+export function buildSuggestionContext(docs: IndexDoc[], nowMs: number): string {
+  const today = new Date(nowMs);
+  const lines: string[] = [];
+  lines.push(`Today: ${today.toLocaleDateString("en-CA")} (${today.toLocaleDateString("en-US", { weekday: "long" })})`);
+
+  const active = byRecentActivity(docs, nowMs).slice(0, CONTEXT_PROJECTS);
+  lines.push("", "Most active projects (last 7 days):");
+  for (const p of active) {
+    lines.push(`- ${p.display} — ${p.sessions} sessions, last active ${p.lastDay}`);
+  }
+
+  const displayFor = (d: IndexDoc) => d.repoName ?? shortName(d.project);
+  const recent = [...docs]
+    .sort((a, b) => (b.startIso ?? "").localeCompare(a.startIso ?? ""))
+    .slice(0, CONTEXT_TITLES);
+  lines.push("", "Most recent sessions:");
+  for (const d of recent) {
+    lines.push(`- [${d.day}] ${displayFor(d)}: ${d.title}`);
+  }
+
+  const briefs: string[] = [];
+  for (const d of recent) {
+    for (const c of d.chunks) {
+      if (c.role !== "summary") continue;
+      briefs.push(`- ${displayFor(d)}: ${c.text}`);
+      if (briefs.length >= CONTEXT_BRIEFS) break;
+    }
+    if (briefs.length >= CONTEXT_BRIEFS) break;
+  }
+  if (briefs.length > 0) {
+    lines.push("", "AI summaries of recent sessions:");
+    lines.push(...briefs);
+  }
+  return lines.join("\n");
+}
+
+export const SUGGESTION_SYSTEM_PROMPT = `You write the four suggestion chips shown on the empty state of an agent that searches the user's local coding-agent session history (their own past Claude Code / Codex / Gemini conversations).
+
+You will receive a digest of their recent activity. Produce EXACTLY four chips, one per category:
+- "recap"      — a time-scoped "what happened" question (yesterday / this week)
+- "find"       — locate specific past sessions about a concrete thing they worked on
+- "synthesize" — a cross-session summary or comparison
+- "handoff"    — draft a context-pack prompt to continue their current work in a fresh agent session
+
+Rules:
+- Write in the user's first-person voice, as something they would click ("What did I…", "Find…", "Draft a prompt…").
+- Anchor chips in CONCRETE topics from the session titles and summaries — the feature, bug, or artifact itself ("the usage daemon fix", "the onboarding wizard"), not just repository names. A project name may appear in at most two of the four labels; a label with a topic and no project name is often better.
+- Use project display names exactly as given in the digest.
+- Specific and tempting beats generic. ≤ 90 characters per label.
+- Output ONLY a JSON array: [{"label": "...", "category": "recap|find|synthesize|handoff"}, ...] — no prose, no markdown fence.`;
+
+const suggestionSchema = z
+  .array(
+    z.object({
+      label: z.string().min(1),
+      category: z.enum(["recap", "find", "synthesize", "handoff"]),
+    }),
+  )
+  .length(4)
+  // One chip per capability — the UI keys rows by category, and a model
+  // that doubles up (two "find"s) would collide.
+  .refine((arr) => new Set(arr.map((s) => s.category)).size === 4);
+
+/** Pull the first JSON array out of the response — smaller models wrap it
+ *  in preambles and fences no matter what the prompt says — then validate.
+ *  Returns null on any mismatch; callers fall back to deterministic. */
+export function parseSuggestions(content: string): Suggestion[] | null {
+  const start = content.indexOf("[");
+  if (start === -1) return null;
+  // Try every closing bracket from the end inward: trailing prose that
+  // happens to contain "]" must not poison an otherwise valid array.
+  for (let end = content.lastIndexOf("]"); end > start; end = content.lastIndexOf("]", end - 1)) {
+    try {
+      const result = suggestionSchema.safeParse(JSON.parse(content.slice(start, end + 1)));
+      if (!result.success) return null;
+      return result.data.map((s) => ({ ...s, label: s.label.slice(0, LABEL_MAX) }));
+    } catch {
+      /* unbalanced slice — try the next candidate bracket */
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,98 @@
+import { describe, expect, test, vi } from "vitest";
+import type { IndexDoc } from "./types";
+
+const doc = (over: Partial<IndexDoc>): IndexDoc => ({
+  version: 2,
+  sessionId: "s1",
+  agent: "claude-code",
+  project: "/repo/a",
+  day: "2026-07-01",
+  startIso: "2026-07-01T10:00:00Z",
+  title: "t",
+  chunks: [],
+  mtimeMs: 0,
+  sizeBytes: 0,
+  ...over,
+});
+
+const DOCS: IndexDoc[] = [
+  doc({
+    sessionId: "aaa",
+    project: "/repo/a",
+    day: "2026-07-01",
+    startIso: "2026-07-01T10:00:00Z",
+    title: "fix daemon",
+    chunks: [
+      { role: "summary", text: "ai brief" },
+      { role: "user", text: "hello" },
+      { role: "agent", text: "world" },
+    ],
+  }),
+  doc({ sessionId: "bbb", project: "/repo/a", day: "2026-07-03", startIso: "2026-07-03T09:00:00Z", title: "ship PR" }),
+  doc({ sessionId: "ccc", project: "/repo/b", day: "2026-07-02", startIso: "2026-07-02T08:00:00Z", title: "other repo" }),
+];
+
+vi.mock("./index-store", () => ({
+  ensureIndex: async () => DOCS,
+  indexStats: () => ({ sessions: DOCS.length, building: false }),
+}));
+vi.mock("@claude-lens/parser/fs", () => ({
+  getAnySession: async (id: string) => (id === "aaa" ? { meta: { sessionId: id } } : null),
+}));
+vi.mock("@/lib/ai/session-summary", () => ({
+  summarizeSessionForAI: () => "STRUCTURED_DIGEST",
+}));
+
+import { agentTools } from "./tools";
+
+describe("list_projects", () => {
+  test("aggregates session counts and last-activity day, newest project first", async () => {
+    const out = JSON.parse(await agentTools.call("list_projects", {}));
+    expect(out.projects).toEqual([
+      { project: "/repo/a", sessions: 2, lastDay: "2026-07-03" },
+      { project: "/repo/b", sessions: 1, lastDay: "2026-07-02" },
+    ]);
+  });
+});
+
+describe("get_session", () => {
+  test("full_text returns chunk text with roles, skipping nothing", async () => {
+    const out = await agentTools.call("get_session", { session_id: "aaa", mode: "full_text" });
+    expect(out).toContain("[user] hello");
+    expect(out).toContain("[agent] world");
+  });
+
+  test("full_text on an unindexed session errors", async () => {
+    await expect(agentTools.call("get_session", { session_id: "zzz", mode: "full_text" })).rejects.toThrow(
+      /not found in index/,
+    );
+  });
+
+  test("summary mode prepends indexed AI summary chunks to the digest", async () => {
+    const out = await agentTools.call("get_session", { session_id: "aaa" });
+    expect(out).toContain("## AI summary\nai brief");
+    expect(out).toContain("STRUCTURED_DIGEST");
+  });
+
+  test("summary mode errors when the transcript is gone", async () => {
+    await expect(agentTools.call("get_session", { session_id: "bbb" })).rejects.toThrow(/not found/);
+  });
+});
+
+describe("list_sessions", () => {
+  test("filters by project and date bounds, newest first", async () => {
+    const out = JSON.parse(await agentTools.call("list_sessions", { project: "/repo/a", after: "2026-07-02" }));
+    expect(out.total).toBe(1);
+    expect(out.sessions[0]).toMatchObject({ session_id: "bbb", url: "/sessions/bbb" });
+  });
+
+  test("unfiltered list is sorted by startIso descending and respects limit", async () => {
+    const out = JSON.parse(await agentTools.call("list_sessions", { limit: 2 }));
+    expect(out.total).toBe(3);
+    expect(out.sessions.map((s: { session_id: string }) => s.session_id)).toEqual(["bbb", "ccc"]);
+  });
+});
+
+test("unknown tool throws", async () => {
+  await expect(agentTools.call("nope", {})).rejects.toThrow(/unknown tool/);
+});

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

@@ -0,0 +1,176 @@
+import { getAnySession } from "@claude-lens/parser/fs";
+import { summarizeSessionForAI } from "@/lib/ai/session-summary";
+import { ensureIndex, indexStats } from "./index-store";
+import { searchDocs } from "./search";
+import type { McpToolDef, McpTools } from "./mcp";
+import type { SearchFilters } from "./types";
+
+const FULL_TEXT_MAX = 48_000;
+
+const DEFS: McpToolDef[] = [
+  {
+    name: "search_sessions",
+    description:
+      "Full-text search across every locally recorded coding-agent session (Claude Code, Codex, Gemini, …). " +
+      "Searches what the user and the agent actually said, plus AI-written session summaries. " +
+      "Multi-word queries are ranked-OR (sessions matching all words rank first); wrap a phrase in double quotes for exact match. " +
+      "Returns ranked hits with snippets and a dashboard url per session. " +
+      "Run several differently-worded searches when the first one isn't conclusive.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search terms. Quote phrases for exact match." },
+        project: { type: "string", description: "Exact canonical project path filter, e.g. /Users/me/Repo/foo" },
+        agent: { type: "string", description: "Agent source filter: claude-code | codex | gemini-cli | …" },
+        after: { type: "string", description: "Only sessions starting on/after this local day (YYYY-MM-DD)" },
+        before: { type: "string", description: "Only sessions starting on/before this local day (YYYY-MM-DD)" },
+        limit: { type: "number", description: "Max hits to return (default 10, max 25)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "get_session",
+    description:
+      "Fetch one session by id. mode=summary (default) returns a compact structured digest: metadata, first user message, " +
+      "turn-by-turn timeline, PRs shipped, errors, final message. mode=full_text returns the raw conversational text " +
+      "(user + agent messages, capped). Use summary first; full_text only when you need exact wording.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: { type: "string" },
+        mode: { type: "string", enum: ["summary", "full_text"] },
+      },
+      required: ["session_id"],
+    },
+  },
+  {
+    name: "list_sessions",
+    description:
+      "List recent sessions (newest first) with title, project, day, and agent. " +
+      "Use for time- or project-scoped questions like 'what did I work on last Tuesday' — filter with after/before/project.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Exact canonical project path filter" },
+        agent: { type: "string" },
+        after: { type: "string", description: "YYYY-MM-DD inclusive" },
+        before: { type: "string", description: "YYYY-MM-DD inclusive" },
+        limit: { type: "number", description: "Default 20, max 100" },
+      },
+    },
+  },
+  {
+    name: "list_projects",
+    description: "List every project that has recorded sessions, with session counts and the most recent activity day.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+type SearchArgs = SearchFilters & { query: string; limit?: number };
+type GetArgs = { session_id: string; mode?: "summary" | "full_text" };
+type ListArgs = SearchFilters & { limit?: number };
+
+async function searchSessions(args: SearchArgs): Promise<string> {
+  const docs = await ensureIndex();
+  const limit = Math.min(Math.max(1, args.limit ?? 10), 25);
+  const { hits, total } = searchDocs(docs, args.query, {
+    limit,
+    filters: { project: args.project, agent: args.agent, after: args.after, before: args.before },
+  });
+  return JSON.stringify({
+    indexed_sessions: indexStats().sessions,
+    total_matches: total,
+    hits: hits.map((h) => ({
+      session_id: h.sessionId,
+      url: `/sessions/${h.sessionId}`,
+      agent: h.agent,
+      project: h.project,
+      day: h.day,
+      title: h.title,
+      matched_terms: h.matchedTerms,
+      snippets: h.snippets,
+    })),
+  });
+}
+
+async function getSessionTool(args: GetArgs): Promise<string> {
+  const docs = await ensureIndex();
+  const doc = docs.find((d) => d.sessionId === args.session_id);
+  if (args.mode === "full_text") {
+    if (!doc) throw new Error(`session not found in index: ${args.session_id}`);
+    let out = `# Session ${doc.sessionId}\nproject: ${doc.project}\nday: ${doc.day}\nagent: ${doc.agent}\n\n`;
+    for (const c of doc.chunks) {
+      const line = `[${c.role}] ${c.text}\n\n`;
+      if (out.length + line.length > FULL_TEXT_MAX) {
+        out += "…(truncated)";
+        break;
+      }
+      out += line;
+    }
+    return out;
+  }
+  const detail = await getAnySession(args.session_id);
+  if (!detail) throw new Error(`session not found: ${args.session_id}`);
+  const summaries = doc?.chunks.filter((c) => c.role === "summary").map((c) => c.text) ?? [];
+  const header = summaries.length ? `## AI summary\n${summaries.join("\n")}\n\n` : "";
+  return header + summarizeSessionForAI(detail);
+}
+
+async function listSessions(args: ListArgs): Promise<string> {
+  const docs = await ensureIndex();
+  const limit = Math.min(Math.max(1, args.limit ?? 20), 100);
+  const filtered = docs
+    .filter(
+      (d) =>
+        (!args.project || d.project === args.project) &&
+        (!args.agent || d.agent === args.agent) &&
+        (!args.after || d.day >= args.after) &&
+        (!args.before || d.day <= args.before),
+    )
+    .sort((a, b) => (b.startIso ?? "").localeCompare(a.startIso ?? ""));
+  return JSON.stringify({
+    total: filtered.length,
+    sessions: filtered.slice(0, limit).map((d) => ({
+      session_id: d.sessionId,
+      url: `/sessions/${d.sessionId}`,
+      agent: d.agent,
+      project: d.project,
+      day: d.day,
+      title: d.title,
+    })),
+  });
+}
+
+async function listProjects(): Promise<string> {
+  const docs = await ensureIndex();
+  const byProject = new Map<string, { sessions: number; lastDay: string }>();
+  for (const d of docs) {
+    const cur = byProject.get(d.project) ?? { sessions: 0, lastDay: "" };
+    cur.sessions++;
+    if (d.day > cur.lastDay) cur.lastDay = d.day;
+    byProject.set(d.project, cur);
+  }
+  const projects = Array.from(byProject.entries())
+    .map(([project, v]) => ({ project, ...v }))
+    .sort((a, b) => b.lastDay.localeCompare(a.lastDay));
+  return JSON.stringify({ projects });
+}
+
+export const agentTools: McpTools = {
+  defs: DEFS,
+  call: async (name, args) => {
+    switch (name) {
+      case "search_sessions":
+        return searchSessions(args as SearchArgs);
+      case "get_session":
+        return getSessionTool(args as GetArgs);
+      case "list_sessions":
+        return listSessions(args as ListArgs);
+      case "list_projects":
+        return listProjects();
+      default:
+        throw new Error(`unknown tool: ${name}`);
+    }
+  },
+};

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

@@ -0,0 +1,50 @@
+export const INDEX_VERSION = 2;
+
+export type IndexChunk = {
+  role: "user" | "agent" | "summary";
+  text: string;
+  /** event index in the source transcript, when applicable */
+  idx?: number;
+};
+
+/** One searchable session — extracted conversational text plus metadata. */
+export type IndexDoc = {
+  version: number;
+  sessionId: string;
+  agent: string;
+  /** canonical project name (worktrees rolled up) */
+  project: string;
+  /** GitHub repo name from the origin remote — the display name the rest of
+   *  the UI uses when the folder is named something else. */
+  repoName?: string;
+  /** local day of session start, YYYY-MM-DD */
+  day: string;
+  startIso?: string;
+  endIso?: string;
+  title: string;
+  chunks: IndexChunk[];
+  truncated?: boolean;
+  mtimeMs: number;
+  sizeBytes: number;
+};
+
+export type SearchFilters = {
+  project?: string;
+  agent?: string;
+  /** inclusive YYYY-MM-DD bounds on the session's start day */
+  after?: string;
+  before?: string;
+};
+
+export type SearchSnippet = { role: string; text: string };
+
+export type SearchHit = {
+  sessionId: string;
+  agent: string;
+  project: string;
+  day: string;
+  title: string;
+  score: number;
+  matchedTerms: string[];
+  snippets: SearchSnippet[];
+};