@reticlehq/server 2.14.0 → 3.2.0

package/dist/mcp/server-instructions.js

@@ -1,98 +0,0 @@
-import { SHARED_PARAM_GUIDANCE } from './shared-params.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.
- *
- * It used to open on tool grammar. That is the right thing to say to an agent that has an app to
- * point the tools at, and the wrong thing to say to one that does not — and in the field the
- * overwhelming majority of daemons never see an app connect, never run a command and never call a
- * tool. Those sessions are not agents failing a hard step. They are agents that were never asked to
- * take an easy one: the MCP server registers itself in a single line of config, so a user reaches
- * "the tools are here" without ever reaching "the app is wired", and nothing in that state reads as
- * unfinished. Registering the server is the cheapest part of the product and it is the only part
- * many installs ever complete.
- *
- * So the lead is state-dependent. A project that has never had an app connect is told the one thing
- * it needs; 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 for a measured reason. On a HEALTHY app in the competitor benchmark,
- * this agent spent 22 turns and roughly 3.5x the cheapest competitor's tokens confirming that
- * nothing was wrong — and it was not payload, which was the smallest of its five runs. It was
- * turns: three navigations, four queries, a console read, a network read and an assert, on a page
- * whose first verdict had already come back "yes" over a clean capture. Nothing anywhere told it
- * when it was finished. Every other instruction here pushes toward MORE checking, which is right
- * when something is broken and is the whole bill when nothing is.
- *
- * The diagnose-from-source rule has the same provenance and a bigger number behind it. Measured on
- * a fix-and-verify benchmark, split at the call that writes the fix: this agent spent 14 and 18
- * calls BEFORE its first edit where chrome-devtools-mcp spent 8 and 9 — and the sequences say why.
- * It drove the app to understand it (snapshot, act, wait_for, snapshot, act, act_and_wait) and only
- * then opened a file, while the competitor read six files and then looked once. Per-turn cost was
- * IDENTICAL on the hardest cell (22,575 against 22,466), so the whole gap was turns, and most of
- * those turns were spent asking a browser a question that only source can answer.
- */
-/** The tools, and the rule that only two of them decide anything. Constant across both states. */
-const VERDICT_DISCIPLINE = `Reticle verifies a running web app from the inside: go (reticle_navigate), look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_observe / reticle_state / reticle_network / reticle_console), assert (reticle_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 reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ 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.`;
-/**
- * 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 FIRST_MOVE = `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 reticle_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. That is enough to USE and not
- * enough to CHOOSE, and `reticle_observe` is the case that proves it costs something: the
- * measurement recorded on TOOL_SURFACE.VERIFY is that dropping the observation tools TRIPLED false
- * alarms, 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 them without their call shape sent an agent at a
- * tool it could not call, which is worse than silence — it teaches distrust of everything else
- * here. They are now written the way the skill writes them, 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 REACH_FOR = `reticle_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. reticle_wait_for settles a page that is changing without you; reticle_inspect maps an element to its source file:line, which turns a finding into an edit; reticle_session {action:"yield"} hands the tab back to the human.
-
-Everything else is one hop: reticle_tools lists it, reticle_run calls it. Two to know early: reticle_run({ tool: "reticle_context", args: {} }) returns what this run already established, after a compaction or handover, and reticle_run({ tool: "reticle_intent", args: { action: "declare", ... } }) declares what a change was MEANT to do, so the verdict has something to check against other than itself.`;
-/** The feedback ask. Constant: an agent that cannot get set up is the report we most need. */
-const FEEDBACK_ASK = `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 \`reticle_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. Measured on this
- * server: 621 tokens here against 5,480 per turn there, so anything true of every tool belongs in
- * this block rather than repeated across sixteen parameter descriptions. See shared-params.ts.
- */
-export function buildServerInstructions(state) {
-    const base = state.previouslyConnected
-        ? `${VERDICT_DISCIPLINE}\n\n${REACH_FOR}\n\n${FEEDBACK_ASK}`
-        : `${FIRST_MOVE}\n\n${VERDICT_DISCIPLINE}\n\n${FEEDBACK_ASK}`;
-    return `${base}\n\n${SHARED_PARAM_GUIDANCE}`;
-}

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

@@ -1,45 +0,0 @@
-/**
- * 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: 25 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/mcp/tool-catalog-cache.js

@@ -1,77 +0,0 @@
-/**
- * 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: 25 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/memory/memory-tools.d.ts

@@ -1,2 +0,0 @@
-import type { ToolDef } from '../tools/tools.js';
-export declare const MEMORY_TOOLS: ToolDef[];

package/dist/memory/memory-tools.js

@@ -1,82 +0,0 @@
-/**
- * `reticle_memory` — ask the project what it already knows.
- *
- * Shared memory reached three callers before this one: the sync writes it, flow replay consults it
- * automatically, and `reticle memory` prints it at a terminal. The one who could not ask was the
- * agent doing the work — mid-drive, holding a question, with a whole tool surface and nothing on it
- * for "what has this team already established about checkout?".
- *
- * That matters twice over. An agent that can read the corpus stops re-deriving what a colleague
- * proved last week; and because the read is attributed, the coverage map's fetch counts finally
- * measure something — they were zero across an entire real corpus, not because the knowledge was
- * useless but because consulting it was a separate act nobody performed.
- */
-import { z } from 'zod';
-import { ReticleTool } from '../tools/tool-names.js';
-import { countSchema } from '../tools/numeric-bounds.js';
-import { sessionIdShape } from '../tools/tool-kit.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { sessionRoot } from '../project/session-root.js';
-import { MemoryUnavailable, readProjectMemory } from './project-memory.js';
-import { homedir } from 'node:os';
-/**
- * Enough to orient on, not enough to flood a context.
- *
- * A busy subject on a real project runs to dozens of statements; an agent asking a question wants
- * the ones that settle it. `total` always rides along, so the cap is never silent.
- */
-const DEFAULT_LIMIT = 10;
-/** What to do next, per reason. A refusal that does not say how to fix it is a dead end. */
-const ADVICE = {
-    [MemoryUnavailable.NOT_LINKED]: 'this project is not linked to a Reticle workspace, so there is no shared memory to read. Run `npx @reticlehq/server login` in the project to link it.',
-    [MemoryUnavailable.DISABLED]: 'this project is linked but memory sync is turned off in .reticle/cloud.json, so nothing is being shared. Enable `sync.memory` to use it.',
-    [MemoryUnavailable.UNREACHABLE]: 'the workspace could not be reached, or refused the key. Nothing is wrong with this project — try again, or check the link with `reticle status`.',
-};
-export const MEMORY_TOOLS = [
-    {
-        name: ReticleTool.MEMORY,
-        description: 'Ask what THIS PROJECT already knows — the shared memory its team has built up, written by every engineer who verified something and readable by every agent since. Use it BEFORE re-deriving how a feature is supposed to behave: a colleague may already have proved it, and a statement marked `proved` was established by a real verdict rather than written down. With { subject } it narrows to one area (a flow name, or a route like "checkout"); without, it returns across the project. Each entry carries the flow and the source file it is about, so a claim can be checked. The read is recorded as an agent consultation, which is what the dashboard\'s per-flow fetch counts are built from. Returns { subject, known, total } or { error, reason, advice } when this project is not linked to a workspace.',
-        inputSchema: {
-            subject: z
-                .string()
-                .optional()
-                .describe('Narrow to one area — a flow name ("checkout-pay") or a route segment ("issues"). Omit to read across the whole project. Subjects come from the coverage map; an unknown one returns nothing rather than erroring.'),
-            limit: countSchema
-                .optional()
-                .describe(`Most relevant N statements. Defaults to ${String(DEFAULT_LIMIT)}. Proved statements rank first, so a small limit still returns the settled ones. \`total\` always reports the true count.`),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            subject: z.string().nullable().optional(),
-            known: z.array(z.unknown()).optional(),
-            total: z.number().optional(),
-            error: z.string().optional(),
-            reason: z.string().optional(),
-            advice: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            /*
-             * The APP's root, not the daemon's.
-             *
-             * `deps.reticleRoot` is wherever the daemon was launched, which for a user-scoped MCP
-             * registration is almost never the project being driven — so the link file it reads is the
-             * wrong one or absent, and every project silently reads as "not attached". The same defect
-             * has now been fixed three times in this codebase; routing through sessionRoot is what stops
-             * a fourth.
-             */
-            const root = sessionRoot(deps, asString(args['sessionId']));
-            const subject = asString(args['subject']);
-            const result = await readProjectMemory(deps.fs, root, homedir(), process.env, {
-                subject,
-                limit: asNumber(args['limit']) ?? DEFAULT_LIMIT,
-            });
-            if (!result.ok)
-                return {
-                    error: 'no shared memory available for this project',
-                    reason: result.reason,
-                    advice: ADVICE[result.reason],
-                };
-            return { subject: result.subject, known: result.known, total: result.total };
-        },
-    },
-];

