@descryy/mcp 0.11.1 → 0.11.3

package/dist/tools/prove-reach.js

@@ -0,0 +1,286 @@
+/**
+ * `prove_reach` — closes RG-10's loop. "Rename that column and these screens go blank" is
+ * three claims, made in order, each on evidence the last one didn't have:
+ *
+ *  1. **Predict** — from a node (typically a `DATABASE_COLUMN`), walk `reachablePages`
+ *     (`@descryy/core`) to whatever `PAGE`/`COMPONENT` nodes the data reaches, and propose a
+ *     navigate-only journey to them, exactly as `predict_reach` already does — this tool calls
+ *     the identical pure planner (`../planner/predict-then-propose.ts#predictThenPropose`), never
+ *     a second implementation. Nothing runs yet: a caller who has not yet approved the drive gets
+ *     back the prediction, the proposal and a confirmation token, and this tool's `describeAction`
+ *     is what mints that token — the dispatcher (`../action-handshake.ts`) never calls `run` at
+ *     all until the second call arrives, so "nothing runs" is structural, not a promise this file
+ *     keeps by convention.
+ *  2. **Approve and drive** — a second call, `confirmToken` in hand, drives the exact proposed
+ *     scenario for real via `../browser/scenario-runner.ts#replayScenario`, in a browser session
+ *     the caller already started and consented (`browser({ verb: "start_session" })`). Never boots an app,
+ *     never widens the journey beyond what was proposed: the scenario driven is the one frozen at
+ *     mint time, byte for byte.
+ *  3. **Prove** — correlates which of the predicted pages the drive's own step results actually
+ *     reached (`../planner/predict-then-propose.ts#visitedPageIds` + `#proveOrDisprove`) — a page
+ *     counts as visited only when the exact navigate URL built from its own route name replayed
+ *     as `"ran"`, never a guess from proximity.
+ *  4. **Conclude** — routes the real, walked graph path (`#combinedGraphPath`, never a synthesised
+ *     one) and the runtime evidence the drive actually observed (console errors, failed requests)
+ *     through the same finding funnel `draw_conclusion` uses — `reportCategory`, `@descryy/ir`,
+ *     `packages/ir/src/finding.ts` — so the reply carries a governed category, not a raw tally the
+ *     caller has to interpret. A drive that reached every predicted page cleanly, with nothing
+ *     wrong observed, reports so honestly: `hasRuntimeEvidence` is false and the category is
+ *     `unconfirmed` by G3's own precondition, not "confirmed" because the pages loaded.
+ *
+ * **class: "action"**, gated only when there is something to drive: a node that reaches nothing,
+ * or reaches only non-path-shaped pages/components with no navigate step to propose, has nothing
+ * to approve, so `describeAction` returns `undefined` and this reports the prediction immediately
+ * — same discipline as `predict_reach`'s own empty case, never a gate for its own sake.
+ */
+import { directMechanismEvidence, evidencePrecondition, humanAssertedOnPath, independentSignalTypes, minimumResolution, reportCategory, } from "@descryy/ir";
+import { combinedGraphPath, predictThenPropose, proveOrDisprove, visitedPageIds, } from "../planner/predict-then-propose.js";
+import { browserAnswer, mutationRefusal, useSession, withinConsent } from "../browser/tool-support.js";
+import { mutates, replayScenario } from "../browser/scenario-runner.js";
+import { answer, briefNode, requiredString, optionalString, ToolInputError, } from "./kit.js";
+import { resolveOneNode } from "./lookup.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        nodeId: { type: "string", description: "Graph node id to predict reach from — typically a DATABASE_COLUMN." },
+        symbol: {
+            type: "string",
+            description: "Symbol name to start from, when you do not have a node id. Ambiguity is reported rather than guessed at — narrow it with \"file\".",
+        },
+        file: { type: "string", description: "Repository-relative path, to disambiguate \"symbol\" or to start from a file." },
+        targetUrl: {
+            type: "string",
+            description: "REQUIRED. The running application's base URL — the same origin the browser session named in \"sessionId\" was consented for.",
+        },
+        sessionId: {
+            type: "string",
+            description: "REQUIRED. A browser session id from browser({ verb: \"start_session\" }), already consented for targetUrl's origin. " +
+                "This tool never starts a browser itself and never widens consent beyond that session's own.",
+        },
+        name: { type: "string", description: "What to call the proposed scenario. Defaults to \"predicted-journey\"." },
+        confirmToken: {
+            type: "string",
+            description: "The token returned by a previous call. The first call predicts and proposes but drives nothing; call " +
+                "again with \"confirmToken\" to actually drive the proposed journey and correlate the result — with " +
+                "the arguments frozen when the token was minted, never whatever the confirming call supplies, so " +
+                "changing nodeId, targetUrl, sessionId or any other field on the confirming call is discarded rather " +
+                "than applied, and the reply discloses that it was; call again without confirmToken for a fresh token " +
+                "if something needs to change. A token is single-use, expires, and is only valid for this tool.",
+        },
+    },
+    required: ["targetUrl", "sessionId"],
+    additionalProperties: false,
+};
+/** Resolves the start node and computes the identical prediction `predict_reach` would, from the
+ *  same pure planner. Shared by `describeAction` and `run` so the two can never compute two
+ *  different predictions for what a caller reads as one call. */
+function prepare(args, ctx) {
+    const nodeIdArg = optionalString(args, "nodeId");
+    const symbol = optionalString(args, "symbol");
+    const file = optionalString(args, "file");
+    const targetUrl = requiredString(args, "targetUrl");
+    const sessionId = requiredString(args, "sessionId");
+    const name = optionalString(args, "name") ?? "predicted-journey";
+    if (nodeIdArg === undefined && symbol === undefined && file === undefined) {
+        throw new ToolInputError('give one of "nodeId", "symbol" or "file"');
+    }
+    const found = resolveOneNode(ctx.session, { nodeId: nodeIdArg, symbol, file });
+    if (found.node === null) {
+        return { ok: false, candidates: found.candidates.map(briefNode), headline: found.headline, notes: found.notes };
+    }
+    const provider = ctx.session.provider();
+    const base = provider.baseStamp();
+    const predicted = predictThenPropose(provider, found.node.id, { targetUrl, name, savedAtCommit: base.commitSha ?? "" });
+    return { ok: true, value: { node: found.node, predicted, targetUrl, sessionId } };
+}
+function drivable(predicted) {
+    return predicted.proposal !== null && predicted.proposal.scenario.steps.length > 0;
+}
+function emptyReport(node, predicted) {
+    return {
+        from: node === null ? { id: "", type: "", name: "", resolution: 0 } : briefNode(node),
+        reachedPages: predicted === null ? [] : predicted.reachedPages.map((n) => ({ id: n.id, type: n.type, name: n.name, resolution: 0 })),
+        proposal: predicted?.proposal === null || predicted === null
+            ? null
+            : { scenario: predicted.proposal.scenario, reachedNotProposed: predicted.proposal.reachedNotProposed },
+        drive: null,
+        proof: null,
+        conclusion: null,
+    };
+}
+async function describeAction(args, ctx) {
+    const prep = prepare(args, ctx);
+    if (!prep.ok)
+        return undefined; // nothing resolvable — run() reports the refusal immediately, no gate
+    const { node, predicted, sessionId } = prep.value;
+    if (!drivable(predicted))
+        return undefined; // nothing to drive — run() reports the prediction alone
+    const steps = predicted.proposal.scenario.steps.length;
+    const pageNames = predicted.reachedPages.map((p) => p.name);
+    return (`drive ${steps} navigate step(s) in browser session "${sessionId}", toward ${predicted.reachedPages.length} ` +
+        `predicted page/component reached from ${node.name} (${pageNames.slice(0, 5).join(", ")}${pageNames.length > 5 ? ", …" : ""}), ` +
+        "then correlate what the drive actually reached — and any console error or failed request observed while " +
+        "it ran — into a governed finding via the same gate draw_conclusion uses.");
+}
+async function run(args, ctx) {
+    const prep = prepare(args, ctx);
+    const base = ctx.session.provider().baseStamp();
+    if (!prep.ok) {
+        return {
+            result: { data: { candidates: prep.candidates }, stamp: { ...base, resolutionFloor: 0 }, truncated: false, notes: prep.notes },
+            nameLevel: true,
+            state: "refused",
+            headline: prep.headline,
+        };
+    }
+    const { node, predicted, targetUrl, sessionId } = prep.value;
+    const notes = [...predicted.notes];
+    if (!drivable(predicted)) {
+        return answer({
+            headline: predicted.proposal === null
+                ? `${node.name} reaches no PAGE or COMPONENT this graph can walk to. Not a claim it reaches none in the running application — see notes.`
+                : `${node.name} reaches ${predicted.reachedPages.length} page/component, but none has a path-shaped route name — nothing to drive or prove.`,
+            state: "empty",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes,
+            data: emptyReport(node, predicted),
+        });
+    }
+    // A non-empty proposal only reaches this line once the two-call handshake has already
+    // approved it — `describeAction` above gates every other case. Drive it, exactly as proposed.
+    const scenario = predicted.proposal.scenario;
+    const found = await useSession(ctx.session.browserSessions(), sessionId);
+    if (!found.ok) {
+        return browserAnswer({
+            ctx,
+            state: found.dead.state,
+            headline: found.dead.headline,
+            notes: [...notes, ...found.dead.notes],
+            data: emptyReport(node, predicted),
+        });
+    }
+    const { entry } = found;
+    if (!withinConsent(entry, targetUrl)) {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `The predicted journey targets ${targetUrl}, outside this session's consent.`,
+            notes: [
+                ...notes,
+                `This session was consented for ${entry.consentedOrigin} only. Start a session against that origin to drive this prediction.`,
+            ],
+            data: emptyReport(node, predicted),
+        });
+    }
+    const refusedForSafety = mutationRefusal(entry);
+    if (refusedForSafety !== null && mutates(scenario)) {
+        // Dead in practice — proposeJourney only ever emits navigate steps — kept for the day a
+        // future planner proposes more, so a readOnly profile still refuses rather than driving.
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `${entry.profile?.name ?? "This environment"} is read-only.`,
+            notes: [...notes, refusedForSafety],
+            data: emptyReport(node, predicted),
+        });
+    }
+    if (entry.page.currentUrl() !== scenario.targetUrl) {
+        await entry.page.navigate(scenario.targetUrl);
+    }
+    ctx.progress(`Driving the predicted journey from ${node.name}`);
+    const replay = await replayScenario(ctx, ctx.session.browserSessions(), sessionId, scenario, process.env, ctx.session.credentialStore);
+    const visited = visitedPageIds(predicted, targetUrl, replay.steps.map((s) => ({ url: s.url, status: s.status })));
+    const proof = proveOrDisprove(predicted, { visitedNodeIds: visited });
+    // The hypothesis's own structural mechanism — every page the walk predicted, not only the ones
+    // this one drive happened to confirm — so the finding's graphPath describes what the graph
+    // claims propagates, and the runtime evidence below is what says whether it broke anything.
+    const graphPath = combinedGraphPath(predicted, predicted.reachedPages.map((p) => p.id));
+    const runtimeEvidence = [
+        ...replay.evidence.consoleErrors.map((e) => ({ signal: "browser-console", detail: e.text, directMechanism: false })),
+        ...replay.evidence.failedRequests.map((r) => {
+            const reached = replay.graph.reached.find((n) => n.via.method === r.method && n.via.url === r.url);
+            return {
+                signal: "network",
+                detail: `${r.method} ${r.url} failed${r.status === null ? "" : ` (status ${r.status})`}`,
+                ...(reached === undefined ? {} : { nodeId: reached.nodeId, directMechanism: reached.nodeId === node.id }),
+            };
+        }),
+    ];
+    const hasRuntimeEvidence = evidencePrecondition(runtimeEvidence);
+    const resolution = minimumResolution(graphPath);
+    const humanAsserted = humanAssertedOnPath(graphPath);
+    const eSignals = independentSignalTypes(runtimeEvidence);
+    const mMechanism = directMechanismEvidence(runtimeEvidence, node.id);
+    const gated = reportCategory({
+        hasRuntimeEvidence,
+        independentSignalTypes: eSignals,
+        directMechanismEvidence: mMechanism,
+        resolution,
+        // Name-level throughout — a route path is read off a node's qualified name, same as
+        // predict_reach's own cap, never a type-checked shape.
+        nameLevel: true,
+        humanAsserted,
+    });
+    const proofNotes = [
+        `Drove the proposed journey for real: ${proof.proven.length} of ${predicted.reachedPages.length} predicted ` +
+            `page(s)/component(s) confirmed reached, ${proof.disproven.length} not reached by this drive.`,
+        hasRuntimeEvidence
+            ? `${runtimeEvidence.length} runtime observation(s) fed the gate — ${replay.evidence.consoleErrors.length} console error(s), ` +
+                `${replay.evidence.failedRequests.length} failed request(s).`
+            : "No console error or failed request was observed during this drive, so G3's evidence precondition fails " +
+                "and this reports unconfirmed regardless of the graph path — reaching a page cleanly is not evidence it broke.",
+    ];
+    return browserAnswer({
+        ctx,
+        headline: `"${node.name}": ${gated.category} (reliability ${gated.reliabilityClass}). Drove ${scenario.steps.length} step(s), ` +
+            `${proof.proven.length} predicted page(s) confirmed reached, ${proof.disproven.length} not.`,
+        notes: [...notes, ...proofNotes, ...replay.notes],
+        data: {
+            from: briefNode(node),
+            reachedPages: predicted.reachedPages.map((n) => ({ id: n.id, type: n.type, name: n.name, resolution: 0 })),
+            proposal: { scenario: predicted.proposal.scenario, reachedNotProposed: predicted.proposal.reachedNotProposed },
+            drive: {
+                outcome: replay.outcome,
+                steps: replay.steps.map((s) => ({ url: s.url, status: s.status })),
+                consoleErrorCount: replay.evidence.consoleErrors.length,
+                failedRequestCount: replay.evidence.failedRequests.length,
+            },
+            proof,
+            conclusion: {
+                failurePoint: node.id,
+                category: gated.category,
+                reliabilityClass: gated.reliabilityClass,
+                resolution,
+                independentSignalTypes: eSignals,
+                directMechanismEvidence: mMechanism,
+                hasRuntimeEvidence,
+            },
+        },
+    });
+}
+export const proveReachTool = {
+    name: "prove_reach",
+    class: "action",
+    tier: "conclusion",
+    version: "1.0.0",
+    title: "Predict which pages a data change reaches, then drive a real browser to prove or disprove it",
+    description: "RG-10's full loop: predicts which PAGE/COMPONENT nodes a node (typically a DATABASE_COLUMN) reaches, " +
+        "exactly as predict_reach does, and proposes a navigate-only journey. The first call performs nothing " +
+        "and returns a confirmation token; call again with confirmToken to drive that exact proposed journey for " +
+        "real, in an already-consented browser session (sessionId, from browser({ verb: \"start_session\" })), then correlate " +
+        "which predicted pages the drive actually reached and route the graph path plus whatever the drive " +
+        "observed (console errors, failed requests) through the same governed gate draw_conclusion uses. Never " +
+        "boots an app, never clicks or types beyond the navigate-only proposal, and never widens the journey the " +
+        "first call showed you. A drive that reaches every predicted page with nothing wrong observed reports " +
+        "unconfirmed, honestly — a clean page load is not evidence of breakage.",
+    inputSchema: SCHEMA,
+    run,
+    describeAction,
+};
+//# sourceMappingURL=prove-reach.js.map

