@zvec/zvec-grep 0.1.5 → 0.1.7

package/dist/cli/commands.js

@@ -1,29 +1,24 @@
-import { randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, open, readFile, readlink, rename, stat, unlink, } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { createZvecGrep, } from "../index.js";
-import { globalConfigPath, updateGlobalConfigFromExplicitOptions, } from "../engine/config.js";
-import { findNearestAnonymousWorkspace } from "../engine/service/root.js";
-import { contextWarningLines, printAgentContextResult, printHumanContextResult, } from "./format/context.js";
+import { globalConfigPath, updateGlobalConfig } from "../engine/config.js";
+import { listEmbeddingModels } from "../engine/models/index.js";
+import { DaemonClient } from "../client/daemon-client.js";
+import { resolveDirectSearchPolicy, resolveServerSearchPolicy, } from "../client/search-policy.js";
+import { resolveClientMode, resolveServerUrl, routeByMode, } from "../client/mode-router.js";
+import { serverStatus } from "../daemon/server-controller.js";
+import { findNearestWorkspace } from "../engine/service/root.js";
+import { contextWarningLines, printCliContextResult, } from "./format/context.js";
 import { printDebug } from "./format/debug.js";
 import { createIndexProgressReporter } from "./format/progress.js";
-import { printAnonymousInfo, printCollectionInfo, printCollectionList, printCollectionRemoveResult, printIndexPathFilterTip, printIndexResult, } from "./format/status.js";
-const AGENT_INSTALLERS = [
-    {
-        id: "codex",
-        label: "Codex",
-        description: "configure zvec-grep MCP and Codex guidance",
-        install: installCodexIntegration,
-        uninstall: uninstallCodexIntegration,
-    },
-];
-const ZVEC_GREP_CONFIG_START = "# ZVEC_GREP_START";
-const ZVEC_GREP_CONFIG_END = "# ZVEC_GREP_END";
-const ZVEC_GREP_AGENTS_START = "<!-- ZVEC_GREP_START -->";
-const ZVEC_GREP_AGENTS_END = "<!-- ZVEC_GREP_END -->";
-const DEFAULT_MCP_TOOL_TIMEOUT_SECONDS = 600;
+import { printWorkspaceInfo, printIndexPathFilterTip, printIndexResult, printIndexScanDiagnostics, printNoIndexableFilesTip, printServerIndexInfo, } from "./format/status.js";
+import { planRemoteIndexAuthorization, planRemoteSearchAuthorization, } from "../authorization/index.js";
+import { indexCompletionFromStatus, indexStatusNeedsRefresh, } from "../engine/index-status.js";
+import { indexProgressFromMessage } from "../index-progress.js";
+import { normalizeManagedRgInput } from "./managed-rg.js";
+import { INCOMPATIBLE_SERVER_SEARCH_MESSAGE, parseServerSearchResponse, } from "./server-search.js";
+import { runInstall, runUninstall } from "./install.js";
+import { runAuth, authorizationStore, authorizeCliPlan, resolveAuthorizationSchema, embeddingModelInfo, configuredEmbeddingReference, workspaceRuntimeFromInfo, assertEmbeddingModelCompatible, assertRequestedEndpointCompatible, requireEmbeddingModelCatalogEntry, unsupportedRemoteEmbeddingProvider, withRemoteEmbeddingOperationPermit, } from "./auth.js";
 export async function runParsedCommand(parsed) {
     switch (parsed.command) {
         case "query":
@@ -35,174 +30,107 @@ export async function runParsedCommand(parsed) {
         case "status":
             await runStatus(parsed);
             return;
-        case "collections":
-            await runCollections(parsed);
-            return;
         case "install":
             await runInstall(parsed);
             return;
         case "uninstall":
             await runUninstall(parsed);
             return;
-        case "serve":
-            await runServe(parsed);
+        case "config":
+            await runConfig(parsed);
+            return;
+        case "auth":
+            await runAuth(parsed);
+            return;
+        case "server":
+            await runServer(parsed);
             return;
         case "help":
         case "version":
             throw new Error(`${parsed.command} must be handled before dispatch`);
     }
 }
-async function runInstall(parsed) {
-    const installers = await resolveInstallers(parsed, "install");
-    if (installers.length === 0) {
-        console.log("No agents selected.");
-        return;
+async function runConfig(parsed) {
+    if (parsed.positionals.length !== 1) {
+        throw new Error(`zg config ${parsed.options.configAction === "provider-set" ? "provider" : "model"} set requires exactly one reference`);
     }
-    console.log(`Installing zvec-grep for: ${installers.map((installer) => installer.label).join(", ")}`);
-    for (const installer of installers) {
-        const result = await installer.install({
-            force: parsed.options.force === true,
-            mcpToolTimeoutSeconds: parsed.options.installMcpToolTimeoutSeconds ??
-                DEFAULT_MCP_TOOL_TIMEOUT_SECONDS,
-        });
-        console.log(`Installed ${installer.label}:`);
-        for (const file of result.files) {
-            console.log(`  ${file}`);
+    const reference = parsed.positionals[0];
+    if (parsed.options.configAction === "provider-set") {
+        if (!/^[a-z][a-z0-9_-]*$/.test(reference)) {
+            throw unsupportedRemoteEmbeddingProvider(reference, "Invalid embedding provider");
         }
-    }
-    console.log("Restart the selected agent or start a new session to pick up the integration.");
-    if (installers.some((installer) => installer.id === "codex")) {
-        console.log("Codex MCP server: zg serve --mcp");
-    }
-}
-async function runUninstall(parsed) {
-    const installers = await resolveInstallers(parsed, "uninstall");
-    if (installers.length === 0) {
-        console.log("No agents selected.");
-        return;
-    }
-    console.log(`Removing zvec-grep from: ${installers.map((installer) => installer.label).join(", ")}`);
-    for (const installer of installers) {
-        const result = await installer.uninstall();
-        console.log(`Removed ${installer.label} integration:`);
-        for (const file of result.files) {
-            console.log(`  ${file}`);
+        if (reference === "local" ||
+            !listEmbeddingModels().some((entry) => entry.provider === reference)) {
+            throw unsupportedRemoteEmbeddingProvider(reference);
+        }
+        if (parsed.options.apiKey === undefined) {
+            throw new Error("zg config provider set requires --api-key");
         }
+        updateGlobalConfig({
+            providers: {
+                [reference]: {
+                    apiKey: parsed.options.apiKey,
+                },
+            },
+        });
+        console.log(`Provider config: ${reference}`);
+        console.log(`Global config: ${globalConfigPath()}`);
+        return;
     }
-    console.log("Restart the selected agent or start a new session to apply the change.");
-}
-async function installCodexIntegration(options) {
-    const codexHome = resolveCodexHome();
-    const configPath = resolve(codexHome, "config.toml");
-    const agentsPath = resolve(codexHome, "AGENTS.md");
-    await writeMarkedFile({
-        path: configPath,
-        startMarker: ZVEC_GREP_CONFIG_START,
-        endMarker: ZVEC_GREP_CONFIG_END,
-        block: codexConfigBlock(options.mcpToolTimeoutSeconds),
-        force: options.force,
-        hasConflict: hasCodexMcpServerConfig,
-        conflictMessage: `Existing [mcp_servers.zvec_grep] found in ${configPath}. Re-run with --force after removing or moving that table into the zvec-grep managed block.`,
-        removeConflict: removeCodexMcpServerConfig,
-    });
-    await writeMarkedFile({
-        path: agentsPath,
-        startMarker: ZVEC_GREP_AGENTS_START,
-        endMarker: ZVEC_GREP_AGENTS_END,
-        block: codexAgentsBlock(),
-        force: true,
-    });
-    return { files: [configPath, agentsPath] };
-}
-async function uninstallCodexIntegration() {
-    const codexHome = resolveCodexHome();
-    const configPath = resolve(codexHome, "config.toml");
-    const agentsPath = resolve(codexHome, "AGENTS.md");
-    await removeMarkedFile({
-        path: configPath,
-        startMarker: ZVEC_GREP_CONFIG_START,
-        endMarker: ZVEC_GREP_CONFIG_END,
-    });
-    await removeMarkedFile({
-        path: agentsPath,
-        startMarker: ZVEC_GREP_AGENTS_START,
-        endMarker: ZVEC_GREP_AGENTS_END,
+    if (parsed.options.configAction !== "model-set") {
+        throw new Error("zg config requires provider set or model set");
+    }
+    const catalogEntry = requireEmbeddingModelCatalogEntry(reference);
+    if (parsed.options.endpoint === undefined &&
+        parsed.options.device === undefined &&
+        !parsed.options.defaultModel) {
+        throw new Error("zg config model set requires --endpoint, --device, or --default");
+    }
+    if (catalogEntry.provider === "local" &&
+        parsed.options.endpoint !== undefined) {
+        throw new Error("--endpoint is only supported for remote embedding models");
+    }
+    if (catalogEntry.provider !== "local" &&
+        parsed.options.device !== undefined) {
+        throw new Error("--device is only supported for local embedding models");
+    }
+    if (parsed.options.endpoint !== undefined) {
+        assertHttpEndpoint(parsed.options.endpoint);
+    }
+    updateGlobalConfig({
+        ...(parsed.options.endpoint !== undefined ||
+            parsed.options.device !== undefined
+            ? {
+                models: {
+                    [reference]: {
+                        ...(parsed.options.endpoint !== undefined
+                            ? { endpoint: parsed.options.endpoint }
+                            : {}),
+                        ...(parsed.options.device !== undefined
+                            ? { device: parsed.options.device }
+                            : {}),
+                    },
+                },
+            }
+            : {}),
+        ...(parsed.options.defaultModel
+            ? { defaults: { embedding: reference } }
+            : {}),
     });
-    return { files: [configPath, agentsPath] };
-}
-async function resolveInstallers(parsed, action) {
-    const targetTokens = [
-        ...(parsed.options.installTargets ?? []),
-        ...parsed.positionals,
-    ];
-    if (targetTokens.length > 0) {
-        return installersFromTokens(targetTokens);
-    }
-    if (parsed.options.yes === true ||
-        !process.stdin.isTTY ||
-        !process.stdout.isTTY) {
-        return installersFromTokens(["auto"]);
-    }
-    return promptInstallers(action);
+    console.log(`Model config: ${reference}`);
+    console.log(`Global config: ${globalConfigPath()}`);
 }
-async function promptInstallers(action) {
-    console.log(`Select agents whose zvec-grep integration should be ${action === "install" ? "installed" : "removed"}:`);
-    AGENT_INSTALLERS.forEach((installer, index) => {
-        console.log(`  ${index + 1}. ${installer.label} - ${installer.description}`);
-    });
-    console.log("  all. All supported agents");
-    console.log("  none. Cancel");
-    const readline = createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
+function assertHttpEndpoint(endpoint) {
+    let parsed;
     try {
-        const answer = await readline.question("Agents [codex]: ");
-        const normalized = answer.trim();
-        return installersFromTokens(normalized.length > 0 ? splitTargetTokens(normalized) : ["codex"]);
+        parsed = new URL(endpoint);
     }
-    finally {
-        readline.close();
+    catch {
+        throw new Error("--endpoint must be a valid HTTP(S) URL");
     }
-}
-function installersFromTokens(tokens) {
-    const normalized = tokens.flatMap(splitTargetTokens);
-    if (normalized.length === 0) {
-        return installersFromTokens(["auto"]);
-    }
-    const selected = new Map();
-    for (const token of normalized) {
-        const lower = token.toLowerCase();
-        if (lower === "none") {
-            return [];
-        }
-        if (lower === "auto" || lower === "all") {
-            for (const installer of AGENT_INSTALLERS) {
-                selected.set(installer.id, installer);
-            }
-            continue;
-        }
-        const numbered = /^\d+$/.test(lower) ? Number(lower) : Number.NaN;
-        if (Number.isInteger(numbered) &&
-            numbered >= 1 &&
-            numbered <= AGENT_INSTALLERS.length) {
-            const installer = AGENT_INSTALLERS[numbered - 1];
-            selected.set(installer.id, installer);
-            continue;
-        }
-        const installer = AGENT_INSTALLERS.find((candidate) => candidate.id === lower || candidate.label.toLowerCase() === lower);
-        if (!installer) {
-            throw new Error(`Unknown install target: ${token}`);
-        }
-        selected.set(installer.id, installer);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("--endpoint must be a valid HTTP(S) URL");
     }
-    return [...selected.values()];
-}
-function splitTargetTokens(value) {
-    return value
-        .split(/[,\s]+/)
-        .map((target) => target.trim())
-        .filter((target) => target.length > 0);
 }
 async function runIndex(parsed) {
     const explicitRoot = parsed.positionals.length > 0;
@@ -215,11 +143,125 @@ async function runIndex(parsed) {
         await runDropIndex(parsed, rootPath.absolutePath);
         return;
     }
-    const zvecGrep = await createZvecGrep(createServiceOptions(parsed.options, rootPath.absolutePath));
-    const progress = createIndexProgressReporter();
+    if (parsed.options.embedding) {
+        requireEmbeddingModelCatalogEntry(parsed.options.embedding);
+    }
+    const mode = resolveClientMode(parsed.options.mode);
+    await routeByMode({
+        mode,
+        serverAvailable: () => daemonIsReady(parsed.options.home),
+        server: async () => {
+            const client = daemonClient(parsed.options);
+            const progress = createIndexProgressReporter({
+                color: parsed.options.color,
+            });
+            let result;
+            try {
+                result = await client.callTool("zvec_grep_index", {
+                    root: rootPath.absolutePath,
+                    embedding: parsed.options.embedding,
+                    apiKey: parsed.options.apiKey,
+                    endpoint: parsed.options.endpoint,
+                    device: parsed.options.device,
+                    rebuild: parsed.options.rebuild,
+                    resetPaths: parsed.options.resetPaths,
+                    globs: parsed.options.globs,
+                    insensitiveGlobs: parsed.options.insensitiveGlobs,
+                    fileTypes: parsed.options.fileTypes,
+                    excludedFileTypes: parsed.options.excludedFileTypes,
+                    hidden: parsed.options.hidden,
+                    noIgnore: parsed.options.noIgnore,
+                    ignoreFiles: parsed.options.ignoreFiles,
+                    maxDepth: parsed.options.maxDepth,
+                    maxFileSizeBytes: parsed.options.maxFileSizeBytes,
+                    follow: parsed.options.follow,
+                    embeddingConcurrency: parsed.options.embeddingConcurrency,
+                    debug: parsed.options.debug,
+                    wait: true,
+                }, {
+                    onProgress: (event) => {
+                        const update = indexProgressFromMessage(event.message);
+                        if (update) {
+                            progress.report(update.progress);
+                        }
+                    },
+                    embeddingEnvironment: process.env.ZVEC_GREP_EMBEDDING?.trim(),
+                });
+            }
+            finally {
+                progress.finish();
+            }
+            console.log(`Workspace index: ${String(result.state ?? "submitted")}`);
+            console.log(`Root: ${String(result.root ?? rootPath.absolutePath)}`);
+            console.log(`Job: ${String(result.job_id ?? "unknown")}`);
+            if (parsed.options.debug) {
+                printIndexScanDiagnostics(result.scan_diagnostics);
+            }
+            if (result.state === "failed") {
+                throw new Error(serverIndexFailureMessage(result));
+            }
+            if (result.state === "succeeded") {
+                const status = (await client
+                    .callTool("zvec_grep_index_status", {
+                    root: rootPath.absolutePath,
+                })
+                    .catch(() => undefined));
+                if (status?.persistent.files?.scanned === 0) {
+                    printNoIndexableFilesTip(parsed.options);
+                }
+            }
+        },
+        direct: () => runDirectIndex(parsed, rootPath, explicitRoot),
+    });
+}
+function serverIndexFailureMessage(result) {
+    const error = result.error;
+    if (error && typeof error === "object") {
+        const code = error.code;
+        const message = error.message;
+        if (typeof message === "string" && message.length > 0) {
+            if (typeof code !== "string" ||
+                code.length === 0 ||
+                message.includes(`[${code}]`)) {
+                return message;
+            }
+            return `[${code}] ${message}`;
+        }
+        if (typeof code === "string" && code.length > 0) {
+            return `[${code}] Index job failed.`;
+        }
+    }
+    return `Index job ${String(result.job_id ?? "unknown")} failed. Run zg status --mode server for details.`;
+}
+async function runDirectIndex(parsed, rootPath, explicitRoot) {
+    const serviceOptions = createServiceOptions(parsed.options, rootPath.absolutePath);
+    const zvecGrep = await createZvecGrep(serviceOptions);
+    const progress = createIndexProgressReporter({ color: parsed.options.color });
     try {
+        const infoBefore = await zvecGrep.info({
+            root: rootPath.absolutePath,
+            includeStatus: parsed.options.rebuild !== true,
+        });
+        const schema = resolveAuthorizationSchema(configuredEmbeddingReference(parsed.options, infoBefore.workspaceIndex?.embedding), infoBefore.workspaceIndex?.embedding);
+        assertEmbeddingModelCompatible(infoBefore.workspaceIndex?.embedding, schema, parsed.options.rebuild === true);
+        const workspaceRuntime = workspaceRuntimeFromInfo(infoBefore);
+        assertRequestedEndpointCompatible(infoBefore, workspaceRuntime, parsed.options.endpoint, parsed.options.rebuild === true);
+        const modelInfo = schema?.provider === "qwen"
+            ? await embeddingModelInfo(schema, serviceOptions, workspaceRuntime)
+            : undefined;
+        const plan = modelInfo
+            ? await planRemoteIndexAuthorization({
+                info: infoBefore,
+                model: modelInfo,
+                rebuild: parsed.options.rebuild,
+                store: authorizationStore(parsed.options),
+            })
+            : undefined;
+        const authorizationResolution = plan
+            ? await authorizeCliPlan(plan, parsed.options)
+            : {};
         printIndexPathFilterTip(parsed.options);
-        const result = await zvecGrep.index({
+        const result = await withRemoteEmbeddingOperationPermit(authorizationResolution.authorization, () => zvecGrep.index({
             root: rootPath.absolutePath,
             rootPaths: explicitRoot ? [rootPath] : undefined,
             rebuild: parsed.options.rebuild,
@@ -236,11 +278,10 @@ async function runIndex(parsed) {
             follow: parsed.options.follow,
             embeddingConcurrency: parsed.options.embeddingConcurrency,
             onProgress: progress.report,
-        });
+        }));
         progress.finish();
         const info = await zvecGrep.info({ root: rootPath.absolutePath });
-        printIndexResult("Indexed anonymous workspace", result, parsed.options, info.collection?.rootPaths);
-        persistExplicitGlobalConfig(parsed.options, info.collection?.embedding?.provider);
+        printIndexResult("Workspace index", result, parsed.options, info.workspaceIndex?.rootPaths);
     }
     catch (error) {
         progress.finish();
@@ -255,14 +296,26 @@ async function runDropIndex(parsed, root) {
         console.log("Index drop cancelled.");
         return;
     }
-    const zvecGrep = await createZvecGrep(createServiceOptions(parsed.options, root));
-    try {
-        const removed = await zvecGrep.dropIndex({ root });
+    const printResult = (removed) => {
         console.log(removed ? `Dropped index for ${root}` : `No index found for ${root}`);
-    }
-    finally {
-        await zvecGrep.close();
-    }
+    };
+    await routeByMode({
+        mode: resolveClientMode(parsed.options.mode),
+        serverAvailable: () => daemonIsReady(parsed.options.home),
+        server: async () => {
+            const result = await daemonClient(parsed.options).callTool("zvec_grep_index_drop", { root });
+            printResult(result.removed === true);
+        },
+        direct: async () => {
+            const zvecGrep = await createZvecGrep(createServiceOptions(parsed.options, root));
+            try {
+                printResult(await zvecGrep.dropIndex({ root }));
+            }
+            finally {
+                await zvecGrep.close();
+            }
+        },
+    });
 }
 async function confirmIndexDrop(root, accepted) {
     if (accepted) {
@@ -283,163 +336,89 @@ async function confirmIndexDrop(root, accepted) {
         readline.close();
     }
 }
-async function runServe(parsed) {
+async function runServer(parsed) {
     if (parsed.positionals.length > 0) {
-        throw new Error("zg serve --mcp does not accept positional arguments");
+        throw new Error(`zg server ${parsed.options.serverStdio ? "--stdio" : parsed.options.serverAction} does not accept positional arguments`);
+    }
+    const { readPackageVersion } = await import("./version.js");
+    if (parsed.options.serverStdio) {
+        const { runStdioBootstrapBridge } = await import("../mcp/stdio-bridge.js");
+        await runStdioBootstrapBridge({
+            cliPath: process.argv[1],
+            version: readPackageVersion(),
+            home: parsed.options.home,
+            tokenFile: parsed.options.serverTokenFile,
+            listen: parsed.options.listen,
+            mcpToolset: parsed.options.mcpToolset,
+        });
+        return;
     }
-    const { runMcpServer } = await import("./mcp.js");
-    await runMcpServer(createServiceOptions(parsed.options, process.cwd()));
+    if (parsed.options.serverAction === "on") {
+        const { startServer } = await import("../daemon/server-controller.js");
+        const status = await startServer({
+            cliPath: process.argv[1],
+            listen: parsed.options.listen,
+            tokenFile: parsed.options.serverTokenFile,
+            home: parsed.options.home,
+            mcpToolset: parsed.options.mcpToolset,
+        });
+        printServerControlStatus(status);
+        return;
+    }
+    if (parsed.options.serverAction === "off") {
+        const { stopServer } = await import("../daemon/server-controller.js");
+        printServerControlStatus(await stopServer(parsed.options.home, 30_000, parsed.options.serverTokenFile));
+        return;
+    }
+    if (parsed.options.serverAction === "status") {
+        const status = await serverStatus(parsed.options.home);
+        printServerControlStatus(status);
+        if (parsed.options.checkReady && !status.ready) {
+            throw new Error("zvec-grep server is not ready");
+        }
+        return;
+    }
+    const { runDaemonForeground } = await import("../daemon/runtime.js");
+    await runDaemonForeground({
+        version: readPackageVersion(),
+        listen: parsed.options.listen,
+        tokenFile: parsed.options.serverTokenFile,
+        home: parsed.options.home,
+        mcpToolset: parsed.options.mcpToolset,
+        serviceOptions: createServiceOptions(parsed.options, process.cwd()),
+    });
 }
 async function runStatus(parsed) {
     const root = parsed.positionals[0] ?? process.cwd();
     if (parsed.positionals.length > 1) {
         throw new Error("zg status accepts at most one root path");
     }
-    const zvecGrep = await createZvecGrep(createServiceOptions(parsed.options, root));
-    try {
-        const info = await zvecGrep.info({ root });
-        printAnonymousInfo(info, parsed.options);
-    }
-    finally {
-        await zvecGrep.close();
-    }
-}
-async function runCollections(parsed) {
-    const [action = "list", name, root] = parsed.positionals;
-    validateCollectionArguments(action, parsed.positionals);
-    const indexOption = collectionIndexOption(parsed.options);
-    if (action !== "index" && indexOption) {
-        throw new Error(`${indexOption} can only be used with zg collections index`);
-    }
-    const zvecGrep = await createZvecGrep(createServiceOptions(parsed.options, undefined));
-    try {
-        if (action === "list") {
-            if (parsed.options.resetPaths) {
-                throw new Error("--reset-paths can only be used with zg collections index");
-            }
-            printCollectionList(await zvecGrep.collections.list(), parsed.options);
-            return;
-        }
-        if (action === "info") {
-            if (parsed.options.resetPaths) {
-                throw new Error("--reset-paths can only be used with zg collections index");
-            }
-            if (!name) {
-                throw new Error("zg collections info requires <name>");
-            }
-            const [info, status] = await Promise.all([
-                zvecGrep.collections.info(name),
-                zvecGrep.collections.status(name),
-            ]);
-            if (!info) {
-                throw new Error(`Collection not found: ${name}`);
-            }
-            printCollectionInfo(info, status, parsed.options);
-            return;
-        }
-        if (action === "index") {
-            if (!name) {
-                throw new Error("zg collections index requires <name>");
-            }
-            const explicitRoot = root !== undefined;
-            const rootPath = indexRootPath(root ?? process.cwd(), parsed.options);
-            const rootPaths = explicitRoot ? rootPath : undefined;
-            const progress = createIndexProgressReporter();
+    const mode = resolveClientMode(parsed.options.mode);
+    const state = await routeByMode({
+        mode,
+        serverAvailable: () => daemonIsReady(parsed.options.home),
+        server: async () => {
+            const result = await daemonClient(parsed.options).callTool("zvec_grep_index_status", { root: resolve(root) });
+            return printServerIndexInfo(result, parsed.options);
+        },
+        direct: async () => {
+            const zvecGrep = await createZvecGrep(createServiceOptions(parsed.options, root));
             try {
-                const result = await zvecGrep.collections.index(name, rootPaths, {
-                    rebuild: parsed.options.rebuild,
-                    resetPaths: parsed.options.resetPaths,
-                    globs: parsed.options.globs,
-                    insensitiveGlobs: parsed.options.insensitiveGlobs,
-                    fileTypes: parsed.options.fileTypes,
-                    excludedFileTypes: parsed.options.excludedFileTypes,
-                    hidden: parsed.options.hidden,
-                    noIgnore: parsed.options.noIgnore,
-                    ignoreFiles: parsed.options.ignoreFiles,
-                    maxDepth: parsed.options.maxDepth,
-                    maxFileSizeBytes: parsed.options.maxFileSizeBytes,
-                    follow: parsed.options.follow,
-                    embeddingConcurrency: parsed.options.embeddingConcurrency,
-                    onProgress: progress.report,
-                });
-                progress.finish();
-                const info = await zvecGrep.collections.info(name);
-                printIndexResult(`Indexed collection ${name}`, result, parsed.options, info?.rootPaths);
-                persistExplicitGlobalConfig(parsed.options, info?.embedding?.provider);
+                return printWorkspaceInfo(await zvecGrep.info({ root }), parsed.options);
             }
-            catch (error) {
-                progress.finish();
-                throw error;
-            }
-            return;
-        }
-        if (action === "remove") {
-            if (parsed.options.resetPaths) {
-                throw new Error("--reset-paths can only be used with zg collections index");
+            finally {
+                await zvecGrep.close();
             }
-            if (!name) {
-                throw new Error("zg collections remove requires <name>");
-            }
-            const removed = await zvecGrep.collections.remove(name);
-            printCollectionRemoveResult(name, removed, parsed.options);
-            return;
-        }
-        if (parsed.options.resetPaths) {
-            throw new Error("--reset-paths can only be used with zg collections index");
-        }
-        throw new Error(`Unknown collections action: ${action}`);
-    }
-    finally {
-        await zvecGrep.close();
-    }
-}
-function validateCollectionArguments(action, positionals) {
-    if (action === "list") {
-        if (positionals.length > 1) {
-            throw new Error("zg collections list does not accept arguments");
-        }
-        return;
-    }
-    if (action === "info" || action === "remove") {
-        if (positionals.length > 2) {
-            throw new Error(`zg collections ${action} accepts only <name>`);
-        }
-        return;
-    }
-    if (action === "index") {
-        if (positionals.length > 3) {
-            throw new Error("zg collections index accepts only <name> and [root]");
-        }
-        return;
+        },
+    });
+    if (parsed.options.checkReady && state !== "ready") {
+        throw new Error(`Workspace index is not ready (state: ${state})`);
     }
-    throw new Error(`Unknown collections action: ${action}`);
-}
-function collectionIndexOption(options) {
-    const candidates = [
-        [options.rebuild, "--rebuild"],
-        [options.resetPaths, "--reset-paths"],
-        [options.embedding, "--embedding"],
-        [options.modelCacheDir, "--model-cache"],
-        [options.llamaGpu, "--llama-gpu"],
-        [options.embeddingParallelism, "--embedding-parallelism"],
-        [options.apiKey, "--api-key"],
-        [options.endpoint, "--endpoint"],
-        [options.embeddingConcurrency, "--embedding-concurrency"],
-        [options.globs?.length, "--glob"],
-        [options.insensitiveGlobs?.length, "--iglob"],
-        [options.fileTypes?.length, "--type"],
-        [options.excludedFileTypes?.length, "--type-not"],
-        [options.hidden, "--hidden"],
-        [options.noIgnore, "--no-ignore"],
-        [options.ignoreFiles?.length, "--ignore-file"],
-        [options.maxDepth, "--max-depth"],
-        [options.maxFileSizeBytes, "--max-filesize"],
-        [options.follow, "--follow"],
-    ];
-    return candidates.find(([value]) => Array.isArray(value) ? value.length > 0 : value !== undefined)?.[1];
 }
 async function runQuery(parsed) {
-    const rgInput = parsed.options.rg ? normalizeRgInput(parsed) : undefined;
+    const rgInput = parsed.options.rg
+        ? normalizeManagedRgInput(parsed)
+        : undefined;
     const commandOptions = rgInput?.options ?? parsed.options;
     const queries = (rgInput?.queries ?? [
         ...parsed.positionals,
@@ -455,24 +434,64 @@ async function runQuery(parsed) {
             ? "zg query --rg requires a pattern. Use zg help query for examples."
             : "zg query requires text or --hybrid/--fts/--vector routes. Use zg help query for examples.");
     }
-    const zvecGrep = await createZvecGrep(createServiceOptions(commandOptions, undefined));
-    const progress = createIndexProgressReporter();
+    if (!commandOptions.rg) {
+        const mode = resolveClientMode(commandOptions.mode);
+        if (mode !== "direct") {
+            await routeByMode({
+                mode,
+                serverAvailable: () => daemonIsReady(commandOptions.home),
+                server: () => runServerQuery(commandOptions, queries, routes),
+                direct: () => runDirectQuery(commandOptions, queries),
+            });
+            return;
+        }
+    }
+    await runDirectQuery(commandOptions, queries);
+}
+async function runDirectQuery(commandOptions, queries) {
+    if (commandOptions.refresh === "background") {
+        console.error("warning: --refresh background requires Server mode; Direct mode uses --refresh off");
+    }
+    const serviceOptions = createServiceOptions(commandOptions, undefined);
+    const zvecGrep = await createZvecGrep(serviceOptions);
+    const progress = createIndexProgressReporter({
+        color: commandOptions.color,
+    });
     try {
-        const result = await zvecGrep.context(contextOptions(commandOptions, queries, (progressEvent) => {
-            if (progressEvent.phase !== "done") {
+        const contextRequest = contextOptions(commandOptions, queries, (progressEvent) => {
+            if (progressEvent.phase !== "done")
                 progress.report(progressEvent);
-            }
-        }));
+        });
+        const info = await directQueryInfo(zvecGrep);
+        const schema = info.workspaceIndex?.embedding;
+        const workspaceRuntime = workspaceRuntimeFromInfo(info);
+        const modelInfo = !commandOptions.rg && schema?.provider === "qwen"
+            ? await embeddingModelInfo(schema, createServiceOptions(commandOptions, info.root), workspaceRuntime)
+            : undefined;
+        const plan = modelInfo
+            ? await planRemoteSearchAuthorization({
+                info,
+                model: modelInfo,
+                search: normalizedDirectSearchInput(commandOptions, queries, info.root),
+                store: authorizationStore(commandOptions),
+            })
+            : undefined;
+        const authorizationResolution = plan
+            ? await authorizeCliPlan(plan, commandOptions, "local_search")
+            : {};
+        const effectiveContextRequest = authorizationResolution.alternative === "local_search"
+            ? ftsFallbackContextRequest(contextRequest)
+            : contextRequest;
+        const result = await withRemoteEmbeddingOperationPermit(authorizationResolution.authorization, () => zvecGrep.context(effectiveContextRequest));
         progress.finish();
-        if (commandOptions.human) {
-            printHumanContextResult(result, commandOptions);
-        }
-        else {
-            printAgentContextResult(result, commandOptions);
-        }
+        printCliContextResult(result, commandOptions);
         for (const line of contextWarningLines(result)) {
             console.error(line);
         }
+        if (effectiveContextRequest.autoUpdate !== true &&
+            indexStatusNeedsRefresh(info.status)) {
+            printStaleIndexStatus("idle", indexCompletionFromStatus(info.status));
+        }
         if (commandOptions.debug) {
             printDebug(result, {
                 trace: commandOptions.trace === true,
@@ -487,7 +506,113 @@ async function runQuery(parsed) {
         await zvecGrep.close();
     }
 }
+async function runServerQuery(options, queries, routes) {
+    const searchPolicy = resolveServerSearchPolicy(options);
+    const structuredContent = await daemonClient(options).callTool("zvec_grep_search", {
+        root: resolve(process.cwd()),
+        apiKey: options.apiKey,
+        device: options.device,
+        queries: queries.length ? queries : undefined,
+        routes: routes.length ? routes : undefined,
+        fuse: options.fuse,
+        limit: options.limit,
+        trace: options.trace,
+        preferSymbol: options.preferSymbol,
+        symbolTypes: options.symbolTypes,
+        globs: options.globs,
+        insensitiveGlobs: options.insensitiveGlobs,
+        fileTypes: options.fileTypes,
+        excludedFileTypes: options.excludedFileTypes,
+        hidden: options.hidden,
+        noIgnore: options.noIgnore,
+        ignoreFiles: options.ignoreFiles,
+        maxDepth: options.maxDepth,
+        maxFileSizeBytes: options.maxFileSizeBytes,
+        follow: options.follow,
+        embeddingConcurrency: options.embeddingConcurrency,
+        modifiedAfter: options.modifiedAfter,
+        modifiedBefore: options.modifiedBefore,
+        freshness: searchPolicy.freshness,
+        autoUpdate: searchPolicy.autoUpdate,
+    }, {
+        toolContract: {
+            inputProperties: ["routes"],
+            outputProperties: ["result"],
+            errorMessage: INCOMPATIBLE_SERVER_SEARCH_MESSAGE,
+        },
+    });
+    const response = parseServerSearchResponse(structuredContent);
+    printCliContextResult(response.result, options);
+    for (const line of contextWarningLines(response.result)) {
+        console.error(line);
+    }
+    if (response.freshness === "possibly_stale") {
+        printStaleIndexStatus(response.indexing?.state, response.indexing);
+    }
+    if (options.debug) {
+        printDebug(response.result, { trace: options.trace === true });
+    }
+}
+function printStaleIndexStatus(state, completion) {
+    console.error("status: possibly_stale");
+    if (!state)
+        return;
+    const progress = completion?.completed === undefined || completion.total === undefined
+        ? ""
+        : ` (${completion.completed}/${completion.total})`;
+    console.error("results: served_from_current_index");
+    console.error(`background_refresh: ${state}${progress}`);
+}
+function daemonClient(options) {
+    return new DaemonClient({
+        serverUrl: resolveServerUrl(),
+        home: options.home,
+        tokenFile: options.serverTokenFile,
+        allowRemote: options.allowRemote,
+    });
+}
+function ftsFallbackContextRequest(request) {
+    const queries = [
+        ...(request.queries ?? []),
+        ...(request.query ? [request.query] : []),
+        ...(request.routes ?? []).map((route) => route.query),
+    ];
+    return {
+        ...request,
+        query: undefined,
+        queries: undefined,
+        routes: queries.map((query) => ({ mode: "fts", query })),
+        autoUpdate: false,
+    };
+}
+async function directQueryInfo(service) {
+    return await service.info({ root: process.cwd() });
+}
+function normalizedDirectSearchInput(options, queries, root) {
+    const policy = resolveDirectSearchPolicy(options);
+    return {
+        root,
+        apiKey: options.apiKey,
+        device: options.device,
+        queries: !options.rg && queries.length > 0 ? [...queries] : undefined,
+        routes: [...(options.routes ?? [])],
+        ...policy,
+    };
+}
+async function daemonIsReady(home) {
+    return (await serverStatus(home)).ready;
+}
+function printServerControlStatus(status) {
+    console.log(`Server: ${status.running ? (status.ready ? "ready" : "starting") : "stopped"}`);
+    if (status.pid)
+        console.log(`PID: ${status.pid}`);
+    if (status.serverUrl)
+        console.log(`URL: ${status.serverUrl}`);
+    if (status.mcpToolset)
+        console.log(`MCP toolset: ${status.mcpToolset}`);
+}
 function contextOptions(options, queries, onAutoUpdateProgress) {
+    const policy = resolveDirectSearchPolicy(options);
     return {
         queries: queries.length > 0 ? queries : undefined,
         rg: options.rg,
@@ -495,9 +620,8 @@ function contextOptions(options, queries, onAutoUpdateProgress) {
         rgPaths: options.rgPaths,
         routes: options.routes,
         fuse: options.fuse,
-        collection: options.collection,
         limit: options.limit,
-        autoUpdate: !options.noAutoUpdate,
+        autoUpdate: policy.autoUpdate,
         onAutoUpdateProgress,
         trace: options.trace,
         preferSymbol: options.preferSymbol,
@@ -517,303 +641,23 @@ function contextOptions(options, queries, onAutoUpdateProgress) {
         embeddingConcurrency: options.embeddingConcurrency,
     };
 }
-function normalizeRgInput(parsed) {
-    const explicitPatterns = parsed.options.rgOptions?.patterns ?? [];
-    const hasPatternFiles = (parsed.options.rgOptions?.patternFiles?.length ?? 0) > 0;
-    const queries = explicitPatterns.length > 0 || hasPatternFiles
-        ? explicitPatterns
-        : parsed.positionals.slice(0, 1);
-    const paths = explicitPatterns.length > 0 || hasPatternFiles
-        ? parsed.positionals
-        : parsed.positionals.slice(1);
-    return {
-        queries,
-        options: {
-            ...parsed.options,
-            rgPaths: paths.length > 0 ? paths : undefined,
-        },
-    };
-}
 export function createServiceOptions(options, root) {
-    const embedding = options.embedding ?? process.env.ZVEC_GREP_EMBEDDING;
-    const apiKey = options.apiKey ??
-        process.env.ZVEC_GREP_API_KEY ??
-        process.env.DASHSCOPE_API_KEY ??
-        process.env.QWEN_API_KEY;
-    const endpoint = options.endpoint ?? process.env.ZVEC_GREP_ENDPOINT;
     return {
         root,
         home: options.home ?? process.env.ZVEC_GREP_HOME,
-        embedding,
-        apiKey,
-        endpoint,
-        modelCacheDir: options.modelCacheDir ?? process.env.ZVEC_GREP_MODEL_CACHE,
-        llamaGpu: options.llamaGpu ?? parseEnvLlamaGpu(process.env.ZVEC_GREP_LLAMA_GPU),
-        embeddingParallelism: options.embeddingParallelism ??
-            parseEnvPositiveInteger(process.env.ZVEC_GREP_EMBED_PARALLELISM),
+        embedding: options.embedding,
+        apiKey: options.apiKey,
+        endpoint: options.endpoint,
+        modelCacheDir: options.modelCacheDir,
+        device: options.device,
+        authorizationSigningKeyPath: process.env.ZVEC_GREP_AUTHORIZATION_KEY_FILE,
     };
 }
-function persistExplicitGlobalConfig(options, indexedProvider) {
-    if (!updateGlobalConfigFromExplicitOptions(options, indexedProvider)) {
-        return;
-    }
-    console.log(`Global config: ${globalConfigPath()}`);
-}
-function parseEnvLlamaGpu(value) {
-    const normalized = value?.trim().toLowerCase() ?? "";
-    if (!normalized) {
-        return undefined;
-    }
-    if (normalized === "auto" ||
-        normalized === "metal" ||
-        normalized === "vulkan" ||
-        normalized === "cuda") {
-        return normalized;
-    }
-    if (["false", "off", "none", "disable", "disabled", "0"].includes(normalized)) {
-        return false;
-    }
-    return undefined;
-}
-function parseEnvPositiveInteger(value) {
-    const normalized = value?.trim() ?? "";
-    if (!/^\d+$/.test(normalized)) {
-        return undefined;
-    }
-    const parsed = Number(normalized);
-    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
-}
-function resolveCodexHome() {
-    return resolve(process.env.CODEX_HOME ?? resolve(homedir(), ".codex"));
-}
-async function writeMarkedFile(options) {
-    let existing = await readTextFileIfExists(options.path);
-    const next = replaceMarkedBlock(existing, options.startMarker, options.endMarker, options.block);
-    if (next === null) {
-        existing = removeOrphanedMarkers(existing, options.startMarker, options.endMarker);
-    }
-    if (next === null && options.hasConflict?.(existing)) {
-        if (!options.force) {
-            throw new Error(options.conflictMessage ??
-                `Existing unmanaged configuration found in ${options.path}`);
-        }
-        existing = options.removeConflict
-            ? options.removeConflict(existing)
-            : existing;
-    }
-    await writeTextFileAtomic(options.path, next ?? appendMarkedBlock(existing, options.block));
-}
-async function removeMarkedFile(options) {
-    const existing = await readTextFileIfExists(options.path);
-    if (!existing) {
-        return;
-    }
-    const next = replaceMarkedBlock(existing, options.startMarker, options.endMarker, "") ??
-        removeOrphanedMarkers(existing, options.startMarker, options.endMarker);
-    if (next === existing) {
-        return;
-    }
-    await writeTextFileAtomic(options.path, next);
-}
-async function writeTextFileAtomic(path, content) {
-    const targetPath = await resolveAtomicWriteTarget(path);
-    await mkdir(dirname(targetPath), { recursive: true });
-    const mode = await fileModeIfExists(targetPath);
-    const temporaryPath = `${targetPath}.${process.pid}.${randomUUID()}.tmp`;
-    let temporaryFile;
-    try {
-        temporaryFile = await open(temporaryPath, "wx", mode);
-        await temporaryFile.writeFile(content, "utf8");
-        await temporaryFile.sync();
-        await temporaryFile.close();
-        temporaryFile = undefined;
-        if (mode !== undefined) {
-            await chmod(temporaryPath, mode);
-        }
-        await rename(temporaryPath, targetPath);
-    }
-    catch (error) {
-        await temporaryFile?.close().catch(() => undefined);
-        await unlink(temporaryPath).catch(() => undefined);
-        throw error;
-    }
-}
-async function resolveAtomicWriteTarget(path, visited = new Set()) {
-    const absolutePath = resolve(path);
-    if (visited.has(absolutePath)) {
-        throw new Error(`Cannot atomically write through circular symbolic link: ${path}`);
-    }
-    try {
-        const file = await lstat(absolutePath);
-        if (!file.isSymbolicLink()) {
-            return absolutePath;
-        }
-        visited.add(absolutePath);
-        const link = await readlink(absolutePath);
-        return resolveAtomicWriteTarget(resolve(dirname(absolutePath), link), visited);
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT") {
-            return absolutePath;
-        }
-        throw error;
-    }
-}
-async function fileModeIfExists(path) {
-    try {
-        return (await stat(path)).mode & 0o777;
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT") {
-            return undefined;
-        }
-        throw error;
-    }
-}
-async function readTextFileIfExists(path) {
-    try {
-        return await readFile(path, "utf8");
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-            return "";
-        }
-        throw error;
-    }
-}
-function isNodeError(error) {
-    return typeof error === "object" && error !== null && "code" in error;
-}
-function replaceMarkedBlock(existing, startMarker, endMarker, block) {
-    const lines = existing.split(/\r?\n/);
-    const markerLines = new Set();
-    const ranges = [];
-    let pendingStart;
-    for (const [index, line] of lines.entries()) {
-        const trimmed = line.trim();
-        if (trimmed === startMarker) {
-            markerLines.add(index);
-            pendingStart = index;
-            continue;
-        }
-        if (trimmed === endMarker) {
-            markerLines.add(index);
-            if (pendingStart !== undefined) {
-                ranges.push({ start: pendingStart, end: index });
-                pendingStart = undefined;
-            }
-        }
-    }
-    const first = ranges[0];
-    if (!first) {
-        return null;
-    }
-    const before = retainedMarkedLines(lines, 0, first.start, markerLines, [])
-        .join("\n")
-        .trimEnd();
-    const after = retainedMarkedLines(lines, first.end + 1, lines.length, markerLines, ranges.slice(1))
-        .join("\n")
-        .trim();
-    return ([before, block.trim(), after.trim()]
-        .filter((part) => part.length > 0)
-        .join("\n\n") + "\n");
-}
-function retainedMarkedLines(lines, start, end, markerLines, removedRanges) {
-    const retained = [];
-    for (let index = start; index < end; index += 1) {
-        if (markerLines.has(index)) {
-            continue;
-        }
-        if (removedRanges.some((range) => index >= range.start && index <= range.end)) {
-            continue;
-        }
-        retained.push(lines[index]);
-    }
-    return retained;
-}
-function removeOrphanedMarkers(existing, startMarker, endMarker) {
-    return (existing
-        .split(/\r?\n/)
-        .filter((line) => {
-        const trimmed = line.trim();
-        return trimmed !== startMarker && trimmed !== endMarker;
-    })
-        .join("\n")
-        .trimEnd() + "\n");
-}
-function appendMarkedBlock(existing, block) {
-    const prefix = existing.trimEnd();
-    return `${prefix.length > 0 ? `${prefix}\n\n` : ""}${block.trim()}\n`;
-}
-function hasCodexMcpServerConfig(existing) {
-    return existing.split(/\r?\n/).some((line) => {
-        const tableName = tomlTableName(line);
-        return tableName !== undefined && isCodexMcpServerTableName(tableName);
-    });
-}
-function removeCodexMcpServerConfig(existing) {
-    const lines = existing.split(/\r?\n/);
-    const kept = [];
-    let skipping = false;
-    for (const line of lines) {
-        const tableName = tomlTableName(line);
-        if (tableName !== undefined) {
-            skipping = isCodexMcpServerTableName(tableName);
-        }
-        if (!skipping) {
-            kept.push(line);
-        }
-    }
-    return kept.join("\n").trimEnd() + "\n";
-}
-function tomlTableName(line) {
-    return line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/)?.[1]?.trim();
-}
-function isCodexMcpServerTableName(tableName) {
-    return /^(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*\.\s*(?:zvec_grep|"zvec_grep"|'zvec_grep')(?:\s*\.|$)/.test(tableName);
-}
-function codexConfigBlock(mcpToolTimeoutSeconds) {
-    return `${ZVEC_GREP_CONFIG_START}
-[mcp_servers.zvec_grep]
-command = "zg"
-args = ["serve", "--mcp"]
-env_vars = [
-  "DASHSCOPE_API_KEY",
-  "QWEN_API_KEY",
-  "ZVEC_GREP_API_KEY",
-  "ZVEC_GREP_EMBEDDING",
-  "ZVEC_GREP_ENDPOINT",
-  "ZVEC_GREP_HOME",
-  "ZVEC_GREP_MODEL_CACHE",
-  "ZVEC_GREP_LLAMA_GPU",
-  "ZVEC_GREP_EMBED_PARALLELISM",
-  "NODE_LLAMA_CPP_CMAKE_OPTION_GGML_OPENMP",
-  "NODE_LLAMA_CPP_CMAKE_OPTION_GGML_NATIVE",
-  "NODE_LLAMA_CPP_CMAKE_OPTION_GGML_CPU_ARM_ARCH"
-]
-startup_timeout_sec = 20
-tool_timeout_sec = ${mcpToolTimeoutSeconds}
-default_tools_approval_mode = "auto"
-${ZVEC_GREP_CONFIG_END}`;
-}
-function codexAgentsBlock() {
-    return `${ZVEC_GREP_AGENTS_START}
-## zvec-grep
-
-Use zvec-grep before grep, rg, or broad file reads when you need to understand or locate code.
-
-- **MCP tools**: Use \`zvec_grep_search\` for indexed semantic/lexical code search and \`zvec_grep_rg\` for explicit no-index lexical search.
-- **Indexing and status**: These are CLI-only operations. If an index is missing, use \`zvec_grep_rg\` and mention \`zg index\` as the opt-in setup path; use \`zg status\` when status inspection is needed.
-- **Shell fallback**: If the MCP server is unavailable, use \`zg status\`, \`zg query "<query>"\`, and \`zg query --rg "<pattern>"\`.
-
-Prefer focused -g/--glob and -t/--type filters, and exclude dependencies, generated output, caches, build artifacts, and logs unless the task is about those files.
-${ZVEC_GREP_AGENTS_END}`;
-}
 function resolveIndexRoot(root) {
     if (root !== undefined) {
         return root;
     }
-    return findNearestAnonymousWorkspace(process.cwd())?.root ?? process.cwd();
+    return findNearestWorkspace(process.cwd())?.root ?? process.cwd();
 }
 function indexRootPath(path, options) {
     return {