@next-open-ai/openclawx 0.6.6

package/dist/core/mcp/transport/sse.js

@@ -0,0 +1,82 @@
+/**
+ * MCP SSE/HTTP 传输：通过 HTTP POST 向远程 URL 发送 JSON-RPC 请求，响应在 response body。
+ */
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+export class SseTransport {
+    config;
+    initTimeoutMs;
+    requestTimeoutMs;
+    _connected = false;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.initTimeoutMs = options.initTimeoutMs ?? 15_000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+    }
+    async start() {
+        if (this._connected)
+            return;
+        const url = (this.config.url ?? "").trim();
+        if (!url)
+            throw new Error("MCP SSE url is required");
+        const initResult = await this.request({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: { name: "openbot", version: "0.1.0" },
+            },
+        }, this.initTimeoutMs);
+        if (initResult.error) {
+            throw new Error(`MCP initialize failed: ${initResult.error.message}`);
+        }
+        await this.request({ jsonrpc: "2.0", id: 2, method: "notifications/initialized" }, this.requestTimeoutMs).catch(() => ({}));
+        this._connected = true;
+    }
+    request(req, timeoutMs) {
+        const url = (this.config.url ?? "").trim();
+        if (!url) {
+            return Promise.reject(new Error("MCP SSE url is required"));
+        }
+        const t = timeoutMs ?? this.requestTimeoutMs;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), t);
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            ...this.config.headers,
+        };
+        return fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(req),
+            signal: controller.signal,
+        })
+            .then(async (res) => {
+            clearTimeout(timeoutId);
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`MCP HTTP ${res.status}: ${text.slice(0, 200)}`);
+            }
+            const json = (await res.json());
+            if (!json || json.jsonrpc !== "2.0") {
+                throw new Error("Invalid MCP response");
+            }
+            return json;
+        })
+            .catch((err) => {
+            clearTimeout(timeoutId);
+            if (err.name === "AbortError") {
+                throw new Error(`MCP request timeout (${t}ms)`);
+            }
+            throw err;
+        });
+    }
+    async close() {
+        this._connected = false;
+    }
+    get isConnected() {
+        return this._connected;
+    }
+}

package/dist/core/mcp/transport/stdio.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MCP stdio 传输：子进程 + 标准输入/输出上的 Newline-delimited JSON-RPC。
+ */
+import type { McpServerConfigStdio } from "../types.js";
+import type { JsonRpcRequest, JsonRpcResponse } from "../types.js";
+export interface StdioTransportOptions {
+    /** 初始化超时（毫秒） */
+    initTimeoutMs?: number;
+    /** 单次请求超时（毫秒） */
+    requestTimeoutMs?: number;
+}
+export declare class StdioTransport {
+    private process;
+    private config;
+    private initTimeoutMs;
+    private requestTimeoutMs;
+    private nextId;
+    private pending;
+    private buffer;
+    constructor(config: McpServerConfigStdio, options?: StdioTransportOptions);
+    /** 启动子进程并完成 MCP initialize 握手 */
+    start(): Promise<void>;
+    private flushLines;
+    private rejectAll;
+    private initialize;
+    private sendNotification;
+    /** 发送 JSON-RPC 请求并等待响应 */
+    request(req: JsonRpcRequest, timeoutMs?: number): Promise<JsonRpcResponse>;
+    /** 关闭子进程 */
+    close(): Promise<void>;
+    get isConnected(): boolean;
+}

package/dist/core/mcp/transport/stdio.js