package/dist/tools/prove-reach.js.map

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

package/dist/tools/verb.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-verb argument validation for a merged tool.
+ *
+ * ## Why a merged tool needs this at all
+ *
+ * The dispatch loop refuses any argument no schema declares
+ * (`server.ts`'s `unknownArgumentKeys`, built for UAT phase 5's F12 after
+ * `browser_start_session({ profile })` silently read `environment` and issued
+ * the wrong consent sentence). That check reads one flat `inputSchema`.
+ *
+ * A merged tool has one schema for many verbs, so its schema must declare the
+ * *union* of every verb's properties. `text` is then a declared property of the
+ * `browser` tool as a whole, and `browser({ verb: "snapshot", text: "hi" })`
+ * sails through the dispatch gate — the same silent-acceptance defect, one
+ * level further down, and invisible to the test that caught it the first time.
+ *
+ * So the strength the flat schema loses is re-established here, per verb. This
+ * is the price of merging, paid explicitly rather than absorbed.
+ *
+ * ## Why it names the other verb
+ *
+ * "unknown argument" is true but useless when the argument is real and the verb
+ * is wrong — the caller who sent `text` to `snapshot` did not misspell
+ * anything, they picked the wrong verb. Saying *`"text"` belongs to `type`*
+ * turns a refusal the caller must debug into one they can act on, which is the
+ * same reason `ToolInputError` exists separately from a thrown `Error`.
+ */
+export interface VerbSpec<V extends string = string> {
+    readonly verb: V;
+    /** Properties this verb accepts, beyond the shared ones. */
+    readonly accepts: readonly string[];
+}
+/**
+ * Resolve and validate the verb of a merged tool call.
+ *
+ * Refuses, rather than defaulting or ignoring, on: a missing verb, an unknown
+ * verb, and any property that belongs to a different verb. Returns the verb so
+ * the caller can switch on a value already known to be valid.
+ *
+ * `shared` are properties every verb accepts — a session id, a budget. A
+ * property in neither `shared` nor any verb's `accepts` is not this function's
+ * to judge: the dispatch gate already refused it against the declared schema,
+ * and re-refusing it here would put the tool's property list in two places.
+ */
+export declare function selectVerb<V extends string>(args: Record<string, unknown>, key: string, specs: readonly VerbSpec<V>[], shared?: readonly string[]): V;
+//# sourceMappingURL=verb.d.ts.map

