ast-mcp-server 0.9.2 → 0.11.0

package/dist/services/context-builder.js

@@ -1,15 +1,20 @@
-import { Buffer } from "node:buffer";
 import path from "node:path";
 import { buildFileOutline, nodeSourceWithLocation } from "./outline.js";
 import { paginate } from "./pagination.js";
+import { resolveImpactRoot } from "./impact.js";
+import { planCallSpines } from "./call-spines.js";
 import { isCooperativeInterruption, NO_REQUEST_CONTEXT, } from "./request-context.js";
 import { findDeclarationByName, getSourceFileOrThrow, reportSymbolIndexFailure, } from "./project.js";
 import { collectSymbolReferences } from "./references.js";
+import { collectCompilerCallRelationships } from "./relationships.js";
+import { presentExploreClusters } from "./explore-presentation.js";
 import { searchProjectSymbolsPage, searchProjectSymbolsPageWithIndex, sourceFileSymbols, symbolMatchRank, } from "./symbols.js";
 export const EXPLORE_DEFAULT_LIMIT = 20;
 export const EXPLORE_DEFAULT_REFERENCE_LIMIT = 20;
 export const EXPLORE_DEFAULT_MAX_BYTES = 64 * 1024;
 export const EXPLORE_MAX_BYTES = 1024 * 1024;
+export const EXPLORE_DEFAULT_OMISSION_DETAIL_LIMIT = 20;
+export const EXPLORE_MAX_OMISSION_DETAIL_LIMIT = 100;
 function matchesQuery(record, query) {
     const normalizedQuery = query.toLowerCase();
     return (record.name.toLowerCase().includes(normalizedQuery) ||
@@ -130,9 +135,6 @@ function projectSymbol(detail, record) {
         signature: record.signature,
     };
 }
-function jsonBytes(value) {
-    return Buffer.byteLength(JSON.stringify(value), "utf8");
-}
 function effectiveExpansion(request) {
     return {
         source: request.includeSource ?? (request.detail === "context" || request.detail === "full"),
@@ -148,6 +150,27 @@ export async function buildExploreContext(context, request, requestContext = NO_
     const expansion = effectiveExpansion(request);
     const unresolved = [];
     const evidence = [];
+    let callSpines;
+    if (request.callSpines) {
+        if (!request.filePath || !request.symbolPath || routed.route !== "symbol") {
+            throw new Error("Call spines require an exact file_path and symbol_path.");
+        }
+        const freshness = {
+            state: effectiveContext.status.state,
+            causes: effectiveContext.status.causes,
+            checked_at: effectiveContext.status.lastSuccessfulSyncAt,
+        };
+        const root = resolveImpactRoot(effectiveContext.project, effectiveContext.projectRoot, { file_path: request.filePath, symbol_path: request.symbolPath }, requestContext);
+        const projected = collectCompilerCallRelationships(effectiveContext.project, effectiveContext.projectRoot, freshness, { max_edges: request.callSpines.maxEdges }, requestContext);
+        callSpines = planCallSpines(root, projected.edges, {
+            direction: request.callSpines.direction,
+            max_depth: request.callSpines.maxDepth,
+            max_nodes: request.callSpines.maxNodes,
+            max_edges: request.callSpines.maxEdges,
+            discovery_complete: !projected.incomplete,
+            freshness,
+        });
+    }
     for (const record of page.items) {
         requestContext.checkpoint();
         let sourceFile;
@@ -190,30 +213,66 @@ export async function buildExploreContext(context, request, requestContext = NO_
         }
     }
     const symbols = page.items.map((record) => projectSymbol(request.detail, record));
-    let returnedSymbols = [...symbols];
-    let returnedEvidence = [...evidence];
-    let reason = page.has_more ? "record_limit" : null;
-    let result = createResult(effectiveContext, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
-    while (jsonBytes(result) > request.maxBytes &&
-        (returnedEvidence.length > 0 || returnedSymbols.length > 0)) {
-        requestContext.checkpoint();
-        reason = "byte_limit";
-        if (returnedEvidence.length > 0) {
-            returnedEvidence = returnedEvidence.slice(0, -1);
+    const initialResult = createResult(effectiveContext, request, routed.route, routed.file, routed.symbol, symbols, evidence, page.total, unresolved, page.has_more ? "record_limit" : null);
+    const evidenceBySelector = new Map(evidence.map((item) => [item.selector, item]));
+    const omissions = unresolved.map((item) => ({
+        subject: item.selector,
+        category: "incomplete",
+        component: item.reason === "source_unresolved" ? "source" : "references",
+        reason: item.reason,
+    }));
+    for (const item of evidence) {
+        if (item.references?.has_more) {
+            omissions.push({
+                subject: item.selector,
+                category: "budget",
+                component: "references",
+                reason: "reference_limit",
+            });
         }
-        else {
-            returnedSymbols = returnedSymbols.slice(0, -1);
-            const selectors = new Set(returnedSymbols.map((symbol) => symbol.selector));
-            returnedEvidence = returnedEvidence.filter((item) => selectors.has(item.selector));
+    }
+    if (callSpines?.authority_state === "untrusted") {
+        omissions.push({
+            subject: callSpines.root.selector,
+            category: "untrusted",
+            component: "call_spine",
+            reason: "non_exact_evidence",
+        });
+    }
+    else if (callSpines?.authority_state === "incomplete") {
+        omissions.push({
+            subject: callSpines.root.selector,
+            category: "incomplete",
+            component: "call_spine",
+            reason: "call_discovery_incomplete",
+        });
+    }
+    if (callSpines) {
+        for (const reason of callSpines.truncation_reasons) {
+            omissions.push({
+                subject: callSpines.root.selector,
+                category: "budget",
+                component: "call_spine",
+                reason,
+            });
         }
-        result = createResult(effectiveContext, request, routed.route, routed.file, routed.symbol, returnedSymbols, returnedEvidence, page.total, unresolved, reason);
     }
     requestContext.checkpoint();
-    const usedBytes = jsonBytes(result);
-    return {
-        ...result,
-        budget: { ...result.budget, used_bytes: usedBytes },
-    };
+    return presentExploreClusters({
+        base: initialResult,
+        clusters: symbols.map((symbol) => ({
+            symbol,
+            evidence: evidenceBySelector.get(symbol.selector),
+        })),
+        offset: request.offset,
+        limit: request.limit,
+        total: page.total,
+        maxBytes: request.maxBytes,
+        omissions,
+        omissionDetailLimit: request.omissionDetailLimit ?? EXPLORE_DEFAULT_OMISSION_DETAIL_LIMIT,
+        callSpines,
+        unresolved,
+    });
 }
 function createResult(context, request, route, file, symbol, symbols, evidence, total, unresolved, reason) {
     const hasMore = request.offset + symbols.length < total;

package/dist/services/doctor-continuation.js

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function relativeArgument(project, cwd) {
+    const requested = project ?? ".";
+    if (/[\0\r\n]/u.test(requested))
+        return ".";
+    const relative = path.relative(cwd, path.resolve(cwd, requested)).split(path.sep).join("/") || ".";
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}
+function ambiguousArgument(project, cwd) {
+    let directory = path.resolve(cwd, project ?? ".");
+    while (true) {
+        const candidate = path.join(directory, "tsconfig.json");
+        if (existsSync(candidate) && existsSync(path.join(directory, "jsconfig.json")))
+            return relativeArgument(candidate, cwd);
+        if (existsSync(path.join(directory, ".git")))
+            break;
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return relativeArgument(path.join(project ?? ".", "tsconfig.json"), cwd);
+}
+export function buildDoctorConfigContinuation(state, discoveryContinuation, project, cwd) {
+    void discoveryContinuation;
+    const requested = state === "ambiguous" ? ambiguousArgument(project, cwd) : relativeArgument(project, cwd);
+    const command = `ast-tool doctor --project ${shellQuote(requested)}`;
+    if (state === "ambiguous")
+        return `Run: ${command}`;
+    return state === "unsafe"
+        ? `Replace the requested project location with a direct config, then run: ${command}`
+        : `Create the requested project location and a supported config, then run: ${command}`;
+}

package/dist/services/doctor-model.js

@@ -0,0 +1,77 @@
+import { sanitizePublicText } from "./public-errors.js";
+function item(code, status, summary, reasonCode, continuation, continuationTrusted = false) {
+    return {
+        code,
+        status,
+        summary: sanitizePublicText(summary),
+        reason_code: reasonCode,
+        ...(continuation
+            ? { continuation: continuationTrusted ? continuation : sanitizePublicText(continuation) }
+            : {}),
+    };
+}
+function overall(checks) {
+    if (checks.some((check) => check.status === "failed"))
+        return "failed";
+    return checks.some((check) => check.status === "degraded") ? "degraded" : "healthy";
+}
+export function evaluateDoctor(evidence) {
+    const checks = [];
+    checks.push(evidence.runtime_invalid
+        ? item("runtime_policy", "degraded", "Runtime limits contain invalid values and defaults were applied.", "invalid_runtime_policy", "Fix AST runtime limit values, then run: ast-tool doctor")
+        : item("runtime_policy", "healthy", "Runtime limits are admitted.", "runtime_policy_ready"));
+    checks.push(evidence.config.state === "ready"
+        ? item("project_config", "healthy", "A unique project config was resolved.", "config_ready")
+        : item("project_config", "failed", "Project config discovery did not produce a safe unique identity.", `config_${evidence.config.state}`, evidence.config.continuation, evidence.config.continuation_trusted));
+    if (evidence.project) {
+        const { compiler, watcher, index, operation_queue: queue } = evidence.project;
+        checks.push(compiler.state === "ready"
+            ? item("compiler", "healthy", "Compiler synchronization is ready.", "compiler_ready")
+            : item("compiler", compiler.state === "failed" ? "failed" : "degraded", "Compiler synchronization is not ready.", `compiler_${compiler.state}`, "Run: ast-tool doctor"));
+        checks.push(watcher.state === "ready"
+            ? item("watcher", "healthy", "Project watcher is ready.", "watcher_ready")
+            : item("watcher", "degraded", "Project watcher is unavailable; compiler reads may require resynchronization.", `watcher_${watcher.state}`, "Restart MCP clients, then run: ast-tool doctor"));
+        checks.push(evidence.project_authority === "isolated" && index.state === "disabled"
+            ? item("derived_index", "not_run", "Persistent derived-index inspection is disabled for an isolated diagnosis.", "index_not_run_diagnostic_policy")
+            : index.state === "ready" || index.state === "disabled"
+                ? item("derived_index", "healthy", index.state === "ready"
+                    ? "Derived symbol index is ready."
+                    : "Derived symbol index is disabled by admitted policy.", `index_${index.state}`)
+                : item("derived_index", "degraded", compiler.state === "ready"
+                    ? "Derived index is unavailable; compiler-backed file operations remain available."
+                    : "Derived index is unavailable while compiler synchronization is not ready.", compiler.state === "ready" ? "index_degraded_compiler_ready" : `index_${index.state}`, "Run: ast-tool cache inspect"));
+        const queueDegraded = evidence.runtime_admission !== "open" ||
+            queue.admission !== "open" ||
+            queue.rejected_operations > 0 ||
+            queue.queue_timeout_operations > 0 ||
+            queue.deadline_exceeded_operations > 0;
+        checks.push(evidence.project_authority === "isolated" && evidence.runtime_admission === "open"
+            ? item("operation_queue", "not_run", "No registered project queue exists to inspect.", "queue_not_run_no_registered_session")
+            : queueDegraded
+                ? item("operation_queue", "degraded", "Operation queue reports admission or timeout pressure.", evidence.runtime_admission === "closed"
+                    ? "runtime_admission_closed"
+                    : "queue_pressure", "Run: ast-tool doctor")
+                : item("operation_queue", "healthy", "Operation queue is accepting work.", "queue_ready"));
+    }
+    else if (evidence.config.state === "ready" && evidence.project_authority === "unavailable") {
+        checks.push(item("compiler", "not_run", "Compiler diagnosis is unavailable while runtime admission is closed.", "compiler_not_run_runtime_closed"), item("watcher", "not_run", "Watcher check requires compiler diagnosis.", "watcher_not_run"), item("derived_index", "not_run", "Derived index check requires compiler diagnosis.", "index_not_run"), item("operation_queue", "degraded", "Project runtime admission is closed.", "runtime_admission_closed", "Restart MCP clients, then run: ast-tool doctor"));
+    }
+    else if (evidence.config.state === "ready") {
+        checks.push(item("compiler", "failed", "Compiler creation failed.", "compiler_creation_failed", "Run: ast-tool doctor"), item("watcher", "not_run", "Watcher check requires a ready compiler.", "watcher_not_run"), item("derived_index", "not_run", "Derived index check requires a ready compiler.", "index_not_run"), item("operation_queue", "not_run", "Queue check requires a diagnostic project.", "queue_not_run"));
+    }
+    else {
+        checks.push(item("compiler", "not_run", "Compiler check requires a project config.", "compiler_not_run"), item("watcher", "not_run", "Watcher check requires a project config.", "watcher_not_run"), item("derived_index", "not_run", "Derived index check requires a project config.", "index_not_run"), item("operation_queue", "not_run", "Queue check requires a project config.", "queue_not_run"));
+    }
+    checks.push(evidence.cache.state === "failed" || evidence.cache.unsafe_entry_count > 0
+        ? item("index_cache", "degraded", "Index cache inspection found unavailable or unsafe state.", evidence.cache.unsafe_entry_count > 0 ? "cache_unsafe" : "cache_failed", "Run: ast-tool cache inspect")
+        : item("index_cache", "healthy", `Index cache is ${evidence.cache.state}.`, `cache_${evidence.cache.state}`));
+    checks.push(evidence.package.state === "ready"
+        ? item("package", "healthy", `Package version ${evidence.package.version ?? "unknown"} is locally admitted.`, "package_ready")
+        : item("package", "degraded", "Running package provenance could not be admitted locally.", `package_${evidence.package.state}`, "Run: ast-tool upgrade --check"));
+    checks.push(evidence.setup.state === "ready"
+        ? item("client_setup", "healthy", "Detected client skills are current.", "setup_ready")
+        : item("client_setup", "degraded", "Detected client skill setup requires attention.", `setup_${evidence.setup.state}`, evidence.setup.state === "conflict"
+            ? "Run: ast-tool setup --agents all --yes --force-skill"
+            : "Run: ast-tool setup --agents all --yes"));
+    return { schema_version: 1, status: overall(checks), checks: checks.slice(0, 9) };
+}

package/dist/services/doctor.js

@@ -0,0 +1,111 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { detectInstalledAgents } from "./agent-setup.js";
+import { resolveCliBatchProject, CliProjectDiscoveryError } from "./cli-project-discovery.js";
+import { buildDoctorConfigContinuation } from "./doctor-continuation.js";
+import { evaluateDoctor } from "./doctor-model.js";
+import { getDiagnosticProjectStatus } from "./project.js";
+import { readRuntimePolicy } from "./runtime-policy.js";
+import { planBundledSkillInstallation, resolveBundledSkillAssets, SkillConflictError, } from "./skill-installer.js";
+import { inspectSymbolIndexCache, } from "./symbol-index-cache.js";
+async function resolveProject(project, cwd) {
+    const resolved = (await resolveCliBatchProject({ ...(project ? { project_root: project } : {}) }, cwd));
+    return resolved.project_root;
+}
+async function inspectPackage(executable) {
+    const cli = await realpath(executable);
+    const root = path.resolve(path.dirname(cli), "..");
+    const metadata = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    const bins = metadata.bin;
+    if (metadata.name !== "ast-mcp-server" ||
+        typeof metadata.version !== "string" ||
+        typeof bins?.["ast-tool"] !== "string" ||
+        (await realpath(path.resolve(root, bins["ast-tool"]))) !== cli)
+        return { state: "unsupported" };
+    return { state: "ready", version: metadata.version };
+}
+async function inspectSetup(executable, cwd, environment) {
+    const detections = await detectInstalledAgents({ environment, commandTimeoutMs: 5000 });
+    const installed = detections.filter((agent) => agent.installed);
+    if (installed.length === 0)
+        return { state: "ready" };
+    if (installed.some((agent) => agent.compatibility?.status !== "compatible"))
+        return { state: "outdated" };
+    const assets = await resolveBundledSkillAssets(executable);
+    try {
+        const plan = await planBundledSkillInstallation({
+            target: installed.map((agent) => agent.id),
+            scope: "user",
+            sourceSkillPath: assets.skillPath,
+            releaseManifestPath: assets.releasesPath,
+            environment,
+            ...(environment.HOME ? { homeDirectory: environment.HOME } : {}),
+            workingDirectory: cwd,
+        });
+        if (plan.installations.every((item) => item.status === "unchanged"))
+            return { state: "ready" };
+        return {
+            state: plan.installations.some((item) => item.status === "updated") ? "outdated" : "missing",
+        };
+    }
+    catch (error) {
+        if (error instanceof SkillConflictError)
+            return { state: "conflict" };
+        throw error;
+    }
+}
+const defaults = {
+    resolveProject,
+    projectStatus: getDiagnosticProjectStatus,
+    cache: (environment) => inspectSymbolIndexCache({ environment }),
+    package: inspectPackage,
+    setup: inspectSetup,
+    runtime: readRuntimePolicy,
+};
+export async function runDoctor(options, overrides = {}) {
+    const dependencies = { ...defaults, ...overrides };
+    const environment = options.environment ?? process.env;
+    const policy = dependencies.runtime(environment);
+    const runtimeInvalid = Object.values(policy.reasons).some((reason) => reason === "invalid_integer" || reason === "out_of_range");
+    let config = { state: "ready" };
+    let projectRoot;
+    try {
+        projectRoot = await dependencies.resolveProject(options.project, options.cwd);
+    }
+    catch (error) {
+        const discovery = error instanceof CliProjectDiscoveryError ? error : undefined;
+        const state = discovery?.code.endsWith("AMBIGUOUS")
+            ? "ambiguous"
+            : discovery?.code.endsWith("UNSAFE")
+                ? "unsafe"
+                : "missing";
+        config = {
+            state,
+            continuation: buildDoctorConfigContinuation(state, discovery?.continuation, options.project, options.cwd),
+            continuation_trusted: true,
+        };
+    }
+    let diagnostic;
+    if (projectRoot)
+        diagnostic = await dependencies.projectStatus(projectRoot).catch(() => undefined);
+    const [cache, packageEvidence, setup] = await Promise.all([
+        dependencies
+            .cache(environment)
+            .then((result) => ({ state: result.state, unsafe_entry_count: result.unsafe_entry_count }))
+            .catch(() => ({ state: "failed", unsafe_entry_count: 0 })),
+        dependencies.package(options.executable).catch(() => ({ state: "failed" })),
+        dependencies
+            .setup(options.executable, options.cwd, environment)
+            .catch(() => ({ state: "failed" })),
+    ]);
+    return evaluateDoctor({
+        runtime_invalid: runtimeInvalid,
+        project_authority: diagnostic?.authority ?? (projectRoot ? "failed" : "unavailable"),
+        runtime_admission: diagnostic?.runtime_admission ?? "open",
+        config,
+        ...(diagnostic?.status ? { project: diagnostic.status } : {}),
+        cache,
+        package: packageEvidence,
+        setup,
+    });
+}

package/dist/services/explore-presentation.js

@@ -0,0 +1,160 @@
+import { Buffer } from "node:buffer";
+export const EXPLORE_OMISSION_REASONS = [
+    "byte_limit",
+    "reference_limit",
+    "source_unresolved",
+    "references_unresolved",
+    "non_exact_evidence",
+    "call_discovery_incomplete",
+    "depth_limit",
+    "node_limit",
+    "edge_limit",
+];
+function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+function summarize(omissions, detailLimit) {
+    const details = [...omissions].sort((left, right) => [left.subject, left.category, left.component, left.reason]
+        .join("\0")
+        .localeCompare([right.subject, right.category, right.component, right.reason].join("\0")));
+    const countMap = new Map();
+    for (const item of omissions) {
+        const key = `${item.category}\0${item.component}`;
+        countMap.set(key, (countMap.get(key) ?? 0) + 1);
+    }
+    const counts = [...countMap]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, count]) => {
+        const [category, component] = key.split("\0");
+        return { category, component, count };
+    });
+    return {
+        counts,
+        details: details.slice(0, detailLimit),
+        total: omissions.length,
+        has_more: details.length > detailLimit,
+    };
+}
+function selectorOnly(symbol) {
+    return { file: symbol.file, selector: symbol.selector, kind: symbol.kind };
+}
+function omittedClusterParts(symbol, evidence) {
+    const component = (value) => ({
+        subject: symbol.selector,
+        category: "budget",
+        component: value,
+        reason: "byte_limit",
+    });
+    return [
+        ...(symbol.signature === undefined ? [] : [component("signature")]),
+        ...(evidence?.source === undefined ? [] : [component("source")]),
+        ...(evidence?.references === undefined ? [] : [component("references")]),
+    ];
+}
+export function presentExploreClusters(input) {
+    const symbols = [];
+    const evidence = [];
+    let omissions = [...input.omissions];
+    let consumed = 0;
+    let byteLimited = false;
+    const build = (detailLimit, includeCallSpines) => {
+        const callSpinesOmitted = input.callSpines !== undefined && !includeCallSpines;
+        const effectiveOmissions = callSpinesOmitted
+            ? [
+                ...omissions,
+                {
+                    subject: input.callSpines.root.selector,
+                    category: "budget",
+                    component: "call_spine",
+                    reason: "byte_limit",
+                },
+            ]
+            : omissions;
+        const spinesComplete = input.callSpines === undefined
+            ? undefined
+            : includeCallSpines && !input.callSpines.incomplete;
+        const hasMore = input.offset + consumed < input.total;
+        const evidenceComplete = effectiveOmissions.length === 0 &&
+            (input.unresolved?.length ?? 0) === 0 &&
+            spinesComplete !== false;
+        const reason = byteLimited || callSpinesOmitted ? "byte_limit" : hasMore ? "record_limit" : null;
+        const result = {
+            ...input.base,
+            ...(includeCallSpines && input.callSpines ? { call_spines: input.callSpines } : {}),
+            symbols,
+            evidence,
+            offset: input.offset,
+            limit: input.limit,
+            total: input.total,
+            has_more: hasMore,
+            next_offset: hasMore ? input.offset + consumed : null,
+            omissions: summarize(effectiveOmissions, detailLimit),
+            completeness: {
+                complete: !hasMore && evidenceComplete,
+                symbols_complete: !hasMore,
+                evidence_complete: evidenceComplete,
+                ...(spinesComplete === undefined ? {} : { spines_complete: spinesComplete }),
+                unresolved: input.unresolved ?? [],
+            },
+            budget: {
+                max_records: input.limit,
+                max_bytes: input.maxBytes,
+                max_depth: null,
+                max_edges: null,
+                max_invocations: 1,
+                used_bytes: 0,
+            },
+            truncation: { truncated: reason !== null, reason },
+        };
+        let usedBytes = 0;
+        let fixed = result;
+        for (let index = 0; index < 10; index += 1) {
+            fixed = { ...result, budget: { ...result.budget, used_bytes: usedBytes } };
+            const next = jsonBytes(fixed);
+            if (next === usedBytes)
+                return fixed;
+            usedBytes = next;
+        }
+        return { ...fixed, budget: { ...fixed.budget, used_bytes: jsonBytes(fixed) } };
+    };
+    const fittingResult = () => {
+        for (let detailLimit = input.omissionDetailLimit; detailLimit >= 0; detailLimit -= 1) {
+            if (input.callSpines) {
+                const included = build(detailLimit, true);
+                if (included.budget.used_bytes <= input.maxBytes)
+                    return included;
+            }
+            const omitted = build(detailLimit, false);
+            if (omitted.budget.used_bytes <= input.maxBytes)
+                return omitted;
+        }
+        return null;
+    };
+    for (const cluster of input.clusters) {
+        const omissionsBeforeCluster = omissions;
+        symbols.push(cluster.symbol);
+        if (cluster.evidence)
+            evidence.push(cluster.evidence);
+        consumed += 1;
+        if (fittingResult())
+            continue;
+        symbols[symbols.length - 1] = selectorOnly(cluster.symbol);
+        if (cluster.evidence)
+            evidence.pop();
+        omissions = [...omissions, ...omittedClusterParts(cluster.symbol, cluster.evidence)];
+        byteLimited = true;
+        if (fittingResult())
+            continue;
+        if (symbols.length > 1) {
+            symbols.pop();
+            consumed -= 1;
+            omissions = omissionsBeforeCluster;
+            break;
+        }
+        throw new Error(`max_bytes cannot fit selector ${cluster.symbol.selector}.`);
+    }
+    const result = fittingResult();
+    if (!result)
+        throw new Error("max_bytes cannot fit the ast_explore result shell.");
+    return result;
+}