@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/mcp/proxy/proxy-log.js

@@ -0,0 +1,117 @@
+/**
+ * The MCP proxy's own log file: where it lives, what bounds it, and how it is written.
+ *
+ * Split out of mcp-proxy.ts, which is the transport. This is housekeeping for a file, and the two
+ * share nothing but a port number — the proxy calls `proxyLog`, and everything else here exists to
+ * keep that file from becoming the largest thing on the user's disk.
+ */
+import { appendFileSync, mkdirSync, renameSync, statSync, truncateSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { log } from '../../../log.js';
+import { MAX_DAEMON_LOG_BYTES, recoverOversizedLog, rotateDaemonLog, } from '../../../command/daemon/daemon.js';
+/**
+ * Which port this proxy serves, for the log file name. Set once at startup.
+ *
+ * One file per port, matching `daemon-<port>.log`. A single shared file interleaved every proxy on
+ * the machine into one stream, so the first question anyone asks of it — "what happened to MY
+ * session?" — needed a filter before it could be answered.
+ */
+let logPort;
+/**
+ * How much the proxy may append between size checks.
+ *
+ * Statting the file on every line would be a syscall per log line on a process that logs from a
+ * reconnect loop. Counting what we wrote costs nothing and is exact enough, because this process is
+ * the only writer of its own log. Well under the cap, so the cap is a cap rather than a suggestion.
+ */
+export const PROXY_LOG_CHECK_BYTES = 256 * 1024;
+/** Appended since the last real size check. Reset by every check, whatever the check decides. */
+let bytesSinceProxyLogCheck = 0;
+/**
+ * Keep the proxy log under the same cap as the daemon log, without a stat per write.
+ *
+ * Returns the new "bytes since the last check" counter, so the accounting is testable without a
+ * filesystem. Rotation itself is `rotateDaemonLog` — the proxy log had no cap at all while the
+ * daemon log on the SAME machine stayed small, which is the whole of this defect.
+ */
+export function accountProxyLogWrite(bytesSinceCheck, written, path, deps) {
+    const total = bytesSinceCheck + written;
+    if (PROXY_LOG_CHECK_BYTES > total)
+        return total;
+    rotateDaemonLog(path, deps);
+    return 0;
+}
+/**
+ * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
+ *
+ * Path-shaped wrapper over `recoverOversizedLog`, which is where the rule, the in-place truncation
+ * and the ENOSPC incident behind them are written down. Both of Reticle's logs are capped by that
+ * one function; this keeps the name and the `fileSize`/`truncateFile` deps its callers already pass.
+ *
+ * Such files already exist on machines that ran an older build, and the cap alone does not help
+ * them: nobody should have to find one with `du`.
+ */
+export function recoverOversizedProxyLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
+    return recoverOversizedLog({ size: () => deps.fileSize(path), truncate: () => deps.truncateFile(path) }, max);
+}
+/** The real filesystem behind the two rotation helpers. */
+const proxyLogFileOps = {
+    fileSize: (p) => statSync(p).size,
+    renameFile: (from, to) => renameSync(from, to),
+    truncateFile: (p) => truncateSync(p, 0),
+};
+/** Name the proxy log after the port it serves. Called before anything can log. */
+export function setProxyLogPort(port) {
+    logPort = port;
+    // The one moment we know a size check is worth its syscall, and the only place a file inherited
+    // from an older build can be brought back under control.
+    const reclaimed = recoverOversizedProxyLog(proxyLogPath(port), proxyLogFileOps);
+    if (0 < reclaimed) {
+        proxyLog('reticle_mcp_proxy_log_truncated', {
+            port,
+            reclaimedBytes: reclaimed,
+            note: 'the proxy log had grown past its cap and was truncated in place to reclaim the space',
+        });
+    }
+}
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export function proxyLogPath(port = logPort) {
+    const name = port === undefined ? 'mcp-proxy.log' : `proxy-${String(port)}.log`;
+    return join(homedir(), ReticleDir.ROOT, name);
+}
+/**
+ * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
+ * does not. A dropped MCP connection is invisible from the agent's side — no message, no exit code —
+ * so the one thing that makes it diagnosable at all is a file somebody can read afterwards.
+ *
+ * EXPORTED because the crash handlers need it. `installProxyResilience` was wired to the bare stderr
+ * logger, so the proxy's own uncaught exceptions and unhandled rejections — the exact events that
+ * present to a human as "the MCP server disconnected" — were written to a stream the editor throws
+ * away. The handler ran, the process kept serving, and the reason went nowhere. Reported as "the
+ * proxy has no log file… when it dies the diagnostic dies with it", which was half right: the file
+ * existed, and the one path that most needed it was not using it.
+ */
+export function proxyLog(event, fields = {}) {
+    log(event, fields);
+    try {
+        const dir = join(homedir(), ReticleDir.ROOT);
+        mkdirSync(dir, { recursive: true });
+        // WITH A TIMESTAMP. This file is the only record of an outage that survives the session, and
+        // without one it cannot answer the two questions anyone brings to it: when did this happen, and
+        // how often. A real 3,283-line log on a dev machine held a `gave_up` — the exact event that used
+        // to precede `process.exit(1)` and cost the human a manual /mcp reconnect — and it was
+        // impossible to tell whether it happened during that person's work or a test run hours earlier.
+        // Evidence you cannot place in time is an anecdote.
+        const path = proxyLogPath();
+        const line = `${JSON.stringify({ t: new Date().toISOString(), event, ...fields })}\n`;
+        appendFileSync(path, line, 'utf8');
+        // A single proxy process is long-lived and logs from a reconnect loop, so rotating only at
+        // startup would leave the growth this file is capable of entirely unchecked while it runs.
+        bytesSinceProxyLogCheck = accountProxyLogWrite(bytesSinceProxyLogCheck, Buffer.byteLength(line, 'utf8'), path, proxyLogFileOps);
+    }
+    catch {
+        // Logging must never be the thing that kills the proxy.
+    }
+}

