@kyleparrott/where-was-i 0.1.0

package/dist/src/mcp.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadWhereWasIConfig, mergeEmbeddingConfig } from "./core/config.js";
+import { runDoctor } from "./core/doctor.js";
+import { indexCodexSessions } from "./core/indexer.js";
+import { resetIndexFiles } from "./core/reset.js";
+import { resolveConfiguredSearchMode } from "./core/search-mode.js";
+import { groupSearchResultsBySession, readMessageContext, readSession, readTurn, resolveMessageLocator, searchSessions } from "./core/search.js";
+import { clearSemanticEmbeddings, indexSemanticChunks } from "./core/semantic.js";
+const appConfig = loadWhereWasIConfig();
+const startupIndexState = {
+    lexical: startupTaskState(appConfig.startup.lexical),
+    semantic: startupTaskState(appConfig.startup.semantic)
+};
+const server = new McpServer({
+    name: "where-was-i",
+    version: "0.1.0"
+});
+server.registerTool("search_agent_sessions", {
+    title: "Search Agent Sessions",
+    description: "Find relevant indexed agent sessions from a natural-language clue. Results are grouped by session and include message IDs plus openable locators.",
+    inputSchema: {
+        query: z.string().min(1).describe("Natural-language clue for the session or message to find."),
+        mode: z
+            .enum(["auto", "fts", "semantic", "hybrid"])
+            .optional()
+            .describe("Search strategy. auto uses hybrid when semantic vectors are usable, otherwise fts."),
+        limit: z.number().int().min(1).max(50).optional().describe("Maximum grouped sessions to return.")
+    },
+    outputSchema: {
+        requestedMode: z.enum(["auto", "fts", "semantic", "hybrid"]),
+        mode: z.enum(["fts", "semantic", "hybrid"]),
+        results: z.array(z.unknown())
+    }
+}, async ({ query, mode, limit }) => {
+    const requestedMode = mode ?? "auto";
+    const selectedMode = await resolveConfiguredSearchMode({
+        dbPath: appConfig.dbPath,
+        requestedMode,
+        embedding: mergeEmbeddingConfig(appConfig)
+    });
+    const results = await searchSessions({
+        dbPath: appConfig.dbPath,
+        query,
+        limit,
+        mode: selectedMode,
+        embedding: mergeEmbeddingConfig(appConfig)
+    });
+    return structuredResult({
+        requestedMode,
+        mode: selectedMode,
+        results: compactGroupedResults(results)
+    });
+});
+server.registerTool("read_agent_session", {
+    title: "Read Agent Session",
+    description: "Read indexed messages for a specific local session.",
+    inputSchema: {
+        sessionId: z.string().min(1).describe("Session ID returned by search_agent_sessions."),
+        limit: z.number().int().min(1).max(500).optional().describe("Maximum messages to return."),
+        offset: z.number().int().min(0).optional().describe("Number of session messages to skip before reading.")
+    },
+    outputSchema: {
+        sessionId: z.string(),
+        messages: z.array(z.unknown())
+    }
+}, async ({ sessionId, limit, offset }) => {
+    const messages = readSession(appConfig.dbPath, sessionId, limit, offset);
+    return structuredResult({ sessionId, messages });
+});
+server.registerTool("read_agent_message_context", {
+    title: "Read Agent Message Context",
+    description: "Read indexed messages around a specific search-hit message.",
+    inputSchema: {
+        messageId: z.string().min(1).describe("Message ID returned by search_agent_sessions."),
+        before: z.number().int().min(0).max(20).optional().describe("Messages before the target message."),
+        after: z.number().int().min(0).max(20).optional().describe("Messages after the target message.")
+    },
+    outputSchema: {
+        messageId: z.string(),
+        context: z.unknown()
+    }
+}, async ({ messageId, before, after }) => {
+    const context = readMessageContext(appConfig.dbPath, messageId, before, after);
+    return structuredResult({ messageId, context });
+});
+server.registerTool("read_agent_turn", {
+    title: "Read Agent Turn",
+    description: "Read all indexed messages in a single turn.",
+    inputSchema: {
+        turnId: z.string().min(1).describe("Turn ID returned by search_agent_sessions."),
+        limit: z.number().int().min(1).max(100).optional().describe("Maximum turn messages to return.")
+    },
+    outputSchema: {
+        turnId: z.string(),
+        messages: z.array(z.unknown())
+    }
+}, async ({ turnId, limit }) => {
+    const messages = readTurn(appConfig.dbPath, turnId, limit);
+    return structuredResult({ turnId, messages });
+});
+server.registerTool("resolve_agent_session_message", {
+    title: "Resolve Agent Session Message",
+    description: "Resolve a message ID to durable message locators and openable fallback links.",
+    inputSchema: {
+        messageId: z.string().min(1).describe("Message ID returned by search_agent_sessions.")
+    },
+    outputSchema: {
+        message: z.unknown()
+    }
+}, async ({ messageId }) => {
+    const resolved = resolveMessageLocator(appConfig.dbPath, messageId);
+    if (!resolved) {
+        throw new Error(`Message not found: ${messageId}`);
+    }
+    return structuredResult({ message: resolved });
+});
+server.registerTool("index_agent_sessions", {
+    title: "Index Agent Sessions",
+    description: "Refresh the local lexical Codex session index. Semantic embeddings are indexed by index_agent_session_embeddings.",
+    inputSchema: {
+        includeArchived: z.boolean().optional().describe("Include archived Codex sessions."),
+        recent: z.number().int().min(1).optional().describe("Only index the N most recently changed session files."),
+        sessionIds: z.array(z.string().min(1)).optional().describe("Only index specific session IDs."),
+        force: z.boolean().optional().describe("Reindex files even when size and mtime are unchanged.")
+    },
+    outputSchema: {
+        lexical: z.unknown()
+    }
+}, async ({ includeArchived, recent, sessionIds, force }) => {
+    const lexical = indexCodexSessions({
+        dbPath: appConfig.dbPath,
+        codexHome: appConfig.codexHome,
+        includeArchived,
+        recent,
+        sessionIds,
+        force
+    });
+    return structuredResult({ lexical });
+});
+server.registerTool("index_agent_session_embeddings", {
+    title: "Index Agent Session Embeddings",
+    description: "Refresh semantic embeddings for indexed user and assistant messages using the configured embedding provider.",
+    inputSchema: {
+        maxChunks: z.number().int().min(1).optional().describe("Maximum missing semantic chunks to embed this run."),
+        sessionIds: z.array(z.string().min(1)).optional().describe("Only embed chunks for specific session IDs.")
+    },
+    outputSchema: {
+        semantic: z.unknown()
+    }
+}, async ({ maxChunks, sessionIds }) => {
+    const semantic = await indexSemanticChunks({
+        dbPath: appConfig.dbPath,
+        embedding: mergeEmbeddingConfig(appConfig),
+        maxChunks,
+        sessionIds
+    });
+    return structuredResult({ semantic });
+});
+server.registerTool("clear_agent_session_embeddings", {
+    title: "Clear Agent Session Embeddings",
+    description: "Delete all derived semantic vectors and embedding provider metadata while keeping lexical index data.",
+    inputSchema: {
+        confirm: z.literal("clear").describe("Must be exactly clear to confirm deletion.")
+    },
+    outputSchema: {
+        summary: z.unknown()
+    }
+}, async ({ confirm }) => {
+    if (confirm !== "clear") {
+        throw new Error('Set confirm to "clear" to delete derived embedding vectors.');
+    }
+    const summary = clearSemanticEmbeddings(appConfig.dbPath);
+    return structuredResult({ summary });
+});
+server.registerTool("reset_agent_session_index", {
+    title: "Reset Agent Session Index",
+    description: "Delete the entire derived local SQLite index, including lexical and semantic stores, without touching Codex transcripts.",
+    inputSchema: {
+        confirm: z.literal("reset").describe("Must be exactly reset to confirm deletion.")
+    },
+    outputSchema: {
+        summary: z.unknown()
+    }
+}, async ({ confirm }) => {
+    if (confirm !== "reset") {
+        throw new Error('Set confirm to "reset" to delete the derived local index.');
+    }
+    const summary = resetIndexFiles(appConfig.dbPath);
+    return structuredResult({ summary });
+});
+server.registerTool("agent_session_status", {
+    title: "Agent Session Index Status",
+    description: "Show whether indexed session search is ready, plus path, index, semantic, and startup details.",
+    inputSchema: {},
+    outputSchema: {
+        readyForSearch: z.boolean(),
+        recommendedSearchMode: z.enum(["fts", "hybrid"]),
+        blockingIssues: z.array(z.string()),
+        semanticWarnings: z.array(z.string()),
+        paths: z.unknown(),
+        index: z.unknown(),
+        embedding: z.unknown(),
+        semantic: z.unknown(),
+        startupIndex: z.unknown()
+    }
+}, async () => {
+    const report = await runDoctor({
+        dbPath: appConfig.dbPath,
+        codexHome: appConfig.codexHome,
+        embedding: mergeEmbeddingConfig(appConfig)
+    });
+    const status = agentStatusFromDoctor(report);
+    return structuredResult({ ...status, startupIndex: startupIndexState });
+});
+function agentStatusFromDoctor(report) {
+    const blockingIssues = [];
+    if (!report.paths.codexHomeExists) {
+        blockingIssues.push(`Codex home does not exist: ${report.paths.codexHome}`);
+    }
+    if (!report.paths.sessionsDirExists) {
+        blockingIssues.push(`Codex sessions directory does not exist: ${report.paths.sessionsDir}`);
+    }
+    if (report.index.messages === 0) {
+        blockingIssues.push("Run index_agent_sessions to build the lexical message index.");
+    }
+    const semanticWarnings = [];
+    const semanticConfigured = Boolean(report.embedding.baseUrl && report.embedding.model);
+    if (semanticConfigured && !report.embedding.available) {
+        semanticWarnings.push(`Embedding provider unavailable: ${report.embedding.error}`);
+    }
+    if (semanticConfigured && report.semantic.missingChunks !== null && report.semantic.missingChunks > 0) {
+        semanticWarnings.push(mcpSemanticRecommendation(report.semantic.recommendation));
+    }
+    if (semanticConfigured && report.semantic.incompatibleStoredVectors > 0) {
+        semanticWarnings.push("Stored semantic vectors are incompatible with the configured embedding provider.");
+    }
+    const semanticUsable = semanticConfigured && report.semantic.indexedChunks > 0 && report.semantic.incompatibleStoredVectors === 0;
+    return {
+        readyForSearch: blockingIssues.length === 0,
+        recommendedSearchMode: semanticUsable ? "hybrid" : "fts",
+        blockingIssues,
+        semanticWarnings,
+        paths: report.paths,
+        index: report.index,
+        embedding: report.embedding,
+        semantic: report.semantic
+    };
+}
+function mcpSemanticRecommendation(recommendation) {
+    if (!recommendation) {
+        return "Call index_agent_session_embeddings to refresh semantic vectors.";
+    }
+    return recommendation
+        .replace(/Run `wwi index --semantic`/g, "Call index_agent_session_embeddings")
+        .replace(/Run `wwi embeddings clear`/g, "Call clear_agent_session_embeddings");
+}
+function structuredResult(value) {
+    return {
+        structuredContent: value,
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
+    };
+}
+function compactGroupedResults(results) {
+    return groupSearchResultsBySession(results).map((group) => ({
+        session: group.session,
+        bestMessage: group.bestMessage,
+        match: group.match,
+        score: group.score,
+        hits: group.hits.map((hit) => ({
+            messageId: hit.messageId,
+            sessionId: hit.sessionId,
+            conversationId: hit.conversationId,
+            turnId: hit.turnId,
+            role: hit.role,
+            timestamp: hit.timestamp,
+            preview: hit.preview,
+            locator: hit.locator,
+            links: hit.links,
+            match: hit.match,
+            scores: hit.scores
+        }))
+    }));
+}
+const transport = new StdioServerTransport();
+if (hasBlockingStartup()) {
+    await startStartupIndex();
+}
+await server.connect(transport);
+if (!hasBlockingStartup()) {
+    void startStartupIndex();
+}
+async function startStartupIndex() {
+    const blockingTasks = [];
+    if (appConfig.startup.lexical !== "off") {
+        const task = runStartupTask(startupIndexState.lexical, () => indexCodexSessions({
+            dbPath: appConfig.dbPath,
+            codexHome: appConfig.codexHome
+        }));
+        if (appConfig.startup.lexical === "blocking") {
+            blockingTasks.push(task);
+        }
+    }
+    if (appConfig.startup.semantic !== "off") {
+        const task = runStartupTask(startupIndexState.semantic, () => indexSemanticChunks({
+            dbPath: appConfig.dbPath,
+            embedding: appConfig.semantic.embedding,
+            maxChunks: appConfig.semantic.startupMaxChunks ?? undefined
+        }));
+        if (appConfig.startup.semantic === "blocking") {
+            blockingTasks.push(task);
+        }
+    }
+    await Promise.all(blockingTasks);
+}
+function hasBlockingStartup() {
+    return appConfig.startup.lexical === "blocking" || appConfig.startup.semantic === "blocking";
+}
+function startupTaskState(mode) {
+    return {
+        mode,
+        status: mode === "off" ? "off" : "queued",
+        summary: null,
+        startedAt: null,
+        completedAt: null,
+        error: null
+    };
+}
+async function runStartupTask(state, task) {
+    state.status = "running";
+    state.startedAt = new Date().toISOString();
+    try {
+        state.summary = await task();
+        state.status = "complete";
+    }
+    catch (error) {
+        state.error = error instanceof Error ? error.message : String(error);
+        state.status = "failed";
+    }
+    finally {
+        state.completedAt = new Date().toISOString();
+    }
+}

