@descryy/mcp 0.11.5 → 0.11.7

package/dist/tools/predict-reach.js

@@ -0,0 +1,183 @@
+/**
+ * `predict_reach` — RG-10's predict-then-propose, exposed. Given a node
+ * (typically a `DATABASE_COLUMN` a change touches, but any node
+ * `reachablePages` can walk from), asks the graph which `PAGE`/`COMPONENT`
+ * nodes the data can reach — `@descryy/core`'s `reachablePages`, a walk
+ * over `PROPAGATES_TO`/`READS`/`ASSIGNS`/`RETURNS`, crossing `USES_API`
+ * backward at an `API_ENDPOINT` — and, when it reaches at least one page,
+ * proposes a navigate-only journey via the same planner `propose_journey`
+ * uses (`../planner/propose-journey.ts`, unmodified, called through
+ * `../planner/predict-then-propose.ts`).
+ *
+ * **Never drives anything and never writes to a Finding.** The proposal
+ * this returns is a value in this reply, not an action: proving or
+ * disproving what it predicts is a human (or an agent acting on a human's
+ * behalf) driving the application for real — `browser_start_session`, the
+ * browser primitives, `browser_save_scenario` to commit what actually
+ * happened — and then recording the outcome against the finding that
+ * predicted it. That last step needs `packages/ir/src/finding.ts` and the
+ * finding funnel, both outside this lane's owned files, and is not
+ * performed here; see this tool's own `description` for the same
+ * disclosure surfaced to a caller.
+ *
+ * **`observedNodeIds` — RG-10's join, added by the pipeline-joins lane.**
+ * Optional, and still never a drive: when a caller supplies the graph node
+ * ids a REAL, already-accepted journey actually reached (read straight off
+ * `browser_run_scenario`'s own reply after that scenario was driven — the
+ * acceptance gate is `browser_run_scenario`'s own, unchanged and untouched
+ * here), this tool additionally reports which predicted pages that real
+ * drive proved and which it disproved
+ * (`../planner/predict-then-propose.ts#proveOrDisprove`). Omitted (the
+ * default), the reply is byte-for-byte what it was before this parameter
+ * existed.
+ */
+import { predictThenPropose, proveOrDisprove } from "../planner/predict-then-propose.js";
+import { answer, briefNode, requiredString, optionalString, optionalStringArray, ToolInputError, } from "./kit.js";
+import { capBySize, sizeCapNote } from "../capped.js";
+import { resolveOneNode } from "./lookup.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        nodeId: { type: "string", description: "Node to predict reach from — typically a data column." },
+        symbol: {
+            type: "string",
+            description: "Start symbol if no node id. Ambiguous matches are refused.",
+        },
+        file: { type: "string", description: "Path, to disambiguate \"symbol\"." },
+        targetUrl: {
+            type: "string",
+            description: "REQUIRED. Base URL. Never inferred.",
+        },
+        name: { type: "string", description: "Name for the proposed scenario. Default \"predicted-journey\"." },
+        observedNodeIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional: nodes a real journey reached. Reports which predicted pages it proved or disproved.",
+        },
+    },
+    required: ["targetUrl"],
+    additionalProperties: false,
+};
+function fitPredictReach(rest, reachedPages, proposal, budgetBytes) {
+    const scaffoldBytes = Buffer.byteLength(JSON.stringify({
+        ...rest,
+        reachedPages: [],
+        proposal: proposal === null ? null : { ...proposal, reachedNotProposed: [] },
+    }), "utf8");
+    let budget = Math.max(budgetBytes - scaffoldBytes, 0);
+    const pagesFit = capBySize(reachedPages, budget, 0);
+    budget = Math.max(budget - Buffer.byteLength(JSON.stringify(pagesFit.shown), "utf8"), 0);
+    const reachedNotProposed = proposal?.reachedNotProposed ?? [];
+    const notProposedFit = capBySize(reachedNotProposed, budget, 0);
+    const notes = [];
+    if (pagesFit.droppedForSize > 0) {
+        notes.push(sizeCapNote("reached page/component", pagesFit.shown.length, reachedPages.length, pagesFit.droppedForSize));
+    }
+    if (notProposedFit.droppedForSize > 0) {
+        notes.push(sizeCapNote("reached-not-proposed node", notProposedFit.shown.length, reachedNotProposed.length, notProposedFit.droppedForSize));
+    }
+    const droppedNow = pagesFit.droppedForSize + notProposedFit.droppedForSize;
+    const shownNow = pagesFit.shown.length + notProposedFit.shown.length;
+    const preFitTotal = reachedPages.length + reachedNotProposed.length;
+    return {
+        data: {
+            ...rest,
+            reachedPages: pagesFit.shown,
+            proposal: proposal === null ? null : { ...proposal, reachedNotProposed: notProposedFit.shown },
+        },
+        notes,
+        ...(droppedNow === 0 ? {} : { truncatedDetail: { shown: shownNow, total: preFitTotal, more: null } }),
+    };
+}
+async function run(args, ctx) {
+    const nodeIdArg = optionalString(args, "nodeId");
+    const symbol = optionalString(args, "symbol");
+    const file = optionalString(args, "file");
+    const targetUrl = requiredString(args, "targetUrl");
+    const name = optionalString(args, "name") ?? "predicted-journey";
+    const observedNodeIds = optionalStringArray(args, "observedNodeIds");
+    if (nodeIdArg === undefined && symbol === undefined && file === undefined) {
+        throw new ToolInputError('give one of "nodeId", "symbol" or "file"');
+    }
+    const provider = ctx.session.provider();
+    const found = resolveOneNode(ctx.session, { nodeId: nodeIdArg, symbol, file });
+    const base = provider.baseStamp();
+    if (found.node === null) {
+        return {
+            result: {
+                data: { candidates: found.candidates.map(briefNode) },
+                stamp: { ...base, resolutionFloor: 0 },
+                truncated: false,
+                notes: found.notes,
+            },
+            nameLevel: true,
+            state: "refused",
+            headline: found.headline,
+        };
+    }
+    const node = found.node;
+    ctx.progress(`Predicting which pages ${node.name} can reach`);
+    const predicted = predictThenPropose(provider, node.id, {
+        targetUrl,
+        name,
+        savedAtCommit: base.commitSha ?? "",
+    });
+    const empty = { from: briefNode(node), reachedPages: [], proposal: null, proof: null };
+    const notes = [...found.notes, ...predicted.notes];
+    const proposal = predicted.proposal;
+    if (proposal === null) {
+        return answer({
+            headline: `${node.name} reaches no PAGE or COMPONENT this graph can walk to. Not a claim it reaches none in the running application — see notes.`,
+            state: "empty",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes,
+            data: empty,
+        });
+    }
+    const proof = observedNodeIds === undefined ? null : proveOrDisprove(predicted, { visitedNodeIds: observedNodeIds });
+    const reachedPages = predicted.reachedPages.map((n) => ({ id: n.id, type: n.type, name: n.name, resolution: 0 }));
+    const shapedProposal = { scenario: proposal.scenario, reachedNotProposed: proposal.reachedNotProposed };
+    return answer({
+        headline: `Predicted ${predicted.reachedPages.length} page/component reached from ${node.name}. Proposed ` +
+            `${proposal.scenario.steps.length} navigate step(s) — unaccepted, unsaved, undriven. Proving or ` +
+            "disproving this prediction is a human act: drive the app for real and save what happened." +
+            (proof === null
+                ? ""
+                : ` Against the observed evidence supplied: ${proof.proven.length} proven, ${proof.disproven.length} disproven.`),
+        // Name-level throughout: a route path is read off a node's qualified name (propose_journey's own cap),
+        // never off a type-checked shape.
+        resolutionFloor: 0,
+        nameLevel: true,
+        commitSha: base.commitSha,
+        graphBuiltAt: base.graphBuiltAt,
+        irSchemaVersion: base.irSchemaVersion,
+        commitSpread: base.commitSpread,
+        repoCount: base.repoCount,
+        notes,
+        data: {
+            from: briefNode(node),
+            reachedPages,
+            proposal: shapedProposal,
+            proof,
+        },
+        fitToBudget: (budgetBytes) => fitPredictReach({ from: briefNode(node), proof }, reachedPages, shapedProposal, budgetBytes),
+    });
+}
+export const predictReachTool = {
+    name: "predict_reach",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Predict which pages a data change reaches, and propose a journey to review it",
+    description: "Predicts which pages a data change reaches and proposes a navigate-only journey to review " +
+        "it. Never drives a browser. Pass observedNodeIds from a real drive to check the prediction.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=predict-reach.js.map

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

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

package/dist/tools/propagation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `propagation` — §11.9 data-flow query. Field-level answers require R3 (§11A.6:
+ * shapes need a type checker); below R3, path-level only, labelled as such.
+ * `PROPAGATES_TO` now has one narrow producer (`adapter-typescript`'s
+ * `extractPropagatesTo`, `descry-adapters`) — single call-argument, no
+ * cross-function chasing, by its own doc comment. Multi-hop/interprocedural
+ * data-flow chasing does not exist in any adapter yet. An empty walk is still
+ * attributed (edge types actually present near the node), never reported as
+ * "reaches 0 nodes", since most graphs still have nothing on this edge type. */
+import { type BriefNode, type NodeCandidates, type ToolDefinition } from "./kit.ts";
+/** A node the data can reach, with how far along the walk it sits. */
+export interface ReachedNode extends BriefNode {
+    readonly depth: number;
+    readonly score: number;
+}
+export interface PropagationReport {
+    readonly from: BriefNode;
+    /** Capped by `limit`; `reachedTotal` is the uncapped count. */
+    readonly reached: readonly ReachedNode[];
+    readonly reachedTotal: number;
+    /** True only at R3+. False means "where data can flow", not "which field arrives
+     *  where" — the latter compares shapes, needing a type checker. */
+    readonly fieldLevel: boolean;
+    /** False when no edge of any walked type touches the start node. Empty `reached`
+     *  with `analysed: false` means the walk didn't run, not that nothing propagates —
+     *  the common case, since `PROPAGATES_TO` has only one narrow single-hop producer
+     *  (`adapter-typescript`) and most graphs still carry none of it. */
+    readonly analysed: boolean;
+    readonly edgeTypesWalked: readonly string[];
+    /** The subset of `edgeTypesWalked` actually found on an edge touching this node. */
+    readonly edgeTypesPresent: readonly string[];
+}
+/** One call, two shapes — narrow on `"from" in data`. `NodeCandidates` arrives when
+ *  the symbol didn't resolve to exactly one node, and nothing was walked. */
+export type PropagationData = PropagationReport | NodeCandidates;
+export declare const propagationTool: ToolDefinition;
+//# sourceMappingURL=propagation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.ts","sourceRoot":"","sources":["../../src/tools/propagation.ts"],"names":[],"mappings":"AAAA;;;;;;;;gFAQgF;AAIhF,OAAO,EAOL,KAAK,SAAS,EACd,KAAK,cAAc,EAEnB,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAGlB,sEAAsE;AACtE,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;uEACmE;IACnE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;yEAGqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,oFAAoF;IACpF,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED;6EAC6E;AAC7E,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAgKjE,eAAO,MAAM,eAAe,EAAE,cAY7B,CAAC"}

package/dist/tools/propagation.js

@@ -0,0 +1,162 @@
+/**
+ * `propagation` — §11.9 data-flow query. Field-level answers require R3 (§11A.6:
+ * shapes need a type checker); below R3, path-level only, labelled as such.
+ * `PROPAGATES_TO` now has one narrow producer (`adapter-typescript`'s
+ * `extractPropagatesTo`, `descry-adapters`) — single call-argument, no
+ * cross-function chasing, by its own doc comment. Multi-hop/interprocedural
+ * data-flow chasing does not exist in any adapter yet. An empty walk is still
+ * attributed (edge types actually present near the node), never reported as
+ * "reaches 0 nodes", since most graphs still have nothing on this edge type. */
+import { dataFlowFrom, DATA_FLOW_EDGE_TYPES } from "@descryy/core";
+import { answer, briefNode, optionalInteger, optionalString, optionalStringArray, ToolInputError, } from "./kit.js";
+import { resolveOneNode } from "./lookup.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        nodeId: { type: "string", description: "Graph node id to start from." },
+        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.",
+        },
+        edgeTypes: {
+            type: "array",
+            items: { type: "string" },
+            description: "Restrict the walk. Defaults to PROPAGATES_TO, READS, ASSIGNS and RETURNS — the four that " +
+                "carry data rather than control. Only one shipped adapter produces PROPAGATES_TO today, and " +
+                "only narrowly (single call-argument, no cross-function chasing); no adapter does " +
+                "multi-hop/interprocedural data-flow chasing yet, so in most repos this walk still runs " +
+                "over the other three; an empty result is disclosed as such rather than reported as " +
+                "\"reaches 0 nodes\".",
+        },
+        maxDepth: { type: "integer", minimum: 1, description: "Hop limit. Default unbounded." },
+        limit: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap on nodes in the reply. Default 25 (MK-9 — the same walk-cost reduction impact.ts " +
+                "applies, for the same reason). A capped reply always discloses shown/total; raise this " +
+                "explicitly when the full set is needed.",
+        },
+    },
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const nodeId = optionalString(args, "nodeId");
+    const symbol = optionalString(args, "symbol");
+    const file = optionalString(args, "file");
+    const edgeTypes = optionalStringArray(args, "edgeTypes");
+    const maxDepth = optionalInteger(args, "maxDepth", 1);
+    const limit = optionalInteger(args, "limit", 1) ?? 25;
+    if (nodeId === undefined && symbol === undefined && file === undefined) {
+        throw new ToolInputError('give one of "nodeId", "symbol" or "file"');
+    }
+    const found = resolveOneNode(ctx.session, { nodeId, symbol, file });
+    if (found.node === null) {
+        const base = ctx.session.provider().baseStamp();
+        return answer({
+            headline: found.headline,
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes: found.notes,
+            data: { candidates: found.candidates.map(briefNode) },
+        });
+    }
+    ctx.progress(`Following data out of ${found.node.name}`);
+    const flow = dataFlowFrom(ctx.session.provider(), found.node.id, {
+        ...(maxDepth === undefined ? {} : { maxDepth }),
+        ...(edgeTypes === undefined ? {} : { types: edgeTypes }),
+    });
+    const reached = flow.data.filter((entry) => entry.node.id !== found.node?.id);
+    const shown = reached.slice(0, limit);
+    const notes = [...found.notes, ...flow.notes];
+    if (shown.length < reached.length) {
+        notes.push(`${reached.length - shown.length} further node(s) are on the path but not listed — the reply ` +
+            `is capped at ${limit}.`);
+    }
+    // Which walked edge types exist around the start node — the baseline precondition.
+    // None present means "reaches 0 nodes" is a statement about the graph, not the symbol.
+    const walked = edgeTypes ?? DATA_FLOW_EDGE_TYPES;
+    const present = new Set();
+    for (const edge of [
+        ...ctx.session.provider().outgoing(found.node.id),
+        ...ctx.session.provider().incoming(found.node.id),
+    ]) {
+        if (walked.includes(edge.type))
+            present.add(edge.type);
+    }
+    const absent = walked.filter((type) => !present.has(type));
+    const analysed = present.size > 0;
+    if (absent.length > 0) {
+        notes.push(`No ${absent.join(", ")} edge touches this node, so ${absent.length === 1 ? "that type" : "those types"} ` +
+            "contributed nothing to this answer.");
+    }
+    if (!analysed) {
+        notes.push(`None of the requested edge types (${walked.join(", ")}) appear on any edge touching this node, ` +
+            "so the walk had nothing to follow. That is not a finding that no data leaves this symbol: " +
+            "no adapter configured here emitting these edge types at all (PROPAGATES_TO's only shipped " +
+            "producer today is narrow single-hop and may simply not have fired here), a " +
+            "graph built without the source that would carry them, and a symbol that genuinely " +
+            "propagates nothing are three different situations. This probe is local to one node and " +
+            "cannot tell them apart — it reports that the walk did not run rather than choosing between them.");
+    }
+    const fieldLevel = flow.stamp.resolutionFloor >= 3;
+    return {
+        result: {
+            ...flow,
+            data: {
+                from: briefNode(found.node),
+                reached: shown.map((entry) => ({
+                    ...briefNode(entry.node),
+                    depth: entry.depth,
+                    score: Number(entry.score.toFixed(4)),
+                })),
+                reachedTotal: reached.length,
+                fieldLevel,
+                /** False when no edge of any walked type touches the start node — empty
+                 *  `reached` with this false means the walk didn't run. Mirrors `HiddenDependencyReport`. */
+                analysed,
+                edgeTypesWalked: walked,
+                edgeTypesPresent: [...present].sort(),
+            },
+            notes,
+        },
+        ...(analysed ? (reached.length === 0 ? { state: "empty" } : {}) : { state: "refused" }),
+        // Never name-level — §11A.5's R2/class-A carve-out is for existence facts (a
+        // missing env var), not a data-flow shape claim. R2 stays capped at B here;
+        // only R3/R4 reach A, the conservative "when in doubt, understate" reading.
+        nameLevel: false,
+        // The headline is what a user acts on — not-analysable gets its own sentence
+        // rather than reusing "reaches 0 node(s)" with a note beneath it (a zero in the
+        // headline reads as a measurement regardless of the notes).
+        headline: !analysed
+            ? `Data flow out of ${found.node.name} was not analysed: the graph holds no ` +
+                `${walked.join("/")} edge touching it. This is not a finding that nothing propagates.`
+            : fieldLevel
+                ? `Data from ${found.node.name} reaches ${reached.length} node(s), at field level.`
+                : `${found.node.name} can reach ${reached.length} node(s). This is where data *can* flow, ` +
+                    "not which field arrives where — that needs R3.",
+    };
+}
+export const propagationTool = {
+    name: "propagation",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Where does this data end up?",
+    description: "Follow a value from a symbol or field through the graph along the edges that carry data. " +
+        "Field-level answers require a type checker (R3); below that the answer is path-level and " +
+        "labelled as such rather than overstated.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=propagation.js.map

package/dist/tools/propagation.js.map

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

package/dist/tools/propose-journey.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `propose_journey` — the planner, exposed. Lane A1, item 5: proposes a
+ * journey from the `PAGE`/`COMPONENT` nodes a diff scope touches; never
+ * writes, never drives a browser, never executes anything. See
+ * `../planner/propose-journey.ts` for what "propose, never invent" means
+ * structurally.
+ */
+import { type JourneyCandidateNode } from "../planner/propose-journey.ts";
+import { type Scenario } from "../scenarios/index.ts";
+import { type ToolDefinition } from "./kit.ts";
+export interface ProposeJourneyData {
+    readonly scenario: Scenario;
+    readonly reachedNotProposed: readonly JourneyCandidateNode[];
+}
+export declare const proposeJourneyTool: ToolDefinition;
+//# sourceMappingURL=propose-journey.d.ts.map

package/dist/tools/propose-journey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propose-journey.d.ts","sourceRoot":"","sources":["../../src/tools/propose-journey.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1F,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAKlB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC9D;AA6HD,eAAO,MAAM,kBAAkB,EAAE,cAWhC,CAAC"}

package/dist/tools/propose-journey.js

@@ -0,0 +1,132 @@
+/**
+ * `propose_journey` — the planner, exposed. Lane A1, item 5: proposes a
+ * journey from the `PAGE`/`COMPONENT` nodes a diff scope touches; never
+ * writes, never drives a browser, never executes anything. See
+ * `../planner/propose-journey.ts` for what "propose, never invent" means
+ * structurally.
+ */
+import { nodesInFiles, scopeChange } from "@descryy/core";
+import { proposeJourney } from "../planner/propose-journey.js";
+import { SCENARIO_SCHEMA_VERSION } from "../scenarios/index.js";
+import { optionalString, optionalStringArray, requiredString, ToolInputError, } from "./kit.js";
+import { capBySize, sizeCapNote } from "../capped.js";
+import { answer } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        files: {
+            type: "array",
+            items: { type: "string" },
+            description: "Paths that are changing. Same seeding as change_scope.",
+        },
+        nodeIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Node ids to seed with, instead of or with files.",
+        },
+        targetUrl: {
+            type: "string",
+            description: "REQUIRED. Base URL. Never inferred.",
+        },
+        name: {
+            type: "string",
+            description: "Name for the proposed scenario. Default \"proposed-journey\".",
+        },
+    },
+    required: ["targetUrl"],
+    additionalProperties: false,
+};
+function fitProposeJourney(scenario, reachedNotProposed, budgetBytes) {
+    const scaffoldBytes = Buffer.byteLength(JSON.stringify({ scenario, reachedNotProposed: [] }), "utf8");
+    const fit = capBySize(reachedNotProposed, budgetBytes, scaffoldBytes);
+    const notes = fit.droppedForSize === 0
+        ? []
+        : [sizeCapNote("reached-not-proposed node", fit.shown.length, reachedNotProposed.length, fit.droppedForSize)];
+    return {
+        data: { scenario, reachedNotProposed: fit.shown },
+        notes,
+        ...(fit.droppedForSize === 0
+            ? {}
+            : { truncatedDetail: { shown: fit.shown.length, total: reachedNotProposed.length, more: null } }),
+    };
+}
+async function run(args, ctx) {
+    const targetUrl = requiredString(args, "targetUrl");
+    const name = optionalString(args, "name") ?? "proposed-journey";
+    const files = optionalStringArray(args, "files") ?? [];
+    const seedIds = [...(optionalStringArray(args, "nodeIds") ?? [])];
+    if (files.length === 0 && seedIds.length === 0) {
+        throw new ToolInputError('give at least one of "files" or "nodeIds" — the planner proposes from a diff scope, and a diff scope needs a seed');
+    }
+    const session = ctx.session;
+    if (files.length > 0) {
+        const { nodes } = nodesInFiles(session.store().driver, files);
+        for (const node of nodes)
+            seedIds.push(node.id);
+    }
+    const base = session.provider().baseStamp();
+    const empty = {
+        scenario: {
+            schemaVersion: SCENARIO_SCHEMA_VERSION,
+            name,
+            description: null,
+            targetUrl,
+            savedAt: new Date().toISOString(),
+            savedAtCommit: "",
+            steps: [],
+            assertions: [],
+        },
+        reachedNotProposed: [],
+    };
+    if (seedIds.length === 0) {
+        return answer({
+            headline: "Nothing in the graph matches what you named, so no journey could be proposed.",
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes: ["This is not a claim that the change touches no pages. No seed node was found, so the scope traversal never ran."],
+            data: empty,
+        });
+    }
+    const scoped = scopeChange(session.provider(), [...new Set(seedIds)], { trigger: "pr" });
+    const candidates = [...scoped.data.changed, ...scoped.data.affected].map((s) => ({
+        id: s.node.id,
+        type: s.node.type,
+        name: s.node.name,
+    }));
+    const proposal = proposeJourney(candidates, { targetUrl, name, savedAtCommit: base.commitSha ?? "" });
+    return answer({
+        headline: proposal.scenario.steps.length === 0
+            ? "No page-shaped route was found in scope — nothing proposed."
+            : `Proposed ${proposal.scenario.steps.length} navigate step(s), unaccepted and unsaved.`,
+        // Name-level: a route path is read straight off a node's qualified name, never off a
+        // type-checked shape — the same cap `scope.ts` applies to its own reply.
+        resolutionFloor: 0,
+        nameLevel: true,
+        commitSha: base.commitSha,
+        graphBuiltAt: base.graphBuiltAt,
+        irSchemaVersion: base.irSchemaVersion,
+        commitSpread: base.commitSpread,
+        repoCount: base.repoCount,
+        notes: [...scoped.notes, ...proposal.notes],
+        data: { scenario: proposal.scenario, reachedNotProposed: proposal.reachedNotProposed },
+        fitToBudget: (budgetBytes) => fitProposeJourney(proposal.scenario, proposal.reachedNotProposed, budgetBytes),
+    });
+}
+export const proposeJourneyTool = {
+    name: "propose_journey",
+    title: "Propose a journey from a diff's affected pages",
+    description: "Proposes a navigate-only scenario from the pages a change touches — a value in this reply, " +
+        "never driven or saved. A human drives it for real if accepted and saves the result.",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=propose-journey.js.map

package/dist/tools/propose-journey.js.map

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