package/dist/surface/mcp/server-instructions.d.ts

@@ -0,0 +1,26 @@
+interface InstructionState {
+    /**
+     * The names this surface actually advertises. Every tool the prose mentions is resolved from it.
+     *
+     * Optional so the two proxy call sites, which brief before a daemon has answered, keep the shipped
+     * default — but a daemon that knows its surface MUST pass it, or it briefs an agent on a product it
+     * is not serving.
+     */
+    advertised?: readonly string[];
+    /**
+     * Has an app ever connected to Reticle for this project, on this port?
+     *
+     * Read from the durable connection memory rather than from the live session list: a daemon four
+     * seconds old has no sessions and that says nothing about whether the app is wired. The question
+     * is whether this install has EVER worked, not whether it is working this second.
+     */
+    previouslyConnected: boolean;
+}
+/** The instructions this daemon should advertise, given what it knows about the project. */
+/**
+ * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn, and costs an
+ * order of magnitude more for it. So anything true of every tool belongs in this block rather than
+ * repeated across every parameter description. See shared-params.ts.
+ */
+export declare function buildServerInstructions(state: InstructionState): string;
+export {};

package/dist/surface/mcp/server-instructions.js

@@ -0,0 +1,156 @@
+import { ReticleTool } from '@reticlehq/core';
+import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
+import { defaultAdvertisedNames } from '../tools/tool-surface.js';
+import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
+/**
+ * What every connected agent is told, before it has asked anything.
+ *
+ * The MCP `instructions` string lands in the agent's context at the handshake — no skill file, no
+ * restart, no action from the user. For an agent that arrived through a plugin listing or a pasted
+ * config block rather than through the skill, it is the ONLY thing Reticle ever says unprompted.
+ *
+ * The lead is state-dependent, because registering the MCP server and instrumenting an app are two
+ * separate acts and only the first is a single line of config. A user therefore reaches "the tools
+ * are here" without reaching "the app is wired", and nothing in that state reads as unfinished. So a
+ * project that has never had an app connect is told the one thing it needs, and a project that has is
+ * not nagged about a step it already took. The verdict discipline and the feedback ask are constant,
+ * because they matter in both states.
+ *
+ * The stopping rule is here because every OTHER instruction pushes toward more checking — which is
+ * right when something is broken, and is the whole bill when nothing is. Without it an agent will
+ * keep driving a page whose first verdict already came back "yes" over a clean capture.
+ *
+ * The diagnose-from-source rule is here because driving the app cannot answer a question only the
+ * source can. An agent that explores to UNDERSTAND the code, rather than to confirm a fix, spends its
+ * turns asking a browser about intent.
+ */
+/**
+ * The tools, and the rule that only two of them decide anything.
+ *
+ * Every tool named here is resolved from the LIVE surface — see surface-vocabulary.ts for the
+ * measured reason. A briefing that names a tool the agent was not given does not merely confuse it;
+ * it makes the agent stop using the product altogether.
+ */
+const verdictDiscipline = (v) => `Reticle verifies a running web app from the inside: go (${v.navigate}), look (${listOf(v.look, v.find)}), act and prove in one hop (${v.actAndWait}), observe (${listOf(v.observe, v.state, v.network, v.console)}), assert (${v.assert}). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+
+Only ${v.actAndWait} and ${v.assert} produce a verdict. ${v.act.length > 0 ? `${v.act} and e` : 'E'}verything else moves or reads the app and proves nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer ${v.actAndWait}({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.
+
+A "yes" over a clean capture IS the answer — re-reading the page after one finds the same state. When every consequence you set out to check has one, stop.
+
+DIAGNOSING a bug? Read the source first — Reticle proves what the app DOES, not why. Drive to CONFIRM a fix, not to find one.`;
+/**
+ * Replay before you drive, when a saved flow already covers the change.
+ *
+ * WHY THIS IS IN THE BRIEFING AND NOT IN A TOOL DESCRIPTION. Across a whole bench run with saved
+ * flows on disk for every cell, replay was invoked ZERO times. Coverage was never the problem — the
+ * daemon saves a flow from every drive at teardown, so it accumulates whether or not anybody asks.
+ * `reticle_verify` carries the whole explanation in its own description, and every shipping surface
+ * trims that description down to one line, which removes every mention of flows. A rule that must
+ * survive the trim has to be here.
+ *
+ * THE ORDER IS THE POINT. Replaying after a drive proves nothing the drive did not already prove,
+ * and the drive is already paid for. The saving is avoided TURNS — orders of magnitude, driving a
+ * journey against replaying it — and it only exists if the question is asked BEFORE the browser is
+ * opened.
+ *
+ * `unknown` is load-bearing and is stated explicitly. It means no saved flow covers this change, so
+ * nothing ran and nothing was proved — and an agent that reads it as "fine" has turned the cheapest
+ * path into a false green, which is the one failure this product exists to prevent. It is the
+ * trigger to drive, never a pass.
+ *
+ * Every call is resolved from the LIVE surface, and the section disappears entirely when the surface
+ * cannot reach any of them. Naming a tool the agent was not given is the failure this module's own
+ * header warns about.
+ */
+const replayFirst = (v) => {
+    if (0 === v.replayChange.length)
+        return '';
+    const ask = v.affected.length > 0 ? `${v.affected} names the saved flows covering your edits; ` : '';
+    return `Changed code? Replay before you drive. ${ask}${v.replayChange} replays them for one verified + because — hundreds of tokens where driving the same journey costs tens of thousands. "yes": proved, stop. "no": names the step that broke. "unknown": NO saved flow covers it, so nothing was proved — drive it, and never report it as passing. What you drive by hand is saved as a flow automatically.`;
+};
+/**
+ * The first move, for a project no app has ever connected to.
+ *
+ * Deliberately concrete: the command, what it does to the app, and the call that confirms it. A
+ * general instruction to "set Reticle up" is the state these agents are already in — they have the
+ * tools and no app, and nothing tells them that combination is incomplete. It also names the dev
+ * server restart, because a plugin added to a config the running server already read is the single
+ * most common way this step half-succeeds.
+ */
+const firstMoveFor = (v) => `FIRST: no app has ever connected to Reticle in this project, so nothing here can be verified yet. Having these tools is not the same as being set up — the tools reach a daemon, and the daemon has nothing to look at until the app itself is instrumented.
+
+Fix that before anything else: run \`npx @reticlehq/server init\` in the project, then RESTART the dev server (a plugin added to a config the running server already read is not in the bundle), then load the app in a browser. Confirm with ${v.sessions} — a session listed there is the proof, and until one appears no other tool can tell you anything about this app.`;
+/**
+ * When to reach for the tools that are advertised but never explained, and how to reach the two
+ * that are explained but not advertised. Both halves of the same defect.
+ *
+ * An advertised tool arrives as a name and one line of description: enough to USE, not enough to
+ * CHOOSE. `reticle_observe` is where that costs something — dropping the observation tools TRIPLES
+ * false alarms (see TOOL_SURFACE.VERIFY), because the model stops observing and reaches for the
+ * verdict without the evidence. So observe gets a reason, not a listing.
+ *
+ * The other direction: `reticle_context` and `reticle_intent` sit on the EXTENDED surface, so they
+ * are not in the list an agent is handed. Naming one without its call shape points the agent at a
+ * tool it cannot call, which is worse than silence — it teaches distrust of everything else here. So
+ * they are written as the `reticle_run` call that works.
+ *
+ * Only in the connected state, and that is not a budget trick: an agent whose app has never
+ * connected has nothing to observe, no run to carry forward and nothing to declare an intent
+ * against. Its one instruction is the first move, and adding a second would compete with it.
+ */
+const reachFor = (v) => {
+    const lines = [
+        `${v.observe} is the evidence channel: everything the page did since a cursor, in one read. Take it BEFORE you call a build broken — measured, stripping the observation tools TRIPLED false alarms, because an agent that stops observing reaches for the verdict without the evidence. ${v.settle} settles a page that is changing without you; ${v.inspect} maps an element to its source file:line, which turns a finding into an edit${v.yield.length > 0 ? `; ${v.yield} hands the tab back to the human` : ''}.`,
+    ];
+    // Said ONLY when both halves are advertised. A catalogue with no way to invoke what it lists sends
+    // the agent at a tool it cannot call and then off the product entirely — see
+    // surface-vocabulary.ts. Where there is no cold tail, there is nothing to say about reaching it.
+    if (v.coldTail.length > 0) {
+        lines.push(`${v.coldTail} Two to know early: ${ReticleTool.RUN}({ tool: "${ReticleTool.CONTEXT}", args: {} }) returns what this run already established, after a compaction or handover, and ${ReticleTool.RUN}({ tool: "${ReticleTool.INTENT}", args: { action: "declare", ... } }) declares what a change was MEANT to do, so the verdict has something to check against other than itself.`);
+    }
+    return lines.join('\n\n');
+};
+/** The feedback ask. Constant: an agent that cannot get set up is the report we most need. */
+const feedbackAsk = (v) => `Feedback is first-class here, not a courtesy. Reticle is built FOR agents, so your experience is the only signal that decides what gets built or fixed — and it disappears when your context does. Send it with \`${v.feedback}\` the moment you notice, then carry on with your task:
+- Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
+- You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
+- The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
+
+Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <one of those kinds> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
+/** The instructions this daemon should advertise, given what it knows about the project. */
+/**
+ * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn, and costs an
+ * order of magnitude more for it. So anything true of every tool belongs in this block rather than
+ * repeated across every parameter description. See shared-params.ts.
+ */
+export function buildServerInstructions(state) {
+    // Defaults to the surface this package ships, so the two proxy callers — which brief an agent
+    // before any daemon has answered — keep working unchanged.
+    // The two meta-tools are added by `buildDynamicTools`, not by the surface filter, so they are
+    // absent from CORE_TOOL_NAMES — and without them the cold-tail sentence goes silent on the very
+    // surface that has a cold tail. The default surface always carries both.
+    // The fallback is the LIVE default surface, never a hardcoded list. The proxy briefs WITHOUT
+    // passing a surface, so a stale fallback here is what every agent reaching Reticle through
+    // `reticle mcp` reads — naming tools the surface it is being served does not have.
+    const v = surfaceVocabulary(state.advertised ?? defaultAdvertisedNames());
+    const firstMove = firstMoveFor(v);
+    /*
+     * Said in BOTH states, and gated only on whether the surface can reach replay.
+     *
+     * NOT gated on `previouslyConnected`, though replay presupposes saved flows: that flag needs
+     * `readProjectId(cwd)` to resolve, and in a monorepo where the agent runs from the repo root and
+     * the app lives in a subdirectory it returns undefined. The rule would be absent exactly where it
+     * is most needed, and reach is the entire problem it exists to fix.
+     *
+     * It is safe to say with no flows, because the tool is honest without help: `affected` names
+     * nothing, `change` answers `unknown`, and `unknown` already means "drive it" — which is what a
+     * first-time reader should do anyway. The advice degrades into the correct first move rather than
+     * into a dead end.
+     */
+    const replay = replayFirst(v);
+    const base = state.previouslyConnected
+        ? `${verdictDiscipline(v)}\n\n${reachFor(v)}\n\n${feedbackAsk(v)}`
+        : `${firstMove}\n\n${verdictDiscipline(v)}\n\n${feedbackAsk(v)}`;
+    const withReplay = replay.length > 0 ? `${base}\n\n${replay}` : base;
+    return `${withReplay}\n\n${SHARED_PARAM_GUIDANCE}`;
+}

package/dist/surface/mcp/surface-vocabulary.d.ts

@@ -0,0 +1,47 @@
+/**
+ * How to CALL each job, on whichever surface is live.
+ *
+ * The instructions are the first thing an agent reads, so naming tools in prose makes the sentence
+ * and the live surface two independent facts. On a trimmed surface the briefing named tools that did
+ * not exist there, and `reticle_tools` catalogued dozens more that could not be called: an agent
+ * handed that tries a tool it was shown, fails, tries again, and stops using the product — which
+ * reads as a token saving, because a product nobody uses is cheap.
+ *
+ * `surface-coherence.test.ts` checks the documents against `CORE_TOOL_NAMES`, so it is blind to every
+ * surface but the default and cannot catch this by itself.
+ *
+ * So the names are DERIVED here from the advertised set, and the prose asks for a job rather than a
+ * tool. A briefing that names a tool the agent was not given is unrepresentable rather than merely
+ * tested for.
+ */
+export interface SurfaceVocabulary {
+    navigate: string;
+    look: string;
+    find: string;
+    inspect: string;
+    state: string;
+    observe: string;
+    network: string;
+    console: string;
+    assert: string;
+    settle: string;
+    sessions: string;
+    actAndWait: string;
+    act: string;
+    /** `reticle_session {action:"yield"}`, or empty where the surface has no session tool. */
+    yield: string;
+    feedback: string;
+    /** The discovery sentence, or empty when this surface advertises everything it can call. */
+    coldTail: string;
+    /** Which saved flows cover an edit, or empty when this surface cannot ask. */
+    affected: string;
+    /** Replay the flows an edit touches and answer with a verdict, or empty. */
+    replayChange: string;
+    /** Replay every saved flow for one suite verdict, or empty. */
+    replayAll: string;
+    /** Rebind a drifted locator, or empty when the surface cannot reach it. */
+    heal: string;
+}
+/** Drop the empty slots, so a sentence never reads "look (), find ()". */
+export declare function listOf(...calls: readonly string[]): string;
+export declare function surfaceVocabulary(advertisedNames: readonly string[]): SurfaceVocabulary;

package/dist/surface/mcp/surface-vocabulary.js

@@ -0,0 +1,56 @@
+import { ReticleTool } from '@reticlehq/core';
+/** `reticle_look { action: "find" }` when the family is merged, `reticle_query` when it is not. */
+function callOf(advertised, direct, parent, action) {
+    if (advertised.has(direct))
+        return direct;
+    if (advertised.has(parent))
+        return `${parent} {action:"${action}"}`;
+    // Neither is advertised. Say nothing rather than name a tool the agent cannot call — an empty
+    // slot costs a capability the agent has to discover; a wrong name costs the whole product.
+    return '';
+}
+/** Drop the empty slots, so a sentence never reads "look (), find ()". */
+export function listOf(...calls) {
+    return calls.filter((call) => call.length > 0).join(' / ');
+}
+export function surfaceVocabulary(advertisedNames) {
+    const advertised = new Set(advertisedNames);
+    const call = (direct, parent, action) => callOf(advertised, direct, parent, action);
+    return {
+        navigate: call(ReticleTool.NAVIGATE, ReticleTool.NAVIGATE, 'go'),
+        look: call(ReticleTool.SNAPSHOT, ReticleTool.LOOK, 'page'),
+        find: call(ReticleTool.QUERY, ReticleTool.LOOK, 'find'),
+        inspect: call(ReticleTool.INSPECT, ReticleTool.LOOK, 'element'),
+        state: call(ReticleTool.STATE, ReticleTool.LOOK, 'state'),
+        observe: call(ReticleTool.OBSERVE, ReticleTool.OBSERVE, 'events'),
+        network: call(ReticleTool.NETWORK, ReticleTool.OBSERVE, 'network'),
+        console: call(ReticleTool.CONSOLE, ReticleTool.OBSERVE, 'console'),
+        assert: call(ReticleTool.ASSERT, ReticleTool.ASSERT, 'now'),
+        settle: call(ReticleTool.WAIT_FOR, ReticleTool.ASSERT, 'wait'),
+        sessions: call(ReticleTool.SESSIONS, ReticleTool.SESSION, 'list'),
+        actAndWait: ReticleTool.ACT_AND_WAIT,
+        act: advertised.has(ReticleTool.ACT) ? ReticleTool.ACT : '',
+        yield: advertised.has(ReticleTool.SESSION) ? `${ReticleTool.SESSION} {action:"yield"}` : '',
+        feedback: call(ReticleTool.FEEDBACK, ReticleTool.SESSION, 'feedback'),
+        // Only said when it is TRUE. `reticle_tools` without `reticle_run` is a catalogue of names
+        // nothing can invoke, which is the trap this whole module was written after.
+        coldTail: advertised.has(ReticleTool.TOOLS) && advertised.has(ReticleTool.RUN)
+            ? `Everything else is one hop: ${ReticleTool.TOOLS} lists it, ${ReticleTool.RUN} calls it.`
+            : '',
+        /*
+         * The replay route, resolved like every other call here.
+         *
+         * These four were the only capability the briefing never mentioned, and the omission was
+         * MEASURED rather than suspected: across 13 agent cells and 323 tool calls, with 29 saved flows
+         * sitting on disk the whole time, replay was invoked zero times. Nothing told the agent it
+         * existed. `reticle_verify`'s own description carries the full explanation — and both shipping
+         * surfaces trim it from 1,791 characters to 93, which deletes every word about flows. A rule
+         * that has to survive that trim cannot live in a tool description; it lives here, where the
+         * string is sent once per session and never trimmed.
+         */
+        affected: call(ReticleTool.AFFECTED, ReticleTool.VERIFY, 'affected'),
+        replayChange: call(ReticleTool.VERIFY_CHANGE, ReticleTool.VERIFY, 'change'),
+        replayAll: call(ReticleTool.FLOW_REPLAY, ReticleTool.VERIFY, 'flows'),
+        heal: advertised.has(ReticleTool.FLOW_HEAL) ? ReticleTool.FLOW_HEAL : '',
+    };
+}

package/dist/surface/mcp/tool-catalog-cache.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The tool catalog the proxy has already seen, so a locally-answered handshake is not toolless.
+ *
+ * When the daemon does not answer in time the proxy answers `initialize` itself — a hang gives the
+ * agent no tools AND no diagnosis, so that is right. But it left the client CONNECTED WITH NO TOOLS,
+ * because `tools/list` then had nothing behind it. Measured over one editor session: many stream drops,
+ * 11 dormant, 4 reconnects, 4 local handshakes — and each of those four is a state where a human has
+ * to notice and reconnect by hand.
+ *
+ * Every `tools/list` response the daemon has ever sent passes through this proxy, so the catalog is
+ * already in hand. Serving it back is the difference between "Reticle is here but useless" and
+ * "Reticle is here, and the first call will tell you what is wrong".
+ *
+ * In-memory and per-process on purpose: a catalog persisted from a different Reticle version would be
+ * its own confidently-wrong answer, and a proxy that has never seen one has nothing honest to serve —
+ * so it says nothing rather than inventing a list the agent would then call into.
+ */
+/**
+ * Is this client line a request for the tool list?
+ *
+ * Lives here because this module already owns the method name and the tolerant parse. The caller is
+ * the proxy's stdin reader, which records the arrival as the one observable fact behind `reticle
+ * status`'s "registered, never enumerated" state — see attach-memory.ts.
+ */
+export declare function isToolsListRequest(line: string): boolean;
+/**
+ * Is this line a client CALLING a tool?
+ *
+ * The one fact that separates a working agent link from a merely-registered one. Listing the tools
+ * proves a client read the catalogue; it proves nothing about whether a request can cross to the
+ * daemon, and the field reports those two states looking identical from every other angle.
+ */
+export declare function isToolCallRequest(line: string): boolean;
+export declare class ToolCatalogCache {
+    #private;
+    /** Watch a line coming BACK from the daemon; remember it if it is a tool catalog. */
+    observe(line: string): void;
+    has(): boolean;
+    /**
+     * A response to `request` from the cached catalog, or null when this is not a tools/list request or
+     * nothing has been cached. The response carries the CALLER'S id — a JSON-RPC reply under any other
+     * id is not an answer, it is noise the client will never match.
+     */
+    answer(request: string): string | null;
+}

package/dist/surface/mcp/tool-catalog-cache.js

@@ -0,0 +1,77 @@
+/**
+ * The tool catalog the proxy has already seen, so a locally-answered handshake is not toolless.
+ *
+ * When the daemon does not answer in time the proxy answers `initialize` itself — a hang gives the
+ * agent no tools AND no diagnosis, so that is right. But it left the client CONNECTED WITH NO TOOLS,
+ * because `tools/list` then had nothing behind it. Measured over one editor session: many stream drops,
+ * 11 dormant, 4 reconnects, 4 local handshakes — and each of those four is a state where a human has
+ * to notice and reconnect by hand.
+ *
+ * Every `tools/list` response the daemon has ever sent passes through this proxy, so the catalog is
+ * already in hand. Serving it back is the difference between "Reticle is here but useless" and
+ * "Reticle is here, and the first call will tell you what is wrong".
+ *
+ * In-memory and per-process on purpose: a catalog persisted from a different Reticle version would be
+ * its own confidently-wrong answer, and a proxy that has never seen one has nothing honest to serve —
+ * so it says nothing rather than inventing a list the agent would then call into.
+ */
+const LIST_METHOD = 'tools/list';
+function parse(line) {
+    try {
+        const value = JSON.parse(line);
+        return 'object' === typeof value && value !== null ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is this client line a request for the tool list?
+ *
+ * Lives here because this module already owns the method name and the tolerant parse. The caller is
+ * the proxy's stdin reader, which records the arrival as the one observable fact behind `reticle
+ * status`'s "registered, never enumerated" state — see attach-memory.ts.
+ */
+export function isToolsListRequest(line) {
+    return parse(line)?.method === LIST_METHOD;
+}
+/** The JSON-RPC method a client sends to actually USE a tool, as opposed to listing them. */
+const CALL_METHOD = 'tools/call';
+/**
+ * Is this line a client CALLING a tool?
+ *
+ * The one fact that separates a working agent link from a merely-registered one. Listing the tools
+ * proves a client read the catalogue; it proves nothing about whether a request can cross to the
+ * daemon, and the field reports those two states looking identical from every other angle.
+ */
+export function isToolCallRequest(line) {
+    return parse(line)?.method === CALL_METHOD;
+}
+export class ToolCatalogCache {
+    #tools;
+    /** Watch a line coming BACK from the daemon; remember it if it is a tool catalog. */
+    observe(line) {
+        const msg = parse(line);
+        const tools = msg?.result?.tools;
+        if (Array.isArray(tools) && tools.length > 0)
+            this.#tools = tools;
+    }
+    has() {
+        return this.#tools !== undefined;
+    }
+    /**
+     * A response to `request` from the cached catalog, or null when this is not a tools/list request or
+     * nothing has been cached. The response carries the CALLER'S id — a JSON-RPC reply under any other
+     * id is not an answer, it is noise the client will never match.
+     */
+    answer(request) {
+        if (this.#tools === undefined)
+            return null;
+        const msg = parse(request);
+        if (msg?.method !== LIST_METHOD)
+            return null;
+        if (msg.id === undefined || null === msg.id)
+            return null;
+        return JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { tools: this.#tools } });
+    }
+}

package/dist/surface/tools/act/act-danger.js

@@ -0,0 +1,69 @@
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, } from '@reticlehq/core';
+import { asRecord, asString } from '@reticlehq/core';
+/**
+ * Refuse to drive a money-moving or destructive control by accident.
+ *
+ * A native click is indistinguishable from a user's, so an agent exploring an unfamiliar app can
+ * refund a payment or delete an account while "just looking". The guard reads every text surface the
+ * control exposes — its name, its text, its value, where it points, and the form it submits — because
+ * a button labelled only with an icon still says what it does through its `formAction`.
+ *
+ * Opt in per action with `args.confirmDangerous: true`. Deliberately a THROW rather than a warning:
+ * a caller that has not thought about it must not proceed by ignoring a field.
+ */
+function descriptorText(value) {
+    const descriptor = asRecord(value);
+    return [
+        asString(descriptor['name']) ?? '',
+        asString(descriptor['text']) ?? '',
+        asString(descriptor['value']) ?? '',
+        asString(descriptor['href']) ?? '',
+        asString(descriptor['formAction']) ?? '',
+        asString(descriptor['formText']) ?? '',
+    ].join(' ');
+}
+function descriptorRole(value) {
+    const role = asString(asRecord(value)['role']);
+    return role !== undefined && role.length > 0 ? role : undefined;
+}
+function isDestructiveDescriptor(value) {
+    return isDangerousActionText(descriptorText(value), descriptorRole(value));
+}
+export function assertNotDestructive(action, innerArgs, inspected) {
+    if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
+        return;
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+        return;
+    if (!isDestructiveDescriptor(inspected))
+        return;
+    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+}
+/**
+ * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
+ * source alone never says so. Each end is classified on its own text and role, so a Payment
+ * option dragged onto Save is not a payment.
+ */
+export function assertDragNotDestructive(innerArgs, from, to) {
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+        return;
+    if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to))
+        return;
+    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+}
+/**
+ * `reticle_act_and_wait` cannot drive native input, and used to take `args.native` and ignore it.
+ *
+ * An open `args` passthrough accepted the field, the handler drove the page through the SDK anyway,
+ * and the result claimed success — so an agent asking for the one thing a synthetic click cannot do
+ * (a file picker, the clipboard, an `isTrusted`-gated handler) got a synthetic click and no hint
+ * that its request had been dropped. A silently ignored argument is a false promise; refusing with
+ * the route that DOES work is the honest answer.
+ */
+export const NATIVE_INPUT_UNSUPPORTED = `reticle_act_and_wait cannot drive native input, so args.${NATIVE_INPUT_ARG} would be ignored. ` +
+    `Use reticle_act { args: { ${NATIVE_INPUT_ARG}: true } } for the trusted click, then assert the ` +
+    'consequence with reticle_assert / reticle_observe using the `since` cursor it returns.';
+/** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
+export function assertNativeInputSupported(innerArgs) {
+    if (true === innerArgs[NATIVE_INPUT_ARG])
+        throw new Error(NATIVE_INPUT_UNSUPPORTED);
+}

package/dist/surface/tools/act/act-helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure coercion + grading helpers behind the act tools.
+ *
+ * Split out when act-tools.ts crossed the 600-line cap. The seam is that nothing here touches a
+ * session, a command, or a tool definition — these are total functions over their arguments, which
+ * is why they can be tested without a browser and why they were the right thing to move.
+ */
+import { ActionType } from '@reticlehq/core';
+import type { ElementBox } from '../../../portal/input/real-input.js';
+import { HonestyGrade } from '@reticlehq/engine/evidence/honesty.js';
+import type { ExpectedLink } from '../../../judgement/capsule/divergence.js';
+/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
+export declare function gradeOf(links: readonly ExpectedLink[]): HonestyGrade;
+/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
+export declare function asBox(value: unknown): ElementBox | undefined;
+/** Outcome of a real-input attempt — real success (result set) or synthetic with a reason. */
+export declare function asActionType(value: unknown): ActionType | undefined;