@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/tools/harness-plan.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What a drive is FOR, decided before it starts and read out of `.reticle` rather than the app.
+ *
+ * The driver used to open its eyes on a page and pick whatever looked interesting. That makes every
+ * run start from zero: it re-drives journeys that are already saved, and it has no idea which
+ * declared intent nobody has ever tested. Both are the same missing input — the project's own
+ * record of what it claims to do and what has been proved about it.
+ *
+ * `.reticle` already holds that. `buildDomainModel` reads `.reticle/flows/` and
+ * `.reticle/contract.json` and answers with every saved flow, the consequence that MUST hold for
+ * each one, and the GAPS: signals and testids the app DECLARED that no flow asserts. So the plan is
+ * derivable with no browser, no model and no source code — which is the order this product argues
+ * for everywhere else and did not follow here.
+ *
+ * Two kinds of step, and the split is the whole economics:
+ *
+ *   REPLAY  a journey that is already recorded. Deterministic, no model in the loop, a few hundred
+ *           tokens. Anything already covered belongs here and must never be re-driven.
+ *   DRIVE   a gap. A model is worth paying for exactly where nothing is proved yet.
+ *
+ * Nothing here calls a model. The plan is the deterministic half, and the model's only job is to
+ * choose among steps somebody already decided were worth taking.
+ */
+import type { DomainModel } from '../../judgement/domain/domain-model.js';
+export declare const PlanStepKind: {
+    /** Already recorded: replay it deterministically instead of paying a model to rediscover it. */
+    readonly REPLAY: "replay";
+    /** Declared but never proved: this is what a drive is actually for. */
+    readonly DRIVE: "drive";
+};
+export type PlanStepKind = (typeof PlanStepKind)[keyof typeof PlanStepKind];
+export interface PlanStep {
+    kind: PlanStepKind;
+    /** The flow to replay, or a short label for the gap to cover. */
+    target: string;
+    /**
+     * WHY this step is in the plan, in the project's own words.
+     *
+     * For a replay it is the consequence that must hold — the flow's `mustHold`, which is the thing
+     * that stops being true when the feature breaks. For a drive it is the declared intent nobody has
+     * tested. Carried because the model choosing between steps should be reading intent, not a list
+     * of names it has no way to rank.
+     */
+    why: string;
+}
+export interface HarnessPlan {
+    steps: readonly PlanStep[];
+    /** One line an agent or a human can read, derived rather than narrated. */
+    summary: string;
+    /**
+     * The app's OWN vocabulary: the signals it declared in its capabilities, untested ones first.
+     *
+     * Carried out of `.reticle` for the same reason the steps are, and then used for something the
+     * plan itself never does. A drive declares what it expects BEFORE it acts, and a declaration can
+     * only be saved into the flow if it names something: `signal "order:placed"` records, a bare
+     * "some signal fires" does not, and a flow that records nothing replays green whatever the
+     * feature does. These are the names that make the difference.
+     */
+    vocabulary: readonly string[];
+}
+/**
+ * Build the plan.
+ *
+ * Replays come first, always. They are the cheap half and they establish what is still true before
+ * any model is paid to explore what is not yet known — and a regression found by a replay is found
+ * for a few hundred tokens rather than a few hundred thousand.
+ */
+export declare function buildHarnessPlan(domain: DomainModel): HarnessPlan;
+/**
+ * The plan as the model reads it.
+ *
+ * Intent first and names second, because a model ranking "what next" against a list of identifiers
+ * is guessing, and ranking against what the project says each one is FOR is not. The kind is stated
+ * so it can prefer finishing the cheap deterministic half before spending itself on the rest.
+ */
+export declare function planAsText(plan: HarnessPlan): string;

package/dist/surface/tools/harness-plan.js