package/dist/memory/project-memory.d.ts

@@ -1,33 +0,0 @@
-import type { FileSystemPort } from '../project/fs-port.js';
-/** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
-export declare const MemoryUnavailable: {
-    /** No `.reticle/cloud.json` — this project has never been linked to a workspace. */
-    readonly NOT_LINKED: "not-linked";
-    /** Linked, but the link says not to sync memory. A setting, not a failure. */
-    readonly DISABLED: "memory-sync-disabled";
-    /** The server was reached and said no, or could not be reached at all. */
-    readonly UNREACHABLE: "unreachable";
-};
-export type MemoryUnavailable = (typeof MemoryUnavailable)[keyof typeof MemoryUnavailable];
-export interface KnownThing {
-    statement: string;
-    status: string;
-    flowName: string | null;
-    sourceFile: string | null;
-    subject: string;
-}
-type ProjectMemoryResult = {
-    ok: true;
-    subject: string | null;
-    known: KnownThing[];
-    total: number;
-} | {
-    ok: false;
-    reason: MemoryUnavailable;
-};
-export declare const rankKnown: (things: readonly KnownThing[]) => KnownThing[];
-export declare function readProjectMemory(fs: FileSystemPort, root: string, home: string, env: NodeJS.ProcessEnv, opts: {
-    subject?: string | undefined;
-    limit: number;
-}): Promise<ProjectMemoryResult>;
-export {};