@@ -0,0 +1,132 @@
+/**
+ * MCP stdio 传输：子进程 + 标准输入/输出上的 Newline-delimited JSON-RPC。
+ */
+import { spawn } from "node:child_process";
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+export class StdioTransport {
+    process = null;
+    config;
+    initTimeoutMs;
+    requestTimeoutMs;
+    nextId = 1;
+    pending = new Map();
+    buffer = "";
+    constructor(config, options = {}) {
+        this.config = config;
+        this.initTimeoutMs = options.initTimeoutMs ?? 10_000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+    }
+    /** 启动子进程并完成 MCP initialize 握手 */
+    async start() {
+        if (this.process) {
+            return;
+        }
+        const env = { ...process.env, ...this.config.env };
+        this.process = spawn(this.config.command, this.config.args ?? [], {
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const child = this.process;
+        child.stdout?.on("data", (chunk) => {
+            this.buffer += chunk.toString("utf-8");
+            this.flushLines();
+        });
+        child.stderr?.on("data", (data) => {
+            const msg = data.toString("utf-8").trim();
+            if (msg)
+                console.warn("[mcp stdio stderr]", msg);
+        });
+        child.on("error", (err) => {
+            this.rejectAll(new Error(`MCP process error: ${err.message}`));
+        });
+        child.on("exit", (code, signal) => {
+            this.rejectAll(new Error(`MCP process exited: code=${code} signal=${signal}`));
+            this.process = null;
+        });
+        await this.initialize();
+    }
+    flushLines() {
+        const lines = this.buffer.split("\n");
+        this.buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const msg = JSON.parse(trimmed);
+                if ("id" in msg && msg.id !== undefined) {
+                    const pending = this.pending.get(msg.id);
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        this.pending.delete(msg.id);
+                        if (msg.error) {
+                            pending.reject(new Error(msg.error.message));
+                        }
+                        else {
+                            pending.resolve(msg);
+                        }
+                    }
+                }
+            }
+            catch {
+                // 忽略非 JSON 行
+            }
+        }
+    }
+    rejectAll(err) {
+        for (const [, { reject, timer }] of this.pending) {
+            clearTimeout(timer);
+            reject(err);
+        }
+        this.pending.clear();
+    }
+    async initialize() {
+        const initResult = await this.request({
+            jsonrpc: "2.0",
+            id: this.nextId++,
+            method: "initialize",
+            params: {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: { name: "openbot", version: "0.1.0" },
+            },
+        }, this.initTimeoutMs);
+        if (initResult.error) {
+            throw new Error(`MCP initialize failed: ${initResult.error.message}`);
+        }
+        this.sendNotification({ jsonrpc: "2.0", method: "notifications/initialized" });
+    }
+    sendNotification(msg) {
+        if (!this.process?.stdin?.writable)
+            return;
+        this.process.stdin.write(JSON.stringify(msg) + "\n", "utf-8");
+    }
+    /** 发送 JSON-RPC 请求并等待响应 */
+    request(req, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            if (!this.process?.stdin?.writable) {
+                reject(new Error("MCP transport not connected"));
+                return;
+            }
+            const t = timeoutMs ?? this.requestTimeoutMs;
+            const timer = setTimeout(() => {
+                if (this.pending.delete(req.id)) {
+                    reject(new Error(`MCP request timeout (${t}ms)`));
+                }
+            }, t);
+            this.pending.set(req.id, { resolve, reject, timer });
+            this.process.stdin.write(JSON.stringify(req) + "\n", "utf-8");
+        });
+    }
+    /** 关闭子进程 */
+    async close() {
+        if (this.process) {
+            this.rejectAll(new Error("MCP transport closed"));
+            this.process.kill("SIGTERM");
+            this.process = null;
+        }
+    }
+    get isConnected() {
+        return this.process != null && this.process.stdin?.writable === true;
+    }
+}