package/dist/src/web-client.js

@@ -0,0 +1,61 @@
+export const WEB_CLIENT_SCRIPT = `
+(() => {
+  const panel = document.querySelector("[data-embedding-job-id]");
+  if (!panel) {
+    return;
+  }
+  const jobId = panel.getAttribute("data-embedding-job-id");
+  const jobStatus = panel.getAttribute("data-embedding-job-status");
+  if (!jobId || jobStatus !== "running") {
+    return;
+  }
+
+  const statusSlot = document.getElementById("embedding-status");
+  const jobSlot = document.getElementById("embedding-job-slot");
+  const submitButton = document.getElementById("embedding-submit");
+  let failures = 0;
+
+  async function poll() {
+    try {
+      const response = await fetch("/embedding-jobs/" + encodeURIComponent(jobId), {
+        headers: { accept: "application/json" }
+      });
+      if (!response.ok) {
+        throw new Error("Embedding job status failed.");
+      }
+      const update = await response.json();
+      if (statusSlot && typeof update.statusHtml === "string") {
+        statusSlot.innerHTML = update.statusHtml;
+      }
+      if (jobSlot && typeof update.jobHtml === "string") {
+        jobSlot.innerHTML = update.jobHtml;
+      }
+      if (submitButton) {
+        submitButton.disabled = Boolean(update.buttonDisabled);
+        if (typeof update.buttonText === "string") {
+          submitButton.textContent = update.buttonText;
+        }
+      }
+      panel.setAttribute("data-embedding-job-status", update.job?.status ?? "complete");
+      failures = 0;
+      if (update.done) {
+        return;
+      }
+    } catch {
+      failures += 1;
+      if (failures >= 5) {
+        if (jobSlot) {
+          jobSlot.insertAdjacentHTML(
+            "beforeend",
+            '<p class="progress-error">Live progress paused. Refresh to check the latest status.</p>'
+          );
+        }
+        return;
+      }
+    }
+    window.setTimeout(poll, 1000);
+  }
+
+  window.setTimeout(poll, 250);
+})();
+`;