@@ -0,0 +1,156 @@
+/**
+ * What a drive is FOR, decided before it starts and read out of `.reticle` rather than the app.
+ *
+ * The driver used to open its eyes on a page and pick whatever looked interesting. That makes every
+ * run start from zero: it re-drives journeys that are already saved, and it has no idea which
+ * declared intent nobody has ever tested. Both are the same missing input — the project's own
+ * record of what it claims to do and what has been proved about it.
+ *
+ * `.reticle` already holds that. `buildDomainModel` reads `.reticle/flows/` and
+ * `.reticle/contract.json` and answers with every saved flow, the consequence that MUST hold for
+ * each one, and the GAPS: signals and testids the app DECLARED that no flow asserts. So the plan is
+ * derivable with no browser, no model and no source code — which is the order this product argues
+ * for everywhere else and did not follow here.
+ *
+ * Two kinds of step, and the split is the whole economics:
+ *
+ *   REPLAY  a journey that is already recorded. Deterministic, no model in the loop, a few hundred
+ *           tokens. Anything already covered belongs here and must never be re-driven.
+ *   DRIVE   a gap. A model is worth paying for exactly where nothing is proved yet.
+ *
+ * Nothing here calls a model. The plan is the deterministic half, and the model's only job is to
+ * choose among steps somebody already decided were worth taking.
+ */
+export const PlanStepKind = {
+    /** Already recorded: replay it deterministically instead of paying a model to rediscover it. */
+    REPLAY: 'replay',
+    /** Declared but never proved: this is what a drive is actually for. */
+    DRIVE: 'drive',
+};
+/**
+ * How many untested declarations become drive steps.
+ *
+ * A contract can declare hundreds of testids, and a plan longer than the step budget is not a plan,
+ * it is a list. Capped so the drive spends its budget on the front of a ranked queue rather than
+ * spreading itself across everything and finishing none of it.
+ */
+const MAX_DRIVE_STEPS = 12;
+/**
+ * How many recorded journeys become replay steps.
+ *
+ * A project with seventy-four flows produced a seventy-four-step plan, which went into the tool
+ * result AND the standing instruction — thousands of tokens spent, every turn, listing work the
+ * drive had no budget to do. The whole argument for reading `.reticle` first is spending less, and
+ * an uncapped plan spends more.
+ *
+ * `reticle_domain` caps its own per-flow detail at 25 for the same measured reason. Ranked before
+ * cutting, so what survives is what is worth replaying first rather than whatever was listed first.
+ */
+const MAX_REPLAY_STEPS = 15;
+/** Signals first: a declared signal is a stronger statement of intent than a testid. */
+function driveSteps(domain) {
+    const steps = [];
+    for (const signal of domain.gaps.declaredUntestedSignals) {
+        steps.push({
+            kind: PlanStepKind.DRIVE,
+            target: signal,
+            why: `the app declares the signal "${signal}" and no saved flow asserts it`,
+        });
+    }
+    for (const testid of domain.gaps.declaredUntestedTestids) {
+        steps.push({
+            kind: PlanStepKind.DRIVE,
+            target: testid,
+            why: `the app declares the control "${testid}" and no saved flow exercises it`,
+        });
+    }
+    return steps.slice(0, MAX_DRIVE_STEPS);
+}
+/**
+ * Replay steps, worst-risk first when there is run history to rank by.
+ *
+ * A flow that asserts nothing is listed too, and says so: replaying it proves very little, and the
+ * honest plan admits that rather than counting it as coverage.
+ */
+function replaySteps(domain) {
+    const byName = new Map(domain.flows.map((flow) => [flow.name, flow]));
+    const ordered = 0 === domain.riskRanked.length
+        ? domain.flows.map((flow) => flow.name)
+        : [
+            ...domain.riskRanked,
+            ...domain.flows.map((f) => f.name).filter((name) => !domain.riskRanked.includes(name)),
+        ];
+    /*
+     * Flows that assert a real consequence come first, whatever the run history says.
+     *
+     * A flow with no `mustHold` passes as long as its steps still run, so replaying one proves close
+     * to nothing — and when the plan has to be cut, proving nothing is the first thing to give up.
+     */
+    const ranked = [
+        ...ordered.filter((name) => byName.get(name)?.mustHold !== undefined),
+        ...ordered.filter((name) => byName.get(name)?.mustHold === undefined),
+    ];
+    const steps = [];
+    for (const name of ranked) {
+        const flow = byName.get(name);
+        if (flow === undefined)
+            continue;
+        steps.push({
+            kind: PlanStepKind.REPLAY,
+            target: name,
+            why: flow.mustHold === undefined
+                ? `already recorded, but it asserts no consequence — replaying it proves only that the steps still run`
+                : `already recorded; it must still hold: ${flow.mustHold}`,
+        });
+    }
+    return steps.slice(0, MAX_REPLAY_STEPS);
+}
+/**
+ * Build the plan.
+ *
+ * Replays come first, always. They are the cheap half and they establish what is still true before
+ * any model is paid to explore what is not yet known — and a regression found by a replay is found
+ * for a few hundred tokens rather than a few hundred thousand.
+ */
+export function buildHarnessPlan(domain) {
+    const replays = replaySteps(domain);
+    const drives = driveSteps(domain);
+    const steps = [...replays, ...drives];
+    // Counted over EVERYTHING, then listed up to the cap — the same split `reticle_domain` uses, so a
+    // capped listing never quietly becomes a smaller analysis.
+    const totalRecorded = domain.flows.length;
+    const totalGaps = domain.gaps.declaredUntestedSignals.length + domain.gaps.declaredUntestedTestids.length;
+    const omitted = totalRecorded - replays.length + (totalGaps - drives.length);
+    /*
+     * Untested declarations first: a signal no flow asserts is exactly the one a drive should be
+     * claiming, and it is the same ranking the drive steps above already use.
+     *
+     * Then the signals saved flows ALREADY assert, which is not redundant and not a nicety. Most apps
+     * declare no capabilities at all -- the production dashboard this was measured on has no
+     * `contract.json` -- so a vocabulary built only from declarations is empty for exactly the
+     * projects that most need one. A signal a saved flow asserts is better evidence than a
+     * declaration anyway: it is a name the app has actually been observed to fire.
+     */
+    const vocabulary = [
+        ...domain.gaps.declaredUntestedSignals,
+        ...domain.declared.signals,
+        ...domain.flows.flatMap((flow) => flow.signals),
+    ].filter((name, index, all) => 0 < name.length && all.indexOf(name) === index);
+    const summary = 0 === steps.length
+        ? 'Nothing is recorded and nothing is declared: there is no plan to follow, so drive the app to find out what it does.'
+        : `${String(totalRecorded)} recorded journey(s) and ${String(totalGaps)} untested declaration(s); the plan lists the ${String(steps.length)} worth doing first${0 === omitted ? '' : `, omitting ${String(omitted)}`}.`;
+    return { steps, summary, vocabulary };
+}
+/**
+ * The plan as the model reads it.
+ *
+ * Intent first and names second, because a model ranking "what next" against a list of identifiers
+ * is guessing, and ranking against what the project says each one is FOR is not. The kind is stated
+ * so it can prefer finishing the cheap deterministic half before spending itself on the rest.
+ */
+export function planAsText(plan) {
+    if (0 === plan.steps.length)
+        return 'PLAN: none — nothing recorded, nothing declared.';
+    const lines = plan.steps.map((step, index) => ` ${String(index + 1)}. [${step.kind}] ${step.target} — ${step.why}`);
+    return `PLAN (from .reticle, not from the source):\n${lines.join('\n')}`;
+}

