@mcoda/mswarm 0.1.57 → 0.1.61

package/dist/vendor/codali/docdex/DocdexClient.js

@@ -0,0 +1,785 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+export class DocdexRuntimeError extends Error {
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = code;
+        this.code = code;
+        this.status = options.status;
+        this.retryable = options.retryable ?? code === "docdex_unavailable";
+        this.details = options.details;
+    }
+}
+const CAPABILITY_KEYS = [
+    "score_breakdown",
+    "rerank",
+    "snippet_provenance",
+    "retrieval_explanation",
+    "batch_search",
+];
+const DOCDEX_RUNTIME_ERROR_CODES = new Set([
+    "docdex_context_missing",
+    "docdex_api_key_missing",
+    "docdex_operation_not_allowed",
+    "docdex_auth_failed",
+    "docdex_repo_access_denied",
+    "docdex_unavailable",
+]);
+const DOCDEX_RUNTIME_OPERATIONS = new Set([
+    "health",
+    "initialize",
+    "search",
+    "snippet",
+    "open",
+    "symbols",
+    "ast",
+    "impact_graph",
+    "impact_diagnostics",
+    "dag_export",
+    "tree",
+    "memory_save",
+    "memory_recall",
+    "profile_read",
+    "profile_write",
+    "web_research",
+    "chat_context",
+    "rerank",
+    "batch_search",
+    "capabilities",
+    "stats",
+    "files",
+    "repo_inspect",
+    "index_rebuild",
+    "index_ingest",
+    "delegate",
+    "hooks_validate",
+]);
+const MCP_OPERATION_BY_METHOD = {
+    docdex_symbols: "symbols",
+    docdex_ast: "ast",
+    docdex_stats: "stats",
+    docdex_files: "files",
+    docdex_repo_inspect: "repo_inspect",
+    docdex_memory_save: "memory_save",
+    docdex_memory_recall: "memory_recall",
+    docdex_tree: "tree",
+    docdex_open: "open",
+    docdex_get_profile: "profile_read",
+    docdex_save_preference: "profile_write",
+    docdex_web_research: "web_research",
+    docdex_rerank: "rerank",
+    docdex_batch_search: "batch_search",
+    docdex_capabilities: "capabilities",
+};
+export const isDocdexRuntimeErrorCode = (value) => {
+    return typeof value === "string" && DOCDEX_RUNTIME_ERROR_CODES.has(value);
+};
+export const normalizeDocdexRuntimeOperation = (value) => {
+    const normalized = value.trim().replace(/[.-]/g, "_").toLowerCase();
+    const aliases = {
+        impact: "impact_graph",
+        diagnostics: "impact_diagnostics",
+        impact_diagnostics: "impact_diagnostics",
+        web: "web_research",
+        web_search: "web_research",
+        chat: "chat_context",
+        chat_completions: "chat_context",
+        context_chat: "chat_context",
+        open_file: "open",
+        snippet_fetch: "snippet",
+        profile: "profile_read",
+        get_profile: "profile_read",
+        save_preference: "profile_write",
+        memory: "memory_recall",
+        index: "index_rebuild",
+        hooks: "hooks_validate",
+    };
+    const aliased = aliases[normalized];
+    if (aliased)
+        return aliased;
+    return DOCDEX_RUNTIME_OPERATIONS.has(normalized)
+        ? normalized
+        : undefined;
+};
+const escapeRegExp = (value) => {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+};
+export class DocdexClient {
+    constructor(options) {
+        this.options = options;
+        this.healthChecked = false;
+        this.repoInitializeAttempted = false;
+        this.repoId = options.repoId;
+        this.dagSessionId = options.dagSessionId;
+    }
+    setRepoId(repoId) {
+        this.repoId = repoId;
+    }
+    getRepoId() {
+        return this.repoId;
+    }
+    getRepoRoot() {
+        return this.options.repoRoot;
+    }
+    setDagSessionId(sessionId) {
+        this.dagSessionId = sessionId;
+    }
+    getDagSessionId() {
+        return this.dagSessionId;
+    }
+    clearCapabilityCache() {
+        this.capabilitySnapshot = undefined;
+    }
+    runtimeAllowedOperations() {
+        if (!this.options.allowedOperations?.length)
+            return undefined;
+        const operations = this.options.allowedOperations
+            .map((entry) => normalizeDocdexRuntimeOperation(entry))
+            .filter((entry) => Boolean(entry));
+        return operations.length ? new Set(operations) : new Set();
+    }
+    runtimeCapability(operation) {
+        if (!this.options.capabilities)
+            return undefined;
+        for (const [key, value] of Object.entries(this.options.capabilities)) {
+            const normalized = normalizeDocdexRuntimeOperation(key);
+            if (normalized === operation && typeof value === "boolean") {
+                return value;
+            }
+        }
+        return undefined;
+    }
+    redactSensitiveText(text) {
+        let output = text;
+        for (const secret of [this.options.apiKey, this.options.authToken]) {
+            if (typeof secret === "string" && secret.length >= 4) {
+                output = output.replace(new RegExp(escapeRegExp(secret), "g"), "[redacted]");
+            }
+        }
+        output = output.replace(/("(?:x-api-key|authorization|api[_-]?key|token|secret)"\s*:\s*")[^"]+(")/gi, "$1[redacted]$2");
+        output = output.replace(/((?:x-api-key|authorization|api[_-]?key|token|secret)\s*[:=]\s*)(?:Bearer\s+)?[^\s,;}]+/gi, "$1[redacted]");
+        return output;
+    }
+    runtimeError(code, message, options = {}) {
+        return new DocdexRuntimeError(code, this.redactSensitiveText(message), options);
+    }
+    assertRuntimeContext(operation) {
+        const credentialSource = this.options.credentialSource;
+        const requiresAttachedKey = credentialSource === "attached_mswarm_api_key";
+        if (requiresAttachedKey && (!this.options.apiKey || this.options.apiKey.trim().length === 0)) {
+            throw this.runtimeError("docdex_api_key_missing", "Docdex attached mswarm API key is required but was not provided.", { retryable: false, details: { operation, credential_source: credentialSource } });
+        }
+        if (this.options.required && this.resolveBaseUrl().length === 0) {
+            throw this.runtimeError("docdex_context_missing", "Docdex base_url is required for this job.", {
+                retryable: false,
+                details: { operation },
+            });
+        }
+        if (this.options.required && requiresAttachedKey && !this.repoId) {
+            throw this.runtimeError("docdex_context_missing", "Docdex repo_id is required for this job.", {
+                retryable: false,
+                details: { operation },
+            });
+        }
+    }
+    assertOperationAllowed(operation) {
+        this.assertRuntimeContext(operation);
+        const allowedOperations = this.runtimeAllowedOperations();
+        if (allowedOperations && !allowedOperations.has(operation)) {
+            throw this.runtimeError("docdex_operation_not_allowed", `Docdex operation is not allowed by this job: ${operation}`, { retryable: false, details: { operation } });
+        }
+        if (this.runtimeCapability(operation) === false) {
+            throw this.runtimeError("docdex_operation_not_allowed", `Docdex operation is disabled by this job capability map: ${operation}`, { retryable: false, details: { operation } });
+        }
+    }
+    resolveBaseUrl() {
+        const base = this.options.baseUrl.trim();
+        return base.endsWith("/") ? base.slice(0, -1) : base;
+    }
+    buildHeaders(dagSessionId) {
+        const headers = { "content-type": "application/json" };
+        if (this.options.apiKey) {
+            headers["x-api-key"] = this.options.apiKey;
+        }
+        else if (this.options.authToken) {
+            headers.authorization = `Bearer ${this.options.authToken}`;
+        }
+        if (this.repoId)
+            headers["x-docdex-repo-id"] = this.repoId;
+        if (this.options.repoRoot)
+            headers["x-docdex-repo-root"] = path.resolve(this.options.repoRoot);
+        const resolvedDagSessionId = dagSessionId ?? this.dagSessionId;
+        if (resolvedDagSessionId)
+            headers["x-docdex-dag-session"] = resolvedDagSessionId;
+        return headers;
+    }
+    async ensureHealth() {
+        if (this.healthChecked)
+            return;
+        let ok = false;
+        try {
+            ok = await this.healthCheck();
+        }
+        catch (error) {
+            if (error instanceof DocdexRuntimeError)
+                throw error;
+            throw this.runtimeError("docdex_unavailable", `Docdex health check failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true });
+        }
+        if (!ok) {
+            throw this.runtimeError("docdex_unavailable", "Docdex health check failed", {
+                retryable: true,
+            });
+        }
+    }
+    async healthCheck() {
+        let response;
+        try {
+            response = await fetch(`${this.resolveBaseUrl()}/healthz`);
+        }
+        catch (error) {
+            throw this.runtimeError("docdex_unavailable", `Docdex health check failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true });
+        }
+        this.healthChecked = response.ok;
+        return response.ok;
+    }
+    async initialize(rootUri) {
+        this.assertOperationAllowed("initialize");
+        return this.initializeRepo(rootUri);
+    }
+    async initializeRepo(rootUri) {
+        await this.ensureHealth();
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/initialize`, {
+            method: "POST",
+            headers: this.buildHeaders(),
+            body: JSON.stringify({ rootUri }),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "initialize");
+        }
+        const payload = (await response.json());
+        const repoId = (payload.repo_id ?? payload.repoId ?? payload.repo);
+        const repoRoot = (payload.repo_root ?? payload.repoRoot);
+        if (repoId)
+            this.repoId = repoId;
+        return { repoId, repoRoot };
+    }
+    async ensureRepoInitialized() {
+        if (this.repoId || this.repoInitializeAttempted || !this.options.repoRoot)
+            return;
+        this.repoInitializeAttempted = true;
+        try {
+            await this.initializeRepo(pathToFileURL(path.resolve(this.options.repoRoot)).toString());
+        }
+        catch {
+            // Keep endpoint-specific calls responsible for reporting the final failure.
+            // Single-repo daemons can still accept repo_root without a prior initialize.
+        }
+    }
+    withRepoId(params) {
+        if (this.repoId)
+            params.set("repo_id", this.repoId);
+        if (this.options.repoRoot)
+            params.set("repo_root", path.resolve(this.options.repoRoot));
+    }
+    extractErrorCode(body) {
+        const parsed = this.tryParseJson(body);
+        if (!parsed || typeof parsed !== "object")
+            return undefined;
+        const record = parsed;
+        const error = record.error && typeof record.error === "object"
+            ? record.error
+            : undefined;
+        const code = error?.code ?? record.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    mapResponseErrorCode(status, body) {
+        const extracted = this.extractErrorCode(body);
+        if (isDocdexRuntimeErrorCode(extracted))
+            return extracted;
+        const normalized = `${extracted ?? ""} ${body}`.toLowerCase();
+        if (/introspection_unavailable|unavailable|timeout|timed out|econnrefused|enotfound/.test(normalized)) {
+            return "docdex_unavailable";
+        }
+        if (/repo_access_denied|unknown_repo|repo.*denied|denied.*repo/.test(normalized)) {
+            return "docdex_repo_access_denied";
+        }
+        if (/scope_denied|operation_not_allowed|encrypted_operation_disabled|not allowed|forbidden_operation/.test(normalized)) {
+            return "docdex_operation_not_allowed";
+        }
+        if (status === 401 || status === 403 || /invalid_credentials|missing_credentials|ambiguous_credentials/.test(normalized)) {
+            return "docdex_auth_failed";
+        }
+        return "docdex_unavailable";
+    }
+    async throwResponseError(response, operation) {
+        const body = await response.text();
+        const code = this.mapResponseErrorCode(response.status, body);
+        throw this.runtimeError(code, `Docdex ${operation} failed (${response.status}): ${body}`, {
+            status: response.status,
+            retryable: code === "docdex_unavailable" && response.status >= 500,
+            details: { operation },
+        });
+    }
+    async search(query, options = {}) {
+        this.assertOperationAllowed("search");
+        await this.ensureHealth();
+        await this.ensureRepoInitialized();
+        const params = new URLSearchParams({ q: query });
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        const dagSessionId = options.dagSessionId ?? this.dagSessionId;
+        if (dagSessionId)
+            params.set("dag_session_id", dagSessionId);
+        this.withRepoId(params);
+        const response = await fetch(`${this.resolveBaseUrl()}/search?${params.toString()}`, {
+            headers: this.buildHeaders(dagSessionId),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "search");
+        }
+        return response.json();
+    }
+    async openSnippet(docId, options = {}) {
+        this.assertOperationAllowed("snippet");
+        await this.ensureHealth();
+        await this.ensureRepoInitialized();
+        const params = new URLSearchParams();
+        if (options.window !== undefined)
+            params.set("window", String(options.window));
+        if (options.textOnly)
+            params.set("text_only", "true");
+        this.withRepoId(params);
+        const response = await fetch(`${this.resolveBaseUrl()}/snippet/${encodeURIComponent(docId)}?${params.toString()}`, {
+            headers: this.buildHeaders(),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "snippet");
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            return response.json();
+        }
+        return response.text();
+    }
+    async impactGraph(file, options = {}) {
+        this.assertOperationAllowed("impact_graph");
+        await this.ensureHealth();
+        await this.ensureRepoInitialized();
+        const params = new URLSearchParams({ file });
+        if (options.maxDepth !== undefined)
+            params.set("max_depth", String(options.maxDepth));
+        if (options.maxEdges !== undefined)
+            params.set("max_edges", String(options.maxEdges));
+        if (options.edgeTypes?.length)
+            params.set("edge_types", options.edgeTypes.join(","));
+        this.withRepoId(params);
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/graph/impact?${params.toString()}`, {
+            headers: this.buildHeaders(),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "impact graph");
+        }
+        return response.json();
+    }
+    async impactDiagnostics(options = {}) {
+        this.assertOperationAllowed("impact_diagnostics");
+        await this.ensureHealth();
+        await this.ensureRepoInitialized();
+        const params = new URLSearchParams();
+        if (options.file)
+            params.set("file", options.file);
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.offset !== undefined)
+            params.set("offset", String(options.offset));
+        this.withRepoId(params);
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/graph/impact/diagnostics?${params.toString()}`, {
+            headers: this.buildHeaders(),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "impact diagnostics");
+        }
+        return response.json();
+    }
+    async indexRebuild(libsSources) {
+        this.assertOperationAllowed("index_rebuild");
+        await this.ensureHealth();
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/index/rebuild`, {
+            method: "POST",
+            headers: this.buildHeaders(),
+            body: JSON.stringify(libsSources ? { libs_sources: libsSources } : {}),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "index rebuild");
+        }
+        return response.json();
+    }
+    async indexIngest(file) {
+        this.assertOperationAllowed("index_ingest");
+        await this.ensureHealth();
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/index/ingest`, {
+            method: "POST",
+            headers: this.buildHeaders(),
+            body: JSON.stringify({ file }),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "index ingest");
+        }
+        return response.json();
+    }
+    async hooksValidate(files) {
+        this.assertOperationAllowed("hooks_validate");
+        await this.ensureHealth();
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/hooks/validate`, {
+            method: "POST",
+            headers: this.buildHeaders(),
+            body: JSON.stringify({ files }),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "hooks validate");
+        }
+        return response.json();
+    }
+    async delegate(payload) {
+        this.assertOperationAllowed("delegate");
+        await this.ensureHealth();
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/delegate`, {
+            method: "POST",
+            headers: this.buildHeaders(),
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "delegate");
+        }
+        return response.json();
+    }
+    async chatContext(messages, options = {}) {
+        this.assertOperationAllowed("chat_context");
+        await this.ensureHealth();
+        await this.ensureRepoInitialized();
+        const body = {
+            messages,
+            stream: false,
+        };
+        if (options.model)
+            body.model = options.model;
+        if (options.maxTokens !== undefined)
+            body.max_tokens = options.maxTokens;
+        if (options.temperature !== undefined)
+            body.temperature = options.temperature;
+        if (options.docdex)
+            body.docdex = options.docdex;
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/chat/completions`, {
+            method: "POST",
+            headers: this.buildHeaders(this.dagSessionId),
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "chat context");
+        }
+        return response.json();
+    }
+    async dagExport(sessionId, options = {}) {
+        this.assertOperationAllowed("dag_export");
+        await this.ensureHealth();
+        await this.ensureRepoInitialized();
+        const params = new URLSearchParams({ session_id: sessionId });
+        if (options.format)
+            params.set("format", options.format);
+        if (options.maxNodes !== undefined)
+            params.set("max_nodes", String(options.maxNodes));
+        this.withRepoId(params);
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/dag/export?${params.toString()}`, {
+            headers: this.buildHeaders(),
+        });
+        const body = await response.text();
+        if (!response.ok) {
+            const code = this.mapResponseErrorCode(response.status, body);
+            throw this.runtimeError(code, `Docdex dag export failed (${response.status}): ${body}`, {
+                status: response.status,
+                retryable: code === "docdex_unavailable" && response.status >= 500,
+                details: { operation: "dag_export" },
+            });
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            try {
+                return JSON.parse(body);
+            }
+            catch {
+                return body;
+            }
+        }
+        return body;
+    }
+    async callMcp(method, params) {
+        const operation = MCP_OPERATION_BY_METHOD[method];
+        if (operation) {
+            this.assertOperationAllowed(operation);
+        }
+        await this.ensureHealth();
+        const payload = {
+            jsonrpc: "2.0",
+            id: randomUUID(),
+            method,
+            params,
+        };
+        const response = await fetch(`${this.resolveBaseUrl()}/v1/mcp`, {
+            method: "POST",
+            headers: this.buildHeaders(),
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "MCP");
+        }
+        const raw = (await response.json());
+        if (raw.error) {
+            const body = JSON.stringify(raw.error);
+            const code = this.mapResponseErrorCode(500, body);
+            throw this.runtimeError(code, raw.error.message ?? "Docdex MCP error", {
+                retryable: code === "docdex_unavailable",
+                details: { method },
+            });
+        }
+        return this.normalizeMcpResult(raw.result);
+    }
+    normalizeMcpResult(payload) {
+        if (!payload || typeof payload !== "object")
+            return payload;
+        const record = payload;
+        if (record.structuredContent !== undefined) {
+            return record.structuredContent;
+        }
+        if (!Array.isArray(record.content) || record.content.length === 0) {
+            return payload;
+        }
+        const textChunks = record.content
+            .map((entry) => {
+            if (!entry || typeof entry !== "object")
+                return undefined;
+            const text = entry.text;
+            return typeof text === "string" ? text : undefined;
+        })
+            .filter((text) => typeof text === "string");
+        if (textChunks.length === 0) {
+            return payload;
+        }
+        const joined = textChunks.join("\n").trim();
+        if (joined.length === 0) {
+            return payload;
+        }
+        const parsed = this.tryParseJson(joined);
+        return parsed ?? joined;
+    }
+    tryParseJson(text) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return undefined;
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    buildProjectParams(extra) {
+        return {
+            project_root: this.options.repoRoot,
+            ...extra,
+        };
+    }
+    defaultCapabilityMap(status) {
+        return {
+            score_breakdown: status,
+            rerank: status,
+            snippet_provenance: status,
+            retrieval_explanation: status,
+            batch_search: status,
+        };
+    }
+    toCapabilityStatus(value) {
+        if (value === true)
+            return "available";
+        if (value === false)
+            return "unavailable";
+        if (typeof value === "number")
+            return value > 0 ? "available" : "unavailable";
+        if (typeof value !== "string")
+            return "unknown";
+        const normalized = value.trim().toLowerCase();
+        if (["available", "enabled", "supported", "ok", "true", "yes"].includes(normalized)) {
+            return "available";
+        }
+        if (["unavailable", "disabled", "unsupported", "none", "false", "no"].includes(normalized)) {
+            return "unavailable";
+        }
+        return "unknown";
+    }
+    normalizeCapabilityPayload(payload) {
+        if (!payload || typeof payload !== "object")
+            return undefined;
+        const record = payload;
+        const source = ((record.capabilities && typeof record.capabilities === "object"
+            ? record.capabilities
+            : undefined) ??
+            (record.retrieval && typeof record.retrieval === "object"
+                ? record.retrieval
+                : undefined) ??
+            record);
+        const scopedSource = (source.retrieval && typeof source.retrieval === "object"
+            ? source.retrieval
+            : source);
+        const aliases = {
+            score_breakdown: ["score_breakdown", "structured_scoring", "scoring"],
+            rerank: ["rerank", "re_rank"],
+            snippet_provenance: ["snippet_provenance", "stable_provenance", "provenance"],
+            retrieval_explanation: ["retrieval_explanation", "hit_explanations", "explanations", "retrieval_explanations"],
+            batch_search: ["batch_search", "batch_retrieval", "batch", "multi_fetch"],
+        };
+        const result = this.defaultCapabilityMap("unknown");
+        let found = false;
+        for (const key of CAPABILITY_KEYS) {
+            const aliasKeys = aliases[key];
+            const raw = aliasKeys.map((alias) => scopedSource[alias]).find((entry) => entry !== undefined);
+            if (raw === undefined)
+                continue;
+            found = true;
+            result[key] = this.toCapabilityStatus(raw);
+        }
+        return found ? result : undefined;
+    }
+    symbols(pathValue) {
+        return this.callMcp("docdex_symbols", this.buildProjectParams({ path: pathValue }));
+    }
+    ast(pathValue, maxNodes) {
+        return this.callMcp("docdex_ast", this.buildProjectParams({ path: pathValue, max_nodes: maxNodes }));
+    }
+    stats() {
+        return this.callMcp("docdex_stats", this.buildProjectParams({}));
+    }
+    files(limit, offset) {
+        return this.callMcp("docdex_files", this.buildProjectParams({ limit, offset }));
+    }
+    repoInspect() {
+        return this.callMcp("docdex_repo_inspect", this.buildProjectParams({}));
+    }
+    memorySave(text, metadata) {
+        return this.callMcp("docdex_memory_save", this.buildProjectParams({ text, metadata }));
+    }
+    memoryRecall(query, topK) {
+        return this.callMcp("docdex_memory_recall", this.buildProjectParams({ query, top_k: topK }));
+    }
+    tree(options = {}) {
+        return this.callMcp("docdex_tree", this.buildProjectParams({
+            path: options.path,
+            max_depth: options.maxDepth,
+            dirs_only: options.dirsOnly,
+            include_hidden: options.includeHidden,
+            extra_excludes: options.extraExcludes,
+        }));
+    }
+    openFile(pathValue, options = {}) {
+        return this.callMcp("docdex_open", this.buildProjectParams({
+            path: pathValue,
+            start_line: options.startLine,
+            end_line: options.endLine,
+            head: options.head,
+            clamp: options.clamp,
+        }));
+    }
+    getProfile(agentId) {
+        const params = {};
+        if (agentId)
+            params.agent_id = agentId;
+        return this.callMcp("docdex_get_profile", params);
+    }
+    savePreference(agentId, category, content, metadata) {
+        return this.callMcp("docdex_save_preference", {
+            agent_id: agentId,
+            category,
+            content,
+            metadata,
+        });
+    }
+    webResearch(query, options = {}) {
+        return this.callMcp("docdex_web_research", this.buildProjectParams({
+            query,
+            force_web: options.forceWeb ?? true,
+            skip_local_search: options.skipLocalSearch,
+            web_limit: options.webLimit,
+            no_cache: options.noCache,
+        })).catch(() => this.webResearchHttp(query, options));
+    }
+    async webResearchHttp(query, options = {}) {
+        this.assertOperationAllowed("web_research");
+        await this.ensureHealth();
+        await this.ensureRepoInitialized();
+        const params = new URLSearchParams({ q: query });
+        params.set("force_web", String(options.forceWeb ?? true));
+        if (options.skipLocalSearch !== undefined) {
+            params.set("skip_local_search", String(options.skipLocalSearch));
+        }
+        if (options.webLimit !== undefined) {
+            params.set("max_web_results", String(options.webLimit));
+        }
+        if (options.noCache !== undefined) {
+            params.set("no_cache", String(options.noCache));
+        }
+        this.withRepoId(params);
+        const response = await fetch(`${this.resolveBaseUrl()}/search?${params.toString()}`, {
+            headers: this.buildHeaders(this.dagSessionId),
+        });
+        if (!response.ok) {
+            await this.throwResponseError(response, "web research");
+        }
+        return response.json();
+    }
+    rerank(query, candidates, limit) {
+        return this.callMcp("docdex_rerank", this.buildProjectParams({
+            query,
+            candidates,
+            limit,
+        }));
+    }
+    batchSearch(queries, options = {}) {
+        return this.callMcp("docdex_batch_search", this.buildProjectParams({
+            queries,
+            limit: options.limit,
+            include_libs: options.includeLibs,
+        }));
+    }
+    async getCapabilities(forceRefresh = false) {
+        if (this.capabilitySnapshot && !forceRefresh) {
+            return { ...this.capabilitySnapshot, cached: true };
+        }
+        try {
+            const payload = await this.callMcp("docdex_capabilities", this.buildProjectParams({}));
+            const normalizedCapabilities = this.normalizeCapabilityPayload(payload);
+            const capabilities = normalizedCapabilities ?? this.defaultCapabilityMap("unknown");
+            const warnings = normalizedCapabilities ? undefined : ["probe_missing_capability_fields"];
+            const snapshot = {
+                cached: false,
+                source: "mcp_probe",
+                probed_at_ms: Date.now(),
+                capabilities,
+                warnings,
+            };
+            this.capabilitySnapshot = snapshot;
+            return snapshot;
+        }
+        catch (error) {
+            const snapshot = {
+                cached: false,
+                source: "fallback",
+                probed_at_ms: Date.now(),
+                capabilities: this.defaultCapabilityMap("unavailable"),
+                warnings: [
+                    `probe_failed:${error instanceof Error ? error.message : String(error)}`,
+                ],
+            };
+            this.capabilitySnapshot = snapshot;
+            return snapshot;
+        }
+    }
+}