package/dist/tools/verb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verb.d.ts","sourceRoot":"","sources":["../../src/tools/verb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACjD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,QAAQ,CAAC,CAAC,CAAC,EAAE,EAC7B,MAAM,GAAE,SAAS,MAAM,EAAO,GAC7B,CAAC,CAwCH"}

package/dist/tools/verb.js

@@ -0,0 +1,78 @@
+/**
+ * Per-verb argument validation for a merged tool.
+ *
+ * ## Why a merged tool needs this at all
+ *
+ * The dispatch loop refuses any argument no schema declares
+ * (`server.ts`'s `unknownArgumentKeys`, built for UAT phase 5's F12 after
+ * `browser_start_session({ profile })` silently read `environment` and issued
+ * the wrong consent sentence). That check reads one flat `inputSchema`.
+ *
+ * A merged tool has one schema for many verbs, so its schema must declare the
+ * *union* of every verb's properties. `text` is then a declared property of the
+ * `browser` tool as a whole, and `browser({ verb: "snapshot", text: "hi" })`
+ * sails through the dispatch gate — the same silent-acceptance defect, one
+ * level further down, and invisible to the test that caught it the first time.
+ *
+ * So the strength the flat schema loses is re-established here, per verb. This
+ * is the price of merging, paid explicitly rather than absorbed.
+ *
+ * ## Why it names the other verb
+ *
+ * "unknown argument" is true but useless when the argument is real and the verb
+ * is wrong — the caller who sent `text` to `snapshot` did not misspell
+ * anything, they picked the wrong verb. Saying *`"text"` belongs to `type`*
+ * turns a refusal the caller must debug into one they can act on, which is the
+ * same reason `ToolInputError` exists separately from a thrown `Error`.
+ */
+import { ToolInputError } from "./kit.js";
+/**
+ * Resolve and validate the verb of a merged tool call.
+ *
+ * Refuses, rather than defaulting or ignoring, on: a missing verb, an unknown
+ * verb, and any property that belongs to a different verb. Returns the verb so
+ * the caller can switch on a value already known to be valid.
+ *
+ * `shared` are properties every verb accepts — a session id, a budget. A
+ * property in neither `shared` nor any verb's `accepts` is not this function's
+ * to judge: the dispatch gate already refused it against the declared schema,
+ * and re-refusing it here would put the tool's property list in two places.
+ */
+export function selectVerb(args, key, specs, shared = []) {
+    const raw = args[key];
+    if (raw === undefined || raw === null || raw === "") {
+        throw new ToolInputError(`"${key}" is required — one of: ${specs.map((s) => s.verb).join(", ")}`);
+    }
+    if (typeof raw !== "string")
+        throw new ToolInputError(`"${key}" must be a string`);
+    const spec = specs.find((s) => s.verb === raw);
+    if (spec === undefined) {
+        throw new ToolInputError(`"${key}" must be one of: ${specs.map((s) => s.verb).join(", ")}`);
+    }
+    // Where each property that is not this verb's does belong. Built per call
+    // rather than hoisted: the specs are a handful of entries, and a module-level
+    // cache keyed on a caller-supplied array is a lifetime question this does not
+    // need to have.
+    const ownerOf = new Map();
+    for (const other of specs) {
+        if (other.verb === spec.verb)
+            continue;
+        for (const property of other.accepts) {
+            if (spec.accepts.includes(property))
+                continue;
+            // First owner wins only for the message; the refusal is the same either
+            // way, and listing every owner of a property shared by two other verbs
+            // would bury the one fact the caller needs.
+            if (!ownerOf.has(property))
+                ownerOf.set(property, other.verb);
+        }
+    }
+    const strays = Object.keys(args).filter((property) => property !== key && !shared.includes(property) && ownerOf.has(property));
+    if (strays.length > 0) {
+        const detail = strays.map((property) => `"${property}" belongs to ${ownerOf.get(property)}`).join("; ");
+        throw new ToolInputError(`${spec.verb} does not accept ${strays.map((p) => `"${p}"`).join(", ")} — ${detail}. ` +
+            `${spec.verb} accepts: ${[...shared, ...spec.accepts].join(", ") || "no arguments beyond the verb"}.`);
+    }
+    return spec.verb;
+}
+//# sourceMappingURL=verb.js.map