package/dist/surface/tools/harness-toolset.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reticle's own tool surface, handed to the harness.
+ *
+ * The harness drives exactly what an agent drives — same definitions, same dispatcher, same session.
+ * There is no private path into the engine, and that is a design rule rather than an implementation
+ * detail: the moment the harness needs something the tool surface does not expose, the tool surface
+ * is missing a tool and THAT is the bug. Every capability a harness run proves is one a user's own
+ * agent can reach.
+ */
+import { type ToolDeps } from './tools.js';
+import type { HarnessToolset } from '../../features/harness/harness.js';
+export interface ReticleToolsetOptions {
+    /** Pinned session, so a drive works the tab it opened rather than whichever one resolves. */
+    sessionId?: string;
+    /** Restrict to these names. Defaults to the advertised surface plus the recording pair. */
+    only?: readonly string[];
+}
+/**
+ * Bind the live tool surface to a set of dependencies.
+ *
+ * `deps` is the daemon's own dependency bag — the same one the MCP layer dispatches with — so a
+ * harness drive and an agent drive are indistinguishable from inside the engine. That is what makes
+ * a harness run a measurement of the product rather than of a test harness.
+ */
+export declare function reticleToolset(deps: ToolDeps, options?: ReticleToolsetOptions): HarnessToolset;
+/**
+ * Stamp the drive's own session onto a call.
+ *
+ * Without it a drive that opened one tab can have a tool resolve a DIFFERENT one — and a verdict
+ * about the wrong tab is the false green this product exists to prevent, arriving through our own
+ * front door. An explicit `sessionId` in the arguments wins: `reticle_sessions` hands the model real
+ * ids, and silently overwriting one would make a deliberate cross-tab call lie about which tab it
+ * read.
+ */
+export declare function pinSession(args: Record<string, unknown>, sessionId: string | undefined): Record<string, unknown>;