package/dist/core/mcp/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * MCP (Model Context Protocol) 相关类型定义。
+ * 仅实现 Client 端 Tools 能力；Resources/Prompts 类型预留扩展。
+ */
+/** stdio 传输：通过子进程 stdin/stdout 进行 JSON-RPC 通信 */
+export interface McpServerConfigStdio {
+    transport: "stdio";
+    /** 可执行路径（禁止从用户输入拼接，需白名单或配置） */
+    command: string;
+    /** 命令行参数 */
+    args?: string[];
+    /** 环境变量（可选，合并到 process.env） */
+    env?: Record<string, string>;
+}
+/** SSE/HTTP 远程传输：通过 URL POST JSON-RPC 请求 */
+export interface McpServerConfigSse {
+    transport: "sse";
+    /** 远程 MCP 服务地址（如 https://example.com/mcp） */
+    url: string;
+    /** 可选请求头（如 Authorization） */
+    headers?: Record<string, string>;
+}
+/** 单条 MCP 服务器配置（由调用方在创建 Session 时传入，与 Skill 类似） */
+export type McpServerConfig = McpServerConfigStdio | McpServerConfigSse;
+/** MCP 协议中 Tool 的 inputSchema 为 JSON Schema 对象 */
+export interface McpToolInputSchema {
+    type?: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+}
+/** MCP tools/list 返回的单个工具描述 */
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: McpToolInputSchema;
+}
+/** MCP tools/call 返回的 content 项 */
+export interface McpToolCallContentItem {
+    type: "text";
+    text: string;
+}
+/** MCP tools/call 的 result */
+export interface McpToolCallResult {
+    content: McpToolCallContentItem[];
+    isError?: boolean;
+}
+/** JSON-RPC 2.0 请求 */
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: number | string;
+    method: string;
+    params?: unknown;
+}
+/** JSON-RPC 2.0 成功响应 */
+export interface JsonRpcResponse<T = unknown> {
+    jsonrpc: "2.0";
+    id: number | string;
+    result?: T;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** 传输层抽象：stdio / sse 等实现此接口供 McpClient 使用 */
+export interface IMcpTransport {
+    start(): Promise<void>;
+    request(req: JsonRpcRequest, timeoutMs?: number): Promise<JsonRpcResponse>;
+    close(): Promise<void>;
+    readonly isConnected: boolean;
+}

package/dist/core/mcp/types.js

@@ -0,0 +1,5 @@
+/**
+ * MCP (Model Context Protocol) 相关类型定义。
+ * 仅实现 Client 端 Tools 能力；Resources/Prompts 类型预留扩展。
+ */
+export {};

package/dist/core/memory/build-summary.d.ts

@@ -0,0 +1,6 @@
+import { type SessionEntry } from "@mariozechner/pi-coding-agent";
+/**
+ * 从 session entries 中提取可用于存入向量库的摘要文本：
+ * 优先使用最新 compaction 的 summary，否则用最近若干条消息拼成短文。
+ */
+export declare function buildSessionSummaryFromEntries(entries: SessionEntry[]): string | null;

package/dist/core/memory/build-summary.js

@@ -0,0 +1,27 @@
+import { getLatestCompactionEntry, } from "@mariozechner/pi-coding-agent";
+import { convertToLlm } from "@mariozechner/pi-coding-agent";
+/**
+ * 从 session entries 中提取可用于存入向量库的摘要文本：
+ * 优先使用最新 compaction 的 summary，否则用最近若干条消息拼成短文。
+ */
+export function buildSessionSummaryFromEntries(entries) {
+    const compaction = getLatestCompactionEntry(entries);
+    if (compaction?.summary) {
+        return compaction.summary;
+    }
+    const messageEntries = entries.filter((e) => e.type === "message");
+    if (messageEntries.length === 0)
+        return null;
+    const recent = messageEntries.slice(-20);
+    const messages = recent.map((e) => e.message);
+    const parts = [];
+    for (const msg of convertToLlm(messages)) {
+        const role = msg.role === "user" ? "User" : "Assistant";
+        const content = typeof msg.content === "string"
+            ? msg.content
+            : msg.content?.map((c) => c.text ?? "").join(" ") ?? "";
+        if (content.trim())
+            parts.push(`${role}: ${content.trim()}`);
+    }
+    return parts.length > 0 ? parts.join("\n") : null;
+}

package/dist/core/memory/compaction-extension.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
+/**
+ * 创建用于在 session_compact 事件时把 compaction summary 写入向量库的 extension factory。
+ * 在 AgentSession 发生 compaction（自动或手动）后触发，无需等到关闭会话。
+ */
+export declare function createCompactionMemoryExtensionFactory(sessionId: string): ExtensionFactory;

package/dist/core/memory/compaction-extension.js

@@ -0,0 +1,23 @@
+import { addMemory } from "./index.js";
+/**
+ * 创建用于在 session_compact 事件时把 compaction summary 写入向量库的 extension factory。
+ * 在 AgentSession 发生 compaction（自动或手动）后触发，无需等到关闭会话。
+ */
+export function createCompactionMemoryExtensionFactory(sessionId) {
+    return (pi) => {
+        pi.on("session_compact", async (event) => {
+            const summary = event.compactionEntry?.summary?.trim();
+            if (!summary)
+                return;
+            try {
+                await addMemory(summary, {
+                    infotype: "compaction",
+                    sessionId,
+                });
+            }
+            catch (_) {
+                // 写入失败不打断会话
+            }
+        });
+    };
+}

package/dist/core/memory/embedding.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 对单条文本做 embedding。未配置 RAG embedding 时返回 null。
+ */
+export declare function embed(text: string): Promise<number[] | null>;

package/dist/core/memory/embedding.js

@@ -0,0 +1,15 @@
+/**
+ * 文本 embedding：使用 config.json 中配置的远端 RAG embedding 模型。
+ * 未配置时返回 null，调用方（长记忆）空转。
+ */
+import { getRagEmbeddingConfigSync } from "../config/desktop-config.js";
+import { embedRemote } from "./remote-embedding.js";
+/**
+ * 对单条文本做 embedding。未配置 RAG embedding 时返回 null。
+ */
+export async function embed(text) {
+    const config = getRagEmbeddingConfigSync();
+    if (!config)
+        return null;
+    return embedRemote(text, config);
+}

package/dist/core/memory/index.d.ts

@@ -0,0 +1,29 @@
+import type { InfoType, MemorySearchResult } from "./types.js";
+export { buildSessionSummaryFromEntries } from "./build-summary.js";
+export type { InfoType, MemoryMetadata, MemorySearchResult } from "./types.js";
+export declare function initMemory(): Promise<void>;
+/**
+ * 将一条文本写入向量库。未配置 RAG embedding 时跳过写入并返回占位 id（长记忆空转）。
+ * @param text 内容
+ * @param metadata.infotype 经验总结(experience) 或 compaction 摘要(compaction)
+ * @param metadata.sessionId 会话 id
+ */
+export declare function addMemory(text: string, metadata: {
+    infotype: InfoType;
+    sessionId: string;
+}): Promise<string>;
+export interface SearchMemoryOptions {
+    topK?: number;
+    infotype?: import("./types.js").InfoType;
+    sessionId?: string;
+}
+/**
+ * 按语义搜索记忆，可按 infotype、sessionId 过滤。未配置 RAG embedding 时返回空数组（空转）。
+ */
+export declare function searchMemory(query: string, topK?: number, options?: SearchMemoryOptions): Promise<MemorySearchResult[]>;
+/** 拉取 3 条经验，格式化为「经验内容」文本（用于拼入用户消息） */
+export declare function getExperienceContextForUserMessage(): Promise<string>;
+/**
+ * 拉取 1 条 compaction 摘要，用于拼入 system prompt（新建 AgentSession 时调用，可选 sessionId）
+ */
+export declare function getCompactionContextForSystemPrompt(sessionId?: string): Promise<string>;

package/dist/core/memory/index.js

@@ -0,0 +1,70 @@
+import { randomUUID } from "node:crypto";
+import { embed } from "./embedding.js";
+import { addToStore, queryStore } from "./vector-store.js";
+export { buildSessionSummaryFromEntries } from "./build-summary.js";
+let initialized = false;
+export async function initMemory() {
+    if (initialized)
+        return;
+    const { getChroma } = await import("./vector-store.js");
+    await getChroma();
+    initialized = true;
+}
+/**
+ * 将一条文本写入向量库。未配置 RAG embedding 时跳过写入并返回占位 id（长记忆空转）。
+ * @param text 内容
+ * @param metadata.infotype 经验总结(experience) 或 compaction 摘要(compaction)
+ * @param metadata.sessionId 会话 id
+ */
+export async function addMemory(text, metadata) {
+    const id = randomUUID();
+    const vec = await embed(text);
+    if (vec === null)
+        return id;
+    const meta = {
+        ...metadata,
+        createdAt: new Date().toISOString(),
+    };
+    await addToStore(id, vec, text, meta);
+    return id;
+}
+/**
+ * 按语义搜索记忆，可按 infotype、sessionId 过滤。未配置 RAG embedding 时返回空数组（空转）。
+ */
+export async function searchMemory(query, topK = 10, options) {
+    const vec = await embed(query);
+    if (vec === null)
+        return [];
+    const opts = typeof options === "object" && options != null ? options : {};
+    const k = opts.topK ?? topK;
+    const filter = opts.infotype != null || opts.sessionId != null
+        ? { infotype: opts.infotype, sessionId: opts.sessionId }
+        : undefined;
+    const rows = await queryStore(vec, k, filter);
+    return rows.map((r) => ({
+        document: r.document,
+        metadata: r.metadata,
+        distance: r.distance,
+    }));
+}
+/** 拉取 3 条经验，格式化为「经验内容」文本（用于拼入用户消息） */
+export async function getExperienceContextForUserMessage() {
+    const results = await searchMemory("经验 总结 技巧 方法", 3, { infotype: "experience" });
+    if (results.length === 0)
+        return "";
+    const lines = results.map((r, i) => `${i + 1}. ${(r.document || "").trim()}`).filter(Boolean);
+    if (lines.length === 0)
+        return "";
+    return "以下为相关经验：\n\n" + lines.join("\n\n");
+}
+/**
+ * 拉取 1 条 compaction 摘要，用于拼入 system prompt（新建 AgentSession 时调用，可选 sessionId）
+ */
+export async function getCompactionContextForSystemPrompt(sessionId) {
+    const filter = sessionId != null ? { infotype: "compaction", sessionId } : { infotype: "compaction" };
+    const results = await searchMemory("对话 摘要 历史 上下文", 1, { ...filter, topK: 1 });
+    const doc = results[0]?.document?.trim();
+    if (!doc)
+        return "";
+    return "## 历史对话摘要\n\n" + doc;
+}

package/dist/core/memory/remote-embedding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 远端 embedding：调用 OpenAI 兼容的 /embeddings 接口。
+ * 配置来自 ~/.openbot/desktop/config.json 的 rag.embeddingProvider + rag.embeddingModel；
+ * 未配置时由调用方（embedding.ts）返回 null，长记忆空转。
+ */
+import type { RagEmbeddingConfig } from "../config/desktop-config.js";
+/**
+ * 单条文本请求远端 embedding，返回归一化向量；失败抛错。
+ */
+export declare function embedRemote(text: string, config: RagEmbeddingConfig): Promise<number[]>;

package/dist/core/memory/remote-embedding.js

@@ -0,0 +1,36 @@
+const EMBEDDINGS_PATH = "/embeddings";
+/**
+ * 单条文本请求远端 embedding，返回归一化向量；失败抛错。
+ */
+export async function embedRemote(text, config) {
+    const base = config.baseUrl.replace(/\/$/, "");
+    const url = base + (base.endsWith("/v1") ? EMBEDDINGS_PATH : "/v1" + EMBEDDINGS_PATH);
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.apiKey}`,
+        },
+        body: JSON.stringify({
+            model: config.modelId,
+            input: text,
+        }),
+    });
+    if (!res.ok) {
+        const errText = await res.text();
+        throw new Error(`Embedding API error ${res.status}: ${errText}`);
+    }
+    const data = (await res.json());
+    const embedding = data?.data?.[0]?.embedding;
+    if (!Array.isArray(embedding) || embedding.length === 0) {
+        throw new Error("Embedding API returned empty embedding");
+    }
+    return L2Normalize(embedding.map(Number));
+}
+function L2Normalize(vec) {
+    let sum = 0;
+    for (let i = 0; i < vec.length; i++)
+        sum += vec[i] * vec[i];
+    const norm = Math.sqrt(sum) || 1;
+    return vec.map((x) => x / norm);
+}

package/dist/core/memory/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 长记忆 metadata 中的信息类型
+ * - experience: 对话结束时 Agent 调用 save_experience 工具存入的经验总结
+ * - compaction: 关闭 session 时从 compaction 取出的会话摘要
+ */
+export type InfoType = "experience" | "compaction";
+export interface MemoryMetadata {
+    infotype: InfoType;
+    sessionId: string;
+    createdAt: string;
+}
+export interface MemorySearchResult {
+    document: string;
+    metadata: MemoryMetadata;
+    distance?: number;
+}

package/dist/core/memory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/memory/vector-store.d.ts

@@ -0,0 +1,15 @@
+import type { InfoType, MemoryMetadata } from "./types.js";
+export declare function getChroma(): Promise<{
+    client: null;
+    collection: null;
+}>;
+export declare function addToStore(id: string, embedding: number[], document: string, metadata: MemoryMetadata): Promise<void>;
+export type MemoryFilter = {
+    infotype?: InfoType;
+    sessionId?: string;
+};
+export declare function queryStore(queryEmbedding: number[], topK?: number, filter?: MemoryFilter): Promise<{
+    document: string;
+    metadata: MemoryMetadata;
+    distance?: number;
+}[]>;

package/dist/core/memory/vector-store.js

@@ -0,0 +1,65 @@
+import { join } from "node:path";
+import { LocalIndex } from "vectra";
+import { getOpenbotAgentDir } from "../agent/agent-dir.js";
+const INDEX_DIR_NAME = "memory";
+let indexDir = null;
+let index = null;
+function getIndexDir() {
+    if (!indexDir) {
+        indexDir = join(getOpenbotAgentDir(), INDEX_DIR_NAME);
+    }
+    return indexDir;
+}
+async function getIndex() {
+    if (index)
+        return index;
+    const path = getIndexDir();
+    index = new LocalIndex(path);
+    if (!(await index.isIndexCreated())) {
+        await index.createIndex();
+    }
+    return index;
+}
+/** Vectra 返回 score（相似度 0~1，越大越相似）；转为 distance = 1 - score，与现有 API 一致 */
+function scoreToDistance(score) {
+    return 1 - score;
+}
+export async function getChroma() {
+    await getIndex();
+    return { client: null, collection: null };
+}
+export async function addToStore(id, embedding, document, metadata) {
+    const idx = await getIndex();
+    await idx.upsertItem({
+        id,
+        vector: embedding,
+        metadata: {
+            document,
+            infotype: metadata.infotype,
+            sessionId: metadata.sessionId,
+            createdAt: metadata.createdAt,
+        },
+    });
+}
+export async function queryStore(queryEmbedding, topK = 10, filter) {
+    const idx = await getIndex();
+    const vectraFilter = filter && (filter.infotype != null || filter.sessionId != null)
+        ? {
+            ...(filter.infotype != null && { infotype: { $eq: filter.infotype } }),
+            ...(filter.sessionId != null && { sessionId: { $eq: filter.sessionId } }),
+        }
+        : undefined;
+    const results = await idx.queryItems(queryEmbedding, "", topK, vectraFilter);
+    return results.map((r) => {
+        const meta = (r.item.metadata ?? {});
+        return {
+            document: String(meta.document ?? ""),
+            metadata: {
+                infotype: meta.infotype,
+                sessionId: String(meta.sessionId ?? ""),
+                createdAt: String(meta.createdAt ?? ""),
+            },
+            distance: scoreToDistance(r.score),
+        };
+    });
+}