package/dist/tools/verb.js.map

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

package/dist/tools/workspace.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `workspace` — merges `analyze`, `analyze_workspace` and `link_workspace`
+ * behind one `verb` (documents/plans/mcp-surface-consolidation.md §2, group 1).
+ * All three are `stateful-read`/`evidence`, so the merge crosses neither
+ * boundary.
+ *
+ * Dispatch only. Each verb's own `run()` body is untouched and stays in its
+ * own module (`analyze.ts` / `analyze-workspace.ts` / `link-workspace.ts`) —
+ * this file never holds a second copy of that logic, it only routes to it
+ * after `selectVerb` has re-established, per verb, the argument strength a
+ * flat union schema loses (`verb.ts`'s own header explains why that is
+ * mandatory once a schema covers more than one verb).
+ */
+import type { ToolDefinition } from "./kit.ts";
+import type { AnalyzeData } from "./analyze.ts";
+import type { AnalyzeWorkspaceData } from "./analyze-workspace.ts";
+import type { LinkWorkspaceData } from "./link-workspace.ts";
+/**
+ * What this tool answers with: one verb's shape, never a merged one.
+ *
+ * The merge cost this its single concrete output type, and `unknown` would have
+ * silently retired `output-shapes.test.ts`'s check that a declared shape is tied
+ * to the code producing it. A union keeps that tie: a verb added without its
+ * shape here stops compiling.
+ */
+export type WorkspaceData = AnalyzeData | AnalyzeWorkspaceData | LinkWorkspaceData;
+export declare const workspaceTool: ToolDefinition;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/tools/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/tools/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,UAAU,CAAC;AAM5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,oBAAoB,GACpB,iBAAiB,CAAC;AAiFtB,eAAO,MAAM,aAAa,EAAE,cAa3B,CAAC"}