package/dist/surface/tools/harness-toolset.js

@@ -0,0 +1,144 @@
+/**
+ * Reticle's own tool surface, handed to the harness.
+ *
+ * The harness drives exactly what an agent drives — same definitions, same dispatcher, same session.
+ * There is no private path into the engine, and that is a design rule rather than an implementation
+ * detail: the moment the harness needs something the tool surface does not expose, the tool surface
+ * is missing a tool and THAT is the bug. Every capability a harness run proves is one a user's own
+ * agent can reach.
+ */
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { ReticleTool } from '@reticlehq/core';
+import { TOOLS } from './tools.js';
+import { runTool } from './invoke-tool.js';
+import { TOOL_SURFACE, filterTools } from './tool-surface.js';
+import { withTimeout } from '../../features/harness/with-timeout.js';
+/**
+ * The two tools the harness is given beyond the advertised surface.
+ *
+ * Recording is what makes a drive worth paying for twice: a journey the model drove and SAVED
+ * replays deterministically for a few hundred tokens on every future run, and one it merely drove
+ * has to be re-driven by a model every time. Both sit in the extended surface, reachable by an agent
+ * only through a discovery hop — and a hop the model has to take on every journey is a hop it will
+ * sometimes skip, which silently turns the cheap path off.
+ */
+/**
+ * Beyond the default surface, the three tools a drive cannot do its job without.
+ *
+ * RECORD and FLOW_SAVE are how a drive keeps what it drove. FLOW_REPLAY is how it avoids driving
+ * the same thing twice — it was absent, so a driver handed a plan full of already-recorded journeys
+ * had no way to run one, and every run paid a model to rediscover what was on disk.
+ */
+const HARNESS_EXTRA_TOOLS = [
+    ReticleTool.RECORD,
+    ReticleTool.FLOW_SAVE,
+    ReticleTool.FLOW_REPLAY,
+];
+/**
+ * The one deliberate subtraction.
+ *
+ * `reticle_feedback` exists so a human's agent can tell us what is missing. A model driving in a loop
+ * will report its own confusion as a product defect at a rate that would drown the channel it is
+ * meant to protect.
+ */
+const HARNESS_EXCLUDED = new Set([ReticleTool.FEEDBACK]);
+/**
+ * Parameters the model is never asked for, because the harness supplies them.
+ *
+ * `sessionId` is pinned by the run: `invoke` stamps it on every call so a drive that leased one tab
+ * cannot have a tool resolve a different one. Advertising it therefore buys nothing and costs twice —
+ * the same paragraph of prose on every tool on EVERY turn, and a parameter the model can get wrong
+ * in the one place where being wrong means a verdict about the wrong tab.
+ */
+const INJECTED_PARAMS = new Set(['sessionId']);
+/**
+ * How long one tool call may take before the drive gives up on it.
+ *
+ * The engine puts no bound on tool execution and it is right not to: it does not know what its caller
+ * can afford. The harness does. A wedged browser — a Chromium that stops answering CDP, a page in an
+ * infinite layout loop — hangs the call that touches it, and a hung call holds the leased context
+ * exactly like a stalled model turn does.
+ *
+ * A BACKSTOP, not a policy, and deliberately far above any real call: a crawl drives every control on
+ * a page and legitimately takes minutes on a large app, so a tight bound here would not catch a
+ * wedge, it would manufacture one.
+ */
+const TOOL_TIMEOUT_MS = 300_000;
+/** What the MCP SDK passes its own converter, restated so the two surfaces cannot drift apart. */
+const MCP_SCHEMA_OPTIONS = { strictUnions: true, pipeStrategy: 'input' };
+/** Convert one tool's zod shape into the JSON Schema the model wire wants. */
+function toHarnessTool(tool) {
+    const asked = Object.fromEntries(Object.entries(tool.inputSchema).filter(([name]) => !INJECTED_PARAMS.has(name)));
+    return {
+        name: tool.name,
+        description: tool.description,
+        /*
+         * The SAME conversion the MCP layer hands an agent — options included.
+         *
+         * Not a detail: `reticle_act_and_wait`'s `until` is a RECURSIVE predicate (and/or/not nest), and
+         * inlining a recursive schema is impossible, so a converter told not to emit `$ref` quietly
+         * degrades that one parameter to `any`. The model would then be guessing the shape of the single
+         * argument that decides whether a drive proves anything. Definitions and refs are what every
+         * agent driving Reticle over MCP already reads.
+         */
+        inputSchema: zodToJsonSchema(z.object(asked), MCP_SCHEMA_OPTIONS),
+    };
+}
+/**
+ * Bind the live tool surface to a set of dependencies.
+ *
+ * `deps` is the daemon's own dependency bag — the same one the MCP layer dispatches with — so a
+ * harness drive and an agent drive are indistinguishable from inside the engine. That is what makes
+ * a harness run a measurement of the product rather than of a test harness.
+ */
+export function reticleToolset(deps, options = {}) {
+    const usable = TOOLS.filter((tool) => !HARNESS_EXCLUDED.has(tool.name));
+    /**
+     * Everything callable, whether or not it is advertised. `reticle_run` dispatches against this, so
+     * trimming the ADVERTISED list never trims what a drive can reach.
+     */
+    const byName = new Map(usable.map((tool) => [tool.name, tool]));
+    const advertised = options.only === undefined
+        ? [
+            ...filterTools([...usable], TOOL_SURFACE.DEFAULT),
+            ...usable.filter((tool) => HARNESS_EXTRA_TOOLS.includes(tool.name)),
+        ]
+        : usable.filter((tool) => true === options.only?.includes(tool.name));
+    return {
+        tools: advertised.map(toHarnessTool),
+        async invoke(name, args) {
+            const [target, targetArgs] = ReticleTool.RUN === name ? [asName(args['tool']), asArgs(args['args'])] : [name, args];
+            const tool = target === undefined ? undefined : byName.get(target);
+            if (tool === undefined) {
+                // Answered rather than thrown: a model that asked for a name it cannot call needs the live
+                // list, and this is the same recovery the MCP surface gives an agent that does the same.
+                return { error: `unknown tool ${target ?? name}`, available: [...byName.keys()] };
+            }
+            const scoped = pinSession(targetArgs, options.sessionId);
+            return withTimeout(runTool(tool, deps, scoped), TOOL_TIMEOUT_MS, `${tool.name} never returned`);
+        },
+    };
+}
+/**
+ * Stamp the drive's own session onto a call.
+ *
+ * Without it a drive that opened one tab can have a tool resolve a DIFFERENT one — and a verdict
+ * about the wrong tab is the false green this product exists to prevent, arriving through our own
+ * front door. An explicit `sessionId` in the arguments wins: `reticle_sessions` hands the model real
+ * ids, and silently overwriting one would make a deliberate cross-tab call lie about which tab it
+ * read.
+ */
+export function pinSession(args, sessionId) {
+    if (sessionId === undefined || 'sessionId' in args)
+        return args;
+    return { ...args, sessionId };
+}
+function asName(value) {
+    return 'string' === typeof value && value.length > 0 ? value : undefined;
+}
+function asArgs(value) {
+    return 'object' === typeof value && null !== value && !Array.isArray(value)
+        ? value
+        : {};
+}