package/dist/src/web-settings.js

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import path from "node:path";
+import { defaultConfigTemplate, validateWhereWasIConfigObject } from "./core/config.js";
+export const STARTUP_MODES = ["off", "background", "blocking"];
+export function settingsViewModel(configPath, saved) {
+    const { raw, exists } = readRawConfig(configPath);
+    const semantic = asRecord(raw.semantic);
+    const provider = asRecord(semantic.provider ?? semantic);
+    const startup = asRecord(raw.startup);
+    const apiKey = stringValue(provider.apiKey);
+    return {
+        configPath,
+        exists,
+        saved,
+        errors: [],
+        values: {
+            dbPath: stringValue(raw.dbPath) ?? "~/.where-was-i/index.sqlite",
+            codexHome: stringValue(raw.codexHome) ?? "~/.codex",
+            startupLexical: startupModeValue(startup.lexical, "off"),
+            startupSemantic: startupModeValue(startup.semantic, "off"),
+            semanticStartupMaxChunks: semantic.startupMaxChunks === null ? "" : stringValue(semantic.startupMaxChunks) ?? "100",
+            embeddingBaseUrl: stringValue(provider.baseUrl) ?? "",
+            embeddingModel: stringValue(provider.model) ?? "",
+            embeddingApiKeyEnv: stringValue(provider.apiKeyEnv) ?? "WHERE_WAS_I_EMBEDDING_API_KEY",
+            embeddingApiKey: "",
+            embeddingApiKeyStored: Boolean(apiKey),
+            embeddingApiKeyClear: false,
+            embeddingTimeoutMs: stringValue(provider.timeoutMs) ?? ""
+        }
+    };
+}
+export function saveSettings(configPath, params) {
+    const current = settingsViewModel(configPath, false).values;
+    const values = {
+        dbPath: formValue(params, "dbPath"),
+        codexHome: formValue(params, "codexHome"),
+        startupLexical: startupModeValue(params.get("startupLexical"), "off"),
+        startupSemantic: startupModeValue(params.get("startupSemantic"), "off"),
+        semanticStartupMaxChunks: formValue(params, "semanticStartupMaxChunks"),
+        embeddingBaseUrl: formValue(params, "embeddingBaseUrl"),
+        embeddingModel: formValue(params, "embeddingModel"),
+        embeddingApiKeyEnv: formValue(params, "embeddingApiKeyEnv"),
+        embeddingApiKey: formValue(params, "embeddingApiKey"),
+        embeddingApiKeyStored: current.embeddingApiKeyStored,
+        embeddingApiKeyClear: params.get("embeddingApiKeyClear") === "on",
+        embeddingTimeoutMs: formValue(params, "embeddingTimeoutMs")
+    };
+    const errors = [];
+    if (!values.dbPath)
+        errors.push("Index path is required.");
+    if (!values.codexHome)
+        errors.push("Codex home is required.");
+    if (!STARTUP_MODES.includes(values.startupLexical))
+        errors.push("Lexical startup mode is invalid.");
+    if (!STARTUP_MODES.includes(values.startupSemantic))
+        errors.push("Semantic startup mode is invalid.");
+    const startupMaxChunks = optionalPositiveInteger(values.semanticStartupMaxChunks, "Semantic startup chunk cap", errors, true);
+    const timeoutMs = optionalPositiveInteger(values.embeddingTimeoutMs, "Timeout ms", errors, false);
+    if (errors.length > 0) {
+        return { values, errors };
+    }
+    const { raw } = readRawConfig(configPath);
+    const next = { ...raw };
+    next.dbPath = values.dbPath;
+    next.codexHome = values.codexHome;
+    next.startup = {
+        ...asRecord(raw.startup),
+        lexical: values.startupLexical,
+        semantic: values.startupSemantic
+    };
+    const rawSemantic = asRecord(raw.semantic);
+    const rawProvider = asRecord(rawSemantic.provider ?? rawSemantic);
+    const provider = { ...rawProvider };
+    setOptionalString(provider, "baseUrl", values.embeddingBaseUrl);
+    setOptionalString(provider, "model", values.embeddingModel);
+    setOptionalString(provider, "apiKeyEnv", values.embeddingApiKeyEnv);
+    if (values.embeddingApiKeyClear) {
+        delete provider.apiKey;
+        values.embeddingApiKeyStored = false;
+    }
+    else if (values.embeddingApiKey) {
+        provider.apiKey = values.embeddingApiKey;
+        values.embeddingApiKeyStored = true;
+    }
+    if (timeoutMs === undefined) {
+        delete provider.timeoutMs;
+    }
+    else {
+        provider.timeoutMs = timeoutMs;
+    }
+    const semantic = { ...rawSemantic, startupMaxChunks, provider };
+    for (const key of ["baseUrl", "model", "apiKey", "apiKeyEnv", "timeoutMs"]) {
+        delete semantic[key];
+    }
+    next.semantic = semantic;
+    try {
+        validateWhereWasIConfigObject(next, configPath);
+        writeConfigAtomically(configPath, next);
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    return { values: { ...values, embeddingApiKey: "" }, errors };
+}
+function readRawConfig(configPath) {
+    if (!fs.existsSync(configPath)) {
+        return { raw: defaultConfigTemplate(), exists: false };
+    }
+    const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    validateWhereWasIConfigObject(parsed, configPath);
+    return { raw: parsed, exists: true };
+}
+function writeConfigAtomically(configPath, value) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    const tempPath = path.join(path.dirname(configPath), `.${path.basename(configPath)}.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tempPath, configPath);
+    fs.chmodSync(configPath, 0o600);
+}
+function optionalPositiveInteger(value, label, errors, allowOff) {
+    const trimmed = value.trim();
+    if (!trimmed || (allowOff && trimmed.toLowerCase() === "off")) {
+        return allowOff ? null : undefined;
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        errors.push(`${label} must be a positive integer${allowOff ? " or blank" : ""}.`);
+        return undefined;
+    }
+    return parsed;
+}
+function startupModeValue(value, fallback) {
+    return value === "off" || value === "background" || value === "blocking" ? value : fallback;
+}
+function setOptionalString(target, key, value) {
+    if (value) {
+        target[key] = value;
+    }
+    else {
+        delete target[key];
+    }
+}
+function formValue(params, key) {
+    return (params.get(key) ?? "").trim();
+}
+function stringValue(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return undefined;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}