package/dist/tools/workspace.js

@@ -0,0 +1,101 @@
+/**
+ * `workspace` — merges `analyze`, `analyze_workspace` and `link_workspace`
+ * behind one `verb` (documents/plans/mcp-surface-consolidation.md §2, group 1).
+ * All three are `stateful-read`/`evidence`, so the merge crosses neither
+ * boundary.
+ *
+ * Dispatch only. Each verb's own `run()` body is untouched and stays in its
+ * own module (`analyze.ts` / `analyze-workspace.ts` / `link-workspace.ts`) —
+ * this file never holds a second copy of that logic, it only routes to it
+ * after `selectVerb` has re-established, per verb, the argument strength a
+ * flat union schema loses (`verb.ts`'s own header explains why that is
+ * mandatory once a schema covers more than one verb).
+ */
+import { selectVerb } from "./verb.js";
+import { analyzeTool } from "./analyze.js";
+import { analyzeWorkspaceTool } from "./analyze-workspace.js";
+import { linkWorkspaceTool } from "./link-workspace.js";
+const VERBS = ["analyze", "index", "link"];
+const VERB_SPECS = [
+    { verb: "analyze", accepts: ["includeHistory", "maxCommits", "reload"] },
+    { verb: "index", accepts: ["includeHistory", "maxCommits"] },
+    { verb: "link", accepts: ["workspace", "repos"] },
+];
+const SCHEMA = {
+    type: "object",
+    properties: {
+        verb: {
+            type: "string",
+            enum: [...VERBS],
+            description: '"analyze" — read this repository into the code graph. "index" — read every repository a ' +
+                'prior "link" declared into one shared graph. "link" — declare which repositories share a ' +
+                "workspace.",
+        },
+        includeHistory: {
+            type: "boolean",
+            description: "analyze/index. Read git history for co-change coupling. Default true.",
+        },
+        maxCommits: {
+            type: "integer",
+            minimum: 1,
+            description: "analyze/index. Cap on commits read from history. Default 2000.",
+        },
+        reload: {
+            type: "boolean",
+            description: "analyze only. Re-read .descry/config.json from disk before this run, instead of the " +
+                "configuration this server started with.",
+        },
+        workspace: {
+            type: "string",
+            description: 'link only. The workspace id to write into every repository in "repos", byte-identical.',
+        },
+        repos: {
+            type: "array",
+            minItems: 2,
+            items: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute path to the repository on disk." },
+                    repo: { type: "string", description: "This repository's identity, written explicitly." },
+                },
+                required: ["path", "repo"],
+                additionalProperties: false,
+            },
+            description: "link only. Every repository that should share this workspace, including the current one " +
+                "if it should join. Only ones the user has explicitly confirmed belong together — never " +
+                "inferred.",
+        },
+    },
+    required: ["verb"],
+    additionalProperties: false,
+};
+const DISPATCH = {
+    analyze: analyzeTool,
+    index: analyzeWorkspaceTool,
+    link: linkWorkspaceTool,
+};
+async function run(args, ctx) {
+    const verb = selectVerb(args, "verb", VERB_SPECS);
+    // `ToolDefinition` erases its answer's type parameter — it has to, the
+    // registry is one array of many shapes — so the delegated call comes back as
+    // an erased answer type. The verb table is what makes the union true: every
+    // entry's own `run` is declared against one of WorkspaceData's members, and a verb
+    // added without its shape stops compiling at the union. The assertion
+    // re-applies what the table already guarantees rather than asserting
+    // something unchecked.
+    return (await DISPATCH[verb].run(args, ctx));
+}
+export const workspaceTool = {
+    name: "workspace",
+    class: "stateful-read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Analyse a repository or workspace into the code graph",
+    description: "Read source into the code graph, or declare which repositories share a workspace, by verb: " +
+        '"analyze" (one repository, with its configured adapters), "index" (every repository a prior ' +
+        '"link" call declared, into one shared graph), "link" (write a workspace id into each named ' +
+        "repository's config — only after the user has explicitly confirmed they belong together).",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=workspace.js.map

package/dist/tools/workspace.js.map

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