package/dist/surface/tools/inspect-tool.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDef } from './tool-kit.js';
+/** The error for a ref-less inspect, or `undefined` when a usable ref was given. */
+export declare function missingRefRefusal(args: Record<string, unknown>): Error | undefined;
+export declare const INSPECT_TOOL: ToolDef;

package/dist/surface/tools/inspect-tool.js

@@ -0,0 +1,142 @@
+/**
+ * `reticle_inspect` — everything about one element by ref, and the refusal it owes a caller who
+ * named an element but gave no ref.
+ *
+ * A ref is REQUIRED here, and the merged surface cannot enforce it. `reticle_look` folds four
+ * actions into one tool, so every action's parameters are optional — `page`, `find`, `state` and
+ * `element` want different ones — and the requirement the schema states is lost exactly where an
+ * agent meets it. The empty string then travelled to the browser and came back as "ref '' no longer
+ * resolves to an element / That ref is stale: refs are invalidated whenever the DOM re-renders".
+ * Nothing was stale and nothing re-rendered; there was no ref. The advice sent the reader to
+ * re-snapshot a page that was fine.
+ *
+ * Measured on bench-app with `{ action: "element", testid: "awkward-icon" }`, which is the natural
+ * call: `testid` IS a parameter of `reticle_look` and the sibling `find` action takes one. So the
+ * refusal names that case specifically rather than saying "ref is required" at somebody who did
+ * name the element, just not the way this action wants.
+ */
+import { z } from 'zod';
+import { asString, ReticleCommand, ReticleTool } from '@reticlehq/core';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+/**
+ * The ways `reticle_query` names an element. Used only to tell somebody who reached for one of
+ * these that they named the element the OTHER action's way, rather than naming none.
+ */
+const LOCATOR_ARGS = [
+    'testid',
+    'text',
+    'role',
+    'label',
+    'placeholder',
+    'alt',
+    'name',
+    'value',
+];
+/** The error for a ref-less inspect, or `undefined` when a usable ref was given. */
+export function missingRefRefusal(args) {
+    const ref = asString(args['ref']);
+    if (ref !== undefined && 0 !== ref.length)
+        return undefined;
+    const locator = LOCATOR_ARGS.find((key) => asString(args[key]) !== undefined);
+    const named = locator === undefined
+        ? ''
+        : ` You gave \`${locator}\`, which is how ${ReticleTool.QUERY} finds an element; this call takes the ref that comes back from it.`;
+    return new Error(`${ReticleTool.INSPECT} needs a \`ref\` and none was given, so nothing was inspected.${named} ` +
+        `Get one from ${ReticleTool.QUERY} or ${ReticleTool.SNAPSHOT}, then pass it as \`ref\`.`);
+}
+export const INSPECT_TOOL = {
+    name: ReticleTool.INSPECT,
+    example: { ref: 'e42' },
+    description: 'Deep info on one element by ref: full a11y props, visibility, box, and (with @reticlehq/react) component stack + source file.',
+    inputSchema: {
+        ref: z
+            .string()
+            .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions.`),
+        ...sessionIdShape,
+    },
+    outputSchema: {
+        ref: z.string(),
+        role: z.string(),
+        name: z.string(),
+        value: z.string().optional(),
+        states: z.array(z.string()),
+        visible: z.boolean(),
+        box: z
+            .object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() })
+            .optional(),
+        // True when another element covers this one's center (z-index/overlay bug — unclickable).
+        occluded: z.boolean().optional(),
+        // Computed style the a11y tree omits: cursor/display/visibility/color so a "present but
+        // unusable" UI bug (dead cursor, invisible, recolored) is observable in one inspect.
+        styles: z
+            .object({
+            color: z.string(),
+            backgroundColor: z.string(),
+            opacity: z.string(),
+            cursor: z.string(),
+            display: z.string(),
+            visibility: z.string(),
+        })
+            .partial()
+            .optional(),
+        scroll: z
+            .object({
+            scrollTop: z.number(),
+            scrollHeight: z.number(),
+            clientHeight: z.number(),
+            overflowY: z.string(),
+        })
+            .optional(),
+        // Theme compliance vs the app's design tokens: { colorToken, colorTokens, backgroundToken,
+        // backgroundTokens, offTheme, tokenCount, themeScope }. The plural fields carry EVERY token
+        // matching the resolved colour; the singular ones abstain (null) when several tokens share it,
+        // because returning an arbitrary winner was the defect (#313). `themeScope` names the theme
+        // that was active at capture, so two inspects minutes apart are comparable at all.
+        // Kept as unknown — the structured-content serializer can truncate a large inspect payload's
+        // fields to strings, which a strict shape would reject; the full object is always present in
+        // the text content the agent reads.
+        theme: z.unknown().optional(),
+        /**
+         * Where this element is written, as `file:line`. Present when the app is built with the
+         * Reticle build plugin in dev; absent in production builds.
+         */
+        source: z.string().optional(),
+        /**
+         * Why `source` is missing, when it is.
+         *
+         * Distinguishes "this element has no stamp" from "nothing on this page has one, so the
+         * stamping loader is not running" — the second means `file:line` is unavailable for the
+         * whole session and the fix is a build-config change, which used to be discoverable only by
+         * reading the adapter's own source.
+         */
+        sourceUnavailable: z.string().optional(),
+        /**
+         * Component identity from the framework adapter (@reticlehq/react).
+         *
+         * Declared to match what the handler actually returns. It previously declared
+         * `{ name, sourceFile }` while the runtime returned `{ componentStack, source }` — the SDK
+         * passes structured content through, so the real shape won and the declaration was simply
+         * wrong. An agent reads this schema to decide what to ask for, which makes a wrong schema worse
+         * than a missing one.
+         */
+        component: z
+            .object({
+            componentStack: z.array(z.string()).optional(),
+            source: z
+                .object({ file: z.string(), line: z.number(), column: z.number().optional() })
+                .optional(),
+        })
+            .optional(),
+    },
+    handler: (deps, args) => {
+        // The merged surface makes every action's parameters optional, so this schema's `ref` stops
+        // being required exactly where an agent meets it. See `missingRefRefusal`. Rejected rather
+        // than thrown: a caller holding the promise would never see a synchronous throw.
+        const refusal = missingRefRefusal(args);
+        if (refusal !== undefined)
+            return Promise.reject(refusal);
+        return commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.INSPECT, {
+            ref: asString(args['ref']),
+        });
+    },
+};

package/dist/surface/tools/invoke-tool.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDef, ToolDeps } from './tool-kit.js';
+export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
+/**
+ * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write
+ * disk (capabilities/contract/flow/project), drain a buffer, or steer session lifecycle. They are
+ * exempt from the health splice ON PURPOSE. Kept explicit so the guard test can force every new
+ * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
+ */
+export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
+export declare function runTool<Ext>(tool: ToolDef<Ext>, deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;