package/dist/oracles/propose-consequences.d.ts

@@ -1,22 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-/**
- * Self-generating oracles, v1. Given the window a recording captured, propose ranked mustHold
- * predicates — the practical answer to "you recorded a flow, now what should it assert?". Ranking
- * follows the moat's tiering: a signal (the app attested it) beats net/state/route (observable
- * consequences) beats presence (a wrong/healed locator can fake it). Deterministic; accepting a
- * proposal is one existing-tool call. The learned RANKING across projects is the paid layer
- * (OSS-VS-SERVER); these local rules are OSS.
- */
-interface ProposedConsequence {
-    /** A predicate object, directly usable as a mustHold. */
-    predicate: Record<string, unknown>;
-    /** Ranking tier: 0 strongest (signal) … 2 weakest (presence). */
-    tier: number;
-    /** Human label for the proposal. */
-    label: string;
-    /** True for presence-only proposals — flagged because they can be faked. */
-    weak: boolean;
-}
-/** Propose ranked consequences from a recorded event window. Deduped; strongest first. */
-export declare function proposeConsequences(events: readonly ReticleEvent[]): ProposedConsequence[];
-export {};

package/dist/oracles/propose-consequences.js

@@ -1,106 +0,0 @@
-import { EventType, PredicateKind } from '@reticlehq/core';
-import { routeOfEvent } from '../events/predicate-route.js';
-const TIER = { SIGNAL: 0, CONSEQUENCE: 1, PRESENCE: 2 };
-function pathname(url) {
-    if (typeof url !== 'string')
-        return undefined;
-    try {
-        return new URL(url, 'http://x').pathname;
-    }
-    catch {
-        return url;
-    }
-}
-/** Propose ranked consequences from a recorded event window. Deduped; strongest first. */
-export function proposeConsequences(events) {
-    const seen = new Set();
-    const proposals = [];
-    const add = (key, proposal) => {
-        if (seen.has(key))
-            return;
-        seen.add(key);
-        proposals.push(proposal);
-    };
-    for (const event of events) {
-        const data = event.data;
-        switch (event.type) {
-            case EventType.SIGNAL: {
-                const name = data['name'];
-                if ('string' === typeof name) {
-                    add(`signal:${name}`, {
-                        predicate: { kind: PredicateKind.SIGNAL, name },
-                        tier: TIER.SIGNAL,
-                        label: `signal "${name}" fires`,
-                        weak: false,
-                    });
-                }
-                break;
-            }
-            case EventType.NET_REQUEST: {
-                const path = pathname(data['url']);
-                const method = 'string' === typeof data['method'] ? data['method'] : 'GET';
-                if (path !== undefined) {
-                    add(`net:${method} ${path}`, {
-                        predicate: {
-                            kind: PredicateKind.NET,
-                            method,
-                            urlContains: path,
-                            status: data['status'],
-                        },
-                        tier: TIER.CONSEQUENCE,
-                        label: `${method} ${path} responds`,
-                        weak: false,
-                    });
-                }
-                break;
-            }
-            case EventType.STATE_CHANGE: {
-                const name = data['name'];
-                if ('string' === typeof name) {
-                    add(`state:${name}`, {
-                        predicate: { kind: PredicateKind.STATE, store: name, path: data['path'] },
-                        tier: TIER.CONSEQUENCE,
-                        label: `state "${name}" changes`,
-                        weak: false,
-                    });
-                }
-                break;
-            }
-            case EventType.ROUTE_CHANGE: {
-                const routed = routeOfEvent(data);
-                if (routed !== undefined) {
-                    // `pathname`, not `to`: the evaluator has never accepted `to`, so this surface was handing
-                    // the agent a predicate reticle_assert refuses with "unknown field to". A proposal that
-                    // cannot be evaluated is worse than no proposal — see the schema check in the test.
-                    //
-                    // And the ROUTER's path, not the document's: under a hash router the document pathname is
-                    // `/` on every page, so proposing it proposes an assertion that says nothing about where
-                    // the app went. See routeOfEvent.
-                    const to = routed.routePath;
-                    add(`route:${to}`, {
-                        predicate: { kind: PredicateKind.ROUTE, pathname: to },
-                        tier: TIER.CONSEQUENCE,
-                        label: `route changes to ${to}`,
-                        weak: false,
-                    });
-                }
-                break;
-            }
-            case EventType.DOM_ADDED: {
-                const name = data['name'];
-                if ('string' === typeof name && name.length > 0) {
-                    add(`presence:${name}`, {
-                        predicate: { kind: PredicateKind.ELEMENT, name },
-                        tier: TIER.PRESENCE,
-                        label: `"${name}" appears (presence only — prefer a consequence)`,
-                        weak: true,
-                    });
-                }
-                break;
-            }
-            default:
-                break;
-        }
-    }
-    return proposals.sort((a, b) => a.tier - b.tier);
-}