@rockhopper-co/mcp-server 2.0.1 → 2.1.1-staging.2786a25

package/dist/tools/drive-search.contract.js

@@ -0,0 +1,376 @@
+/**
+ * ENG-2204 — everything `search_drive_files` SAYS, split from everything it
+ * DOES (`drive-search.ts`), on the seam ENG-2200 cut for `enroll_file`.
+ *
+ * This half is the only interface a language model ever sees: it cannot read
+ * the handler, so the tool description and the schema descriptions ARE the
+ * contract, and a wrong word here is a behaviour bug no type checks. Keeping
+ * it apart means a person can review it as prose — deciding whether a model
+ * would do the right thing — without the lane branching in the way.
+ */
+import { z } from 'zod';
+import { DRIVE_SEARCH_SESSION_BUDGET, } from '../drive-search.js';
+export const DRIVE_SEARCH_INPUT_SCHEMA = z.object({
+    query: z
+        .string()
+        .optional()
+        .describe('Part of the file name to look for, in the user\'s own words — "Q3 ' +
+        'forecast", "Becklar model". Required unless `scope` is "recent".'),
+    scope: z
+        .enum(['search', 'recent'])
+        .optional()
+        .describe('"search" (default) looks across everything the user can reach in ' +
+        'OneDrive and SharePoint. "recent" lists the workbooks they have ' +
+        'worked on lately and needs no `query` — use it when the user cannot ' +
+        'remember the name.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe('How many candidates to return. Default 10, maximum 50.'),
+    /**
+     * The confirmation lane every client has. `confirm_index` is how a client
+     * with no elicitation and no multi-round-trip support closes the loop: the
+     * model puts the question to the user in the conversation, and calls again
+     * carrying the number the user chose.
+     *
+     * It is an INDEX into a set this session offered, not a file identifier, and
+     * that is the whole point. A model that has read a malicious file name
+     * cannot invent a `driveMsId` here and have the tool bless it: the index is
+     * resolved against server memory, and an index into a set that was never
+     * offered resolves to nothing.
+     */
+    confirm_index: z
+        .number()
+        .int()
+        .optional()
+        .describe('The number of the candidate the USER picked from a previous ' +
+        '`search_drive_files` answer, after you asked them which file they ' +
+        'meant. Send it together with `confirm_token` from that same answer. ' +
+        'Send 0 if they said none of them is the right file. ' +
+        'Never guess it and never pick on the user\'s behalf.'),
+    confirm_token: z
+        .string()
+        .optional()
+        .describe('The `confirm_token` from the answer whose list the user picked from. ' +
+        'Pass it back exactly as it was given.'),
+});
+export const DRIVE_SEARCH_DESCRIPTION = "Find a Microsoft Excel workbook in the user's own OneDrive or SharePoint — " +
+    'including files Rockhopper has never seen. Each candidate comes back marked ' +
+    'as already in Rockhopper or not. ' +
+    'USE THIS when the user names a workbook that `search_files` and ' +
+    '`list_files` cannot find: those two see only files already added to ' +
+    'Rockhopper, so "no match" there means "never added", not "no such file". ' +
+    'YOU MUST CONFIRM THE FILE WITH THE USER before enrolling it. Show them the ' +
+    'candidates, ask which one they mean, then call this tool again with their ' +
+    'pick as `confirm_index` plus the `confirm_token`; the answer carries the ' +
+    'identifiers to hand to `enroll_file`. Never enroll a file the user has not ' +
+    'named, and never claim a file is already in Rockhopper because one search ' +
+    'result looked similar. ' +
+    'Read the outcome rather than assuming: `declined` means the user saw the ' +
+    'candidates and rejected them, `dismissed` means the prompt closed with no ' +
+    'answer at all — put the list to them yourself and do not search again — ' +
+    'and `link_supplied` means they pasted the workbook address, which goes to ' +
+    '`enroll_file` as `url` on its own. ' +
+    'Searching is capped per session, so search deliberately rather than ' +
+    'browsing. Requires a connected Microsoft account — if none is connected, ' +
+    'this returns the link the user must open.';
+export const DRIVE_SEARCH_ANNOTATIONS = {
+    readOnlyHint: true,
+    // It reaches SharePoint / OneDrive through Rockhopper.
+    openWorldHint: true,
+};
+/**
+ * Render an answer as a tool result: prose for the human, then one JSON line
+ * for the model. Both, because prose alone invites the model to paraphrase a
+ * refusal into a success, and JSON alone gives the user nothing to read.
+ * Same shape as `enroll_file`'s, so the two tools read alike in a transcript.
+ */
+export function toolResult(answer) {
+    const payload = { outcome: answer.outcome, ...(answer.detail ?? {}) };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${answer.text}\n${JSON.stringify(payload)}`,
+            },
+        ],
+        ...(answer.isError ? { isError: true } : {}),
+    };
+}
+/**
+ * How one candidate reads to a user, without its identifiers.
+ *
+ * ENG-2787 — the enrolment marking comes FIRST, and that ordering is the whole
+ * fix. The flag was already on the wire; the client truncated it off the END of
+ * the row, so ten candidates rendered as
+ * `RE_Forecast.xlsx · /drives/b!YmtA8jQX3OSHJRQ88O…` and the tool
+ * description's promise that "each candidate comes back marked as already in
+ * Rockhopper or not" was true of the payload and false of the screen. A marking
+ * whose position depends on the length of a customer's file name is not
+ * visible; one at position zero always is.
+ *
+ * `lastModifiedAt` and `parentPath` are dropped for the same reason they did
+ * harm: an ISO timestamp and a raw `/drives/b!…` id are forty characters
+ * nobody can read, sitting in front of the one phrase that decides whether
+ * this row is worth picking. Both still appear in the prompt's own message,
+ * which wraps instead of truncating.
+ */
+export function candidateLabel(candidate) {
+    return `${ENROLLMENT_NOTE[candidate.enrollmentState]} · ${candidate.name}`;
+}
+/**
+ * The same facts MINUS the name, for the places that print the name already.
+ *
+ * A picker row has to stand alone, so {@link candidateLabel} repeats the name;
+ * prose that has just written `**Becklar_RMR_Model.xlsx**` has not.
+ */
+function candidateNote(candidate) {
+    return [ENROLLMENT_NOTE[candidate.enrollmentState]]
+        .concat(candidate.parentPath ?? [])
+        .join(' · ');
+}
+/**
+ * What each enrolment state MEANS to the person choosing, in their words.
+ *
+ * `hidden` is spelled out rather than folded into "already added" because the
+ * two lead to different conversations: one is done, and the other needs the
+ * user to say whether they want a file they removed put back. Collapsing them
+ * is the ENG-1647 answer — "already enrolled" about a file the user cannot see.
+ */
+const ENROLLMENT_NOTE = {
+    enrolled: 'already in Rockhopper',
+    hidden: 'previously removed from Rockhopper',
+    not_enrolled: 'not in Rockhopper yet',
+};
+/** The numbered list the user picks from, and the model quotes back. */
+export function renderCandidates(candidates) {
+    return candidates
+        .map((c, index) => `${index + 1}. **${c.name}** — ${candidateNote(c)}`)
+        .join('\n');
+}
+/** The question the model puts to the user when no richer lane exists. */
+export function confirmationPrompt(candidates, token) {
+    return (`Found ${candidates.length} possible file(s). ` +
+        'DO NOT enroll any of these yet.\n\n' +
+        `${renderCandidates(candidates)}\n\n` +
+        'Ask the user which one they meant — quote the names, do not choose for ' +
+        'them. When they answer, call `search_drive_files` again with ' +
+        `confirm_index: <their number> and confirm_token: "${token}", or ` +
+        'confirm_index: 0 if none of these is the file.');
+}
+/**
+ * What the user READS before they touch anything (ENG-2789).
+ *
+ * The candidates are written into the message because the message is the only
+ * part of an elicitation this client renders unprompted. The prompt David
+ * photographed on 2026-08-19 showed exactly two things on screen — this
+ * sentence, and a field collapsed to the words `not set` — while ten workbooks
+ * sat behind a `→` documented in a footnote under the buttons. Three
+ * consecutive real attempts returned `declined` from a prompt whose options
+ * were never on screen.
+ *
+ * So the list is prose now, and the field is a way to answer a question the
+ * user has already read rather than the only place the question exists.
+ */
+function pickerMessage(candidates) {
+    return (`Which of these ${candidates.length} workbooks did you mean? ` +
+        'Rockhopper will not add anything until you say.\n\n' +
+        `${renderCandidates(candidates)}\n\n` +
+        'Pick one by number in the File field below.\n\n' +
+        'If none of them is the right file, you can paste the workbook\'s own ' +
+        'link instead: open it in your browser and copy the address from the bar ' +
+        'into the Link field. That names the file exactly, so nothing has to be ' +
+        'guessed from its name.');
+}
+/**
+ * The elicitation form both richer lanes send.
+ *
+ * NOTHING IS REQUIRED, and that is deliberate (ENG-2789). A required `choice`
+ * is what turned an unreadable prompt into a trap: the only visible buttons
+ * were Accept and Decline, and Accept was REFUSED because the invisible field
+ * was unset, leaving Decline as the sole affordance that did anything. An
+ * unanswered form now comes back as `dismissed` — a state the tool can name
+ * and act on — instead of a button the user is herded into pressing.
+ */
+export function confirmationForm(candidates) {
+    return {
+        message: pickerMessage(candidates),
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                // The values are POSITIONS, never identifiers. A client (or anything
+                // steering it) can only send back a number, and a number that does not
+                // index a set this session offered resolves to nothing.
+                choice: {
+                    type: 'string',
+                    enum: [
+                        ...candidates.map((_, index) => String(index + 1)),
+                        DECLINE_CHOICE,
+                    ],
+                    // Numbered so a row the client truncates is still resolvable
+                    // against the list in the message above it.
+                    enumNames: [
+                        ...candidates.map((c, index) => `${index + 1}. ${candidateLabel(c)}`),
+                        'None of these',
+                    ],
+                    title: 'File',
+                    description: 'The workbook to add to Rockhopper.',
+                },
+                // ENG-2784. The link route used to be spoken only to the MODEL, in the
+                // text returned after the user had already given up: whether they ever
+                // heard it depended on the assistant choosing to relay it. A recovery
+                // path that needs the agent to speak IS the defect, so it is a field on
+                // the prompt the user is already looking at.
+                link: {
+                    type: 'string',
+                    title: 'Link',
+                    description: 'Or paste the workbook\'s address here — open it in your browser ' +
+                        'and copy the address from the bar.',
+                },
+            },
+        },
+    };
+}
+/** The answer that means "none of these" rather than a position. */
+export const DECLINE_CHOICE = 'none';
+/**
+ * The answer once a specific candidate has been confirmed by a human.
+ *
+ * It hands over identifiers and stops. Enrolling here would mean a second copy
+ * of `enroll_file`'s logic — the share_with question, the hidden-file restore
+ * — living in a read tool, and two copies of a rule is how the two answers
+ * start to differ.
+ */
+export function confirmedAnswer(candidate) {
+    if (!candidate.driveMsId) {
+        return toolResult({
+            outcome: 'unknown_candidate',
+            isError: true,
+            text: `Microsoft did not say which drive "${candidate.name}" lives in, so ` +
+                'it cannot be added from the search result. Ask the user to open the ' +
+                'workbook and paste the address from their browser bar, then call ' +
+                '`enroll_file` with that `url`.',
+        });
+    }
+    return toolResult({
+        outcome: 'confirmed',
+        text: `The user confirmed "${candidate.name}" (${candidateNote(candidate)}). ` +
+            'Now call `enroll_file` with the `driveMsId` and `msId` below. ' +
+            '`enroll_file` will ask who may see the file — put that question to the ' +
+            'user too, and never answer it yourself.',
+        detail: {
+            name: candidate.name,
+            driveMsId: candidate.driveMsId,
+            msId: candidate.msId,
+            enrollmentState: candidate.enrollmentState,
+        },
+    });
+}
+/** The answer when the user was asked and said none of these. */
+export function declinedAnswer() {
+    return toolResult({
+        outcome: 'declined',
+        text: 'The user looked at the candidates and said none of them is the file, ' +
+            'so nothing was added. Ask them to describe the workbook differently ' +
+            'and search again, or to paste its SharePoint or OneDrive link for ' +
+            '`enroll_file`.',
+    });
+}
+/**
+ * The answer when the prompt closed without the user answering it (ENG-2789).
+ *
+ * Its own outcome and not a flavour of `declined`, because the two say opposite
+ * things about what the user knows. `declined` means they read ten workbooks
+ * and none was theirs — searching again with a different word is the right next
+ * move. This means they never told us anything, and the honest next move is to
+ * put the same list to them in the conversation, where it cannot be collapsed.
+ * Folding them together is what let three unreadable prompts report themselves
+ * as a decision the user had made.
+ */
+export function dismissedAnswer(candidates) {
+    const list = candidates?.length
+        ? `\n\n${renderCandidates(candidates)}\n\n`
+        : ' ';
+    return toolResult({
+        outcome: 'dismissed',
+        text: 'The user closed the file picker without answering it, so nothing was ' +
+            'added and they have told us nothing about which file they meant. Do ' +
+            'NOT treat this as a rejection and do not search again yet.' +
+            list +
+            'List these candidates in the conversation, ask which one they meant, ' +
+            'and say they can paste the workbook\'s OneDrive or SharePoint link ' +
+            'instead if none is right.',
+    });
+}
+/**
+ * The answer when the user pasted a link rather than picking a row (ENG-2784).
+ *
+ * The URL is the user's own typing, from a field only they can fill — it is
+ * not a model-chosen argument, and it is handed straight to `enroll_file`,
+ * which is the tool that resolves and validates it. Nothing here tries to
+ * parse it: `enroll_file`'s own description calls a pasted address "the only
+ * input that names one specific file with no guessing", and re-deriving that
+ * judgement in a second place is how two answers start to differ.
+ */
+export function linkSuppliedAnswer(url) {
+    return toolResult({
+        outcome: 'link_supplied',
+        text: 'The user did not pick from the list. They pasted the workbook\'s own ' +
+            'address instead, which names the file exactly. Call `enroll_file` with ' +
+            'the `url` below and nothing else — no `driveMsId`, no `msId`. ' +
+            '`enroll_file` will ask who may see the file; put that question to the ' +
+            'user too, and never answer it yourself.',
+        detail: { url },
+    });
+}
+/**
+ * A pasted value this tool will pass on, or `null`.
+ *
+ * The only check is that it is an http(s) address, and it exists so an empty
+ * box or a stray keystroke does not get announced to the model as "the user
+ * gave us the file". Anything further — which tenant, which drive, whether the
+ * file exists — is `enroll_file`'s to decide against Microsoft, not this
+ * tool's to guess from a string.
+ */
+export function usableLink(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const { protocol } = new URL(trimmed);
+        return protocol === 'https:' || protocol === 'http:' ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The answer when a confirmation names something this session never offered. */
+export function unknownCandidateAnswer() {
+    return toolResult({
+        outcome: 'unknown_candidate',
+        isError: true,
+        text: 'That pick does not match any file this search offered, so nothing was ' +
+            'added. Run `search_drive_files` again and confirm against the list it ' +
+            'returns. Never enroll a file that did not come back from a search.',
+    });
+}
+/** Told to the model when the session has searched as much as it may. */
+export const BUDGET_EXHAUSTED_TEXT = `This session has used all ${DRIVE_SEARCH_SESSION_BUDGET} of its file ` +
+    'searches. This is a fixed limit and waiting does not restore it. Stop ' +
+    "searching and ask the user to paste the workbook's SharePoint or OneDrive " +
+    'link, then call `enroll_file` with that link. Nothing was searched.';
+/** Told to the model when the user has no delegated Microsoft grant. */
+export function connectPrompt(authorizeUrl, expiresAt) {
+    return ('Rockhopper cannot look at this user\'s Microsoft files until they ' +
+        'connect their Microsoft account. Give them this link to open ' +
+        `themselves — it expires at ${expiresAt}:\n\n${authorizeUrl}\n\n` +
+        'Rockhopper asks only to READ their files. Once they have approved, call ' +
+        '`microsoft_link_status` to confirm, then search again. Do not compose a ' +
+        'sign-in link yourself; this one is the only valid one.');
+}
+//# sourceMappingURL=drive-search.contract.js.map

package/dist/tools/drive-search.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-search.contract.js","sourceRoot":"","sources":["../../src/tools/drive-search.contract.ts"],"names":[],"mappings":"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"}

package/dist/tools/drive-search.d.ts

@@ -0,0 +1,31 @@
+import { type InputRequiredResult, type McpServer } from '@modelcontextprotocol/server';
+import type { ApiClient } from '../api-client.js';
+import { CandidateRegistry, SearchBudget } from '../drive-search.js';
+/**
+ * ENG-2204 (SP08) — the half of ENG-1647 that ENG-2200 did not fix.
+ *
+ * ENG-2200 built the enroll tool the customer could not find. This finds the
+ * FILE: a workbook Rockhopper has never seen, in the user's own OneDrive or
+ * SharePoint, confirmed with them before anything is written.
+ *
+ * Three things here are load-bearing and none is obvious from the happy path:
+ *
+ * 1. **The search set IS the permission trim.** Every candidate came back from
+ *    a delegated Microsoft call made as this user. Nothing is added to it,
+ *    nothing is inferred into it, and no file outside it is ever offered.
+ * 2. **A confirmation resolves against SERVER memory, never against what the
+ *    client sent.** The confirmation carries a position and a nonce; the file
+ *    it names is looked up in the set this session actually returned. A model
+ *    that has read a hostile file name cannot conjure a `driveMsId` and have
+ *    the tool bless it.
+ * 3. **The budget is claimed BEFORE the network call.** A cap that discards an
+ *    answer already fetched has not capped anything — the enumeration already
+ *    happened, and Microsoft already answered it.
+ */
+export declare function registerDriveSearchTool(server: McpServer, api: ApiClient, session?: {
+    budget?: SearchBudget;
+    registry?: CandidateRegistry;
+}): void;
+/** Re-exported so `InputRequiredResult` is nameable where the tool is used. */
+export type { InputRequiredResult };
+//# sourceMappingURL=drive-search.d.ts.map

package/dist/tools/drive-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-search.d.ts","sourceRoot":"","sources":["../../src/tools/drive-search.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,SAAS,EAEf,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,YAAY,EAOb,MAAM,oBAAoB,CAAC;AAyB5B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CAAE,GAChE,IAAI,CAwMN;AAiCD,+EAA+E;AAC/E,YAAY,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/tools/drive-search.js

@@ -0,0 +1,236 @@
+import { randomUUID } from 'node:crypto';
+import { inputRequired, inputResponse, } from '@modelcontextprotocol/server';
+import { CandidateRegistry, SearchBudget, classifyDriveSearchFailure, ADMIN_CONSENT_TEXT, isAdminConsentRequired, isNoDelegatedToken, toCandidate, } from '../drive-search.js';
+import { log } from '../logger.js';
+import { BUDGET_EXHAUSTED_TEXT, DECLINE_CHOICE, DRIVE_SEARCH_ANNOTATIONS, DRIVE_SEARCH_DESCRIPTION, DRIVE_SEARCH_INPUT_SCHEMA, confirmationForm, confirmationPrompt, confirmedAnswer, connectPrompt, declinedAnswer, dismissedAnswer, linkSuppliedAnswer, toolResult, unknownCandidateAnswer, usableLink, } from './drive-search.contract.js';
+import { CONFIRM_KEY, readRequestState, selectLane, } from './drive-search-lanes.js';
+/**
+ * ENG-2204 (SP08) — the half of ENG-1647 that ENG-2200 did not fix.
+ *
+ * ENG-2200 built the enroll tool the customer could not find. This finds the
+ * FILE: a workbook Rockhopper has never seen, in the user's own OneDrive or
+ * SharePoint, confirmed with them before anything is written.
+ *
+ * Three things here are load-bearing and none is obvious from the happy path:
+ *
+ * 1. **The search set IS the permission trim.** Every candidate came back from
+ *    a delegated Microsoft call made as this user. Nothing is added to it,
+ *    nothing is inferred into it, and no file outside it is ever offered.
+ * 2. **A confirmation resolves against SERVER memory, never against what the
+ *    client sent.** The confirmation carries a position and a nonce; the file
+ *    it names is looked up in the set this session actually returned. A model
+ *    that has read a hostile file name cannot conjure a `driveMsId` and have
+ *    the tool bless it.
+ * 3. **The budget is claimed BEFORE the network call.** A cap that discards an
+ *    answer already fetched has not capped anything — the enumeration already
+ *    happened, and Microsoft already answered it.
+ */
+export function registerDriveSearchTool(server, api, session) {
+    // Per-server, never per-module: two servers in one process (a test file, a
+    // gateway serving two sessions) must not share a ceiling, and a module-level
+    // counter is exactly the shape that silently does.
+    const budget = session?.budget ?? new SearchBudget();
+    const registry = session?.registry ?? new CandidateRegistry();
+    /**
+     * Resolve a (nonce, position) pair against what this session offered.
+     *
+     * Position, never identifier — the only thing a client can send is a number,
+     * and a number that does not index a set this session returned resolves to
+     * nothing. `0` and the elicitation form's "none of these" are the same
+     * answer: the user was asked and chose no file.
+     */
+    function resolvePick(nonce, choice) {
+        if (choice === DECLINE_CHOICE || choice === 0)
+            return declinedAnswer();
+        if (!nonce)
+            return unknownCandidateAnswer();
+        const position = typeof choice === 'number' ? choice : Number(choice);
+        const candidate = registry.resolve(nonce, position - 1);
+        return candidate ? confirmedAnswer(candidate) : unknownCandidateAnswer();
+    }
+    /** The set this session offered under `nonce`, for re-asking in prose. */
+    function offered(nonce) {
+        return (nonce ? registry.recall(nonce) : null) ?? undefined;
+    }
+    /**
+     * Read a filled-in elicitation form.
+     *
+     * Order matters and it is not the obvious one: a pasted LINK beats a picked
+     * row. The link is the user typing the file's own address, which
+     * `enroll_file` calls the only input that names one file with no guessing,
+     * while a row is a position in a list a search produced. If someone took the
+     * trouble to paste an address, that is the file they mean.
+     *
+     * An EMPTY form is `dismissed`, never `declined`. Nothing is required any
+     * more (ENG-2789), so Accept with nothing filled in is a reachable state, and
+     * it means the user answered nothing — which is a different fact from "none
+     * of these is my file" and leads to a different next move.
+     */
+    function resolveForm(nonce, content) {
+        const filled = content;
+        const link = usableLink(filled?.link);
+        if (link)
+            return linkSuppliedAnswer(link);
+        const choice = filled?.choice;
+        if (choice === undefined || choice === '')
+            return dismissedAnswer(offered(nonce));
+        return resolvePick(nonce, choice);
+    }
+    /**
+     * Put the question through the best lane this request can reach.
+     *
+     * Lane 2 is awaited INSIDE the call and lane 3 returns out of it; both end
+     * at the same three answers, and lane 1 hands the question to the model.
+     */
+    async function ask(ctx, candidates, nonce) {
+        const lane = selectLane(ctx, server.server?.getClientCapabilities?.());
+        const form = confirmationForm(candidates);
+        if (lane === 'input_required') {
+            return inputRequired({
+                inputRequests: { [CONFIRM_KEY]: inputRequired.elicit(form) },
+                requestState: nonce,
+            });
+        }
+        if (lane === 'elicitation' && ctx?.mcpReq?.elicitInput) {
+            try {
+                const answer = await ctx.mcpReq.elicitInput({ ...form, mode: 'form' });
+                if (answer?.action === 'accept')
+                    return resolveForm(nonce, answer.content);
+                // Declined or cancelled. Neither is an error — a person is allowed to
+                // close a prompt — and neither is `declined` either: the user pressed a
+                // button, they did not tell us anything about these ten files. Saying
+                // "the user rejected the candidates" here is the ENG-2789 failure, and
+                // it is how three unreadable prompts reported themselves as decisions.
+                return dismissedAnswer(candidates);
+            }
+            catch {
+                // The client advertised elicitation and could not deliver it. Falling
+                // back to the universal lane keeps the question answerable instead of
+                // turning a capability mismatch into a dead end.
+            }
+        }
+        return toolResult({
+            outcome: 'candidates',
+            text: confirmationPrompt(candidates, nonce),
+            detail: { confirmToken: nonce, candidateCount: candidates.length },
+        });
+    }
+    server.registerTool('search_drive_files', {
+        title: "Find a File in the User's Microsoft Drive",
+        description: DRIVE_SEARCH_DESCRIPTION,
+        inputSchema: DRIVE_SEARCH_INPUT_SCHEMA,
+        annotations: DRIVE_SEARCH_ANNOTATIONS,
+    }, async ({ query, scope, limit, confirm_index, confirm_token }, ctx) => {
+        // A retried multi-round-trip request arrives with the user's answer
+        // embedded. It is checked FIRST and it never searches again: re-running
+        // the query on a retry would spend a second unit of budget and could
+        // return a different set than the one the user was looking at.
+        const embedded = inputResponse(ctx?.mcpReq?.inputResponses, CONFIRM_KEY);
+        if (embedded.kind === 'elicit') {
+            const answered = readRequestState(ctx);
+            if (embedded.action !== 'accept')
+                return dismissedAnswer(offered(answered));
+            return resolveForm(answered, embedded.content);
+        }
+        // The universal lane's confirmation: the model relaying a number the
+        // user said out loud. Same resolution, same server-side lookup.
+        if (confirm_index !== undefined || confirm_token !== undefined) {
+            return resolvePick(confirm_token ?? null, confirm_index ?? NaN);
+        }
+        if (!budget.claim()) {
+            log.warn({
+                event: 'drive_search_capped',
+                searches: budget.spent,
+                budget: budget.ceiling,
+            }, 'drive_search_capped');
+            return toolResult({
+                outcome: 'search_limit_reached',
+                isError: true,
+                text: BUDGET_EXHAUSTED_TEXT,
+                detail: { searchesUsed: budget.spent, searchBudget: budget.ceiling },
+            });
+        }
+        let items;
+        try {
+            const answer = await api.searchDriveFiles({
+                q: query,
+                scope,
+                limit: limit ?? 10,
+            });
+            items = answer.items;
+        }
+        catch (error) {
+            // ORDER MATTERS. Both refusals arrive as `NO_DELEGATED_TOKEN`, so
+            // checking "not connected" first would swallow the administrator
+            // case and hand the user a connect link that Microsoft refuses —
+            // which returns them here, with the same link, forever (ENG-2614).
+            if (isAdminConsentRequired(error)) {
+                return toolResult({
+                    outcome: 'microsoft_admin_approval_required',
+                    text: ADMIN_CONSENT_TEXT,
+                    isError: true,
+                });
+            }
+            if (isNoDelegatedToken(error))
+                return connectAnswer(api);
+            const { outcome, message } = classifyDriveSearchFailure(error);
+            return toolResult({ outcome, text: message, isError: true });
+        }
+        // Mirrors the backend's own discovery log (`[DRIVE-SEARCH]`): the query
+        // LENGTH, never its text, and a count, never a name. Enough to tell an
+        // empty probe from a real one while reading an incident, and none of the
+        // customer's content.
+        log.info({
+            event: 'drive_search',
+            scope: scope ?? 'search',
+            queryLength: query?.length ?? 0,
+            results: items.length,
+            searches: budget.spent,
+            budget: budget.ceiling,
+        }, 'drive_search');
+        if (items.length === 0) {
+            return toolResult({
+                outcome: 'no_matches',
+                text: 'Microsoft returned no spreadsheets matching that. The search ran ' +
+                    'and came back empty — it did not fail. Ask the user to try a ' +
+                    'different part of the name, or call again with scope="recent" ' +
+                    'to list what they have worked on lately.',
+            });
+        }
+        const candidates = items.map(toCandidate);
+        const nonce = randomUUID();
+        registry.remember(nonce, candidates);
+        return ask(ctx, candidates, nonce);
+    });
+}
+/**
+ * The `NO_DELEGATED_TOKEN` answer: a link the BACKEND built.
+ *
+ * The tool takes no authorize URL, no redirect and no client id, and it never
+ * asks the model to compose one. An MCP tool's arguments are chosen by a model
+ * reading content it did not author, so a caller-supplied sign-in link is a
+ * consent-phishing lever — the user would see a genuine Microsoft consent
+ * screen the whole way while approving somebody else's application. Same
+ * reasoning as `connect_microsoft`, which is where this link comes from.
+ */
+async function connectAnswer(api) {
+    try {
+        const handoff = await api.beginMicrosoftConnect();
+        return toolResult({
+            outcome: 'microsoft_not_connected',
+            text: connectPrompt(handoff.authorizeUrl, handoff.expiresAt),
+            detail: { authorizeUrl: handoff.authorizeUrl },
+        });
+    }
+    catch {
+        return toolResult({
+            outcome: 'microsoft_not_connected',
+            isError: true,
+            text: 'This user has no connected Microsoft account, and Rockhopper could ' +
+                'not produce a sign-in link just now. Ask them to run ' +
+                '`connect_microsoft`, or to paste the workbook link for `enroll_file`. ' +
+                'Do not compose a Microsoft sign-in link yourself.',
+        });
+    }
+}
+//# sourceMappingURL=drive-search.js.map