@reticlehq/server 2.2.1 → 2.4.0

package/dist/cloud-cli.d.ts

@@ -1,4 +1,3 @@
 export declare const isCloudCommand: (cmd: string | undefined) => boolean;
 /** Dispatch a cloud subcommand. Returns the process exit code. */
 export declare const runCloudCommand: (argv: readonly string[]) => Promise<number>;
-//# sourceMappingURL=cloud-cli.d.ts.map

package/dist/cloud-cli.js

@@ -102,7 +102,15 @@ const api = async (method, url, token, body) => {
         init.body = JSON.stringify(body);
     const res = await fetch(url, init);
     const text = await res.text();
-    const json = text.length > 0 ? JSON.parse(text) : null;
+    let json = null;
+    if (text.length > 0) {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`expected JSON from ${method} ${url} but got: ${text.slice(0, 120)}`);
+        }
+    }
     if (!res.ok) {
         const parsed = z.object({ error: z.object({ message: z.string() }) }).safeParse(json);
         throw new Error(parsed.success ? parsed.data.error.message : `${res.status} ${res.statusText}`);
@@ -504,4 +512,3 @@ export const runCloudCommand = async (argv) => {
         return 1;
     }
 };
-//# sourceMappingURL=cloud-cli.js.map

package/dist/crawl/crawl-tools.d.ts

@@ -5,4 +5,3 @@ import type { ToolDef } from '../tools/tools.js';
  * it drives the app — so it's an explicit, bounded tool, never part of a passive read.
  */
 export declare const CRAWL_TOOLS: ToolDef[];
-//# sourceMappingURL=crawl-tools.d.ts.map

package/dist/crawl/crawl-tools.js

@@ -11,7 +11,7 @@ const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export const CRAWL_TOOLS = [
     {
         name: ReticleTool.CRAWL,
-        description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script: console errors, failed requests (status ≥ 400), and DEAD controls (dispatched but the app did nothing). DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
+        description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script. Two classes: single-channel faults (console errors, failed requests ≥400, DEAD controls that dispatched but did nothing) and CONTRADICTIONS — two channels disagreeing about the same click, e.g. the UI advanced while its write failed, a success signal fired over a failed request, a write succeeded and nothing changed, the same write fired twice, or the UI moved on over an in-flight request. Contradictions are the false greens a human cannot see, because a human watches one channel (the screen) and it looks correct. DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
         inputSchema: {
             maxSteps: z.number().optional().describe('Maximum number of controls to click. Default: 25.'),
             settleMs: z
@@ -70,4 +70,3 @@ export const CRAWL_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=crawl-tools.js.map

package/dist/crawl/crawl.d.ts

@@ -1,4 +1,4 @@
-import { CrawlAnomalyKind, type CommandResult, type ReticleEvent } from '@reticlehq/core';
+import { CrawlAnomalyKind, ContradictionKind, type CommandResult, type ReticleEvent } from '@reticlehq/core';
 /** The slice of Session the crawler needs — so tests inject a fake without a live browser. */
 export interface CrawlSession {
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
@@ -16,7 +16,13 @@ export interface CrawlSession {
 }
 type CrawlSleep = (ms: number) => Promise<void>;
 export interface CrawlAnomaly {
-    kind: CrawlAnomalyKind;
+    /**
+     * A single-channel fault (something bad in one stream) or a CONTRADICTION (two channels
+     * disagreeing about the same click). The second kind is why an autonomous crawl is worth more
+     * than a human clicking the same buttons: a person sees only the screen, so a UI that advanced
+     * while its write failed looks like success to them and always will.
+     */
+    kind: CrawlAnomalyKind | ContradictionKind;
     /** The control that triggered it. */
     ref: string;
     desc: string;
@@ -41,6 +47,7 @@ export interface CrawlReport {
         consoleErrors: number;
         failedRequests: number;
         deadControls: number;
+        contradictions: number;
     };
     /** Descriptions of the controls actually clicked. */
     visited: string[];
@@ -62,6 +69,13 @@ export interface CrawlOptions {
  * orchestration over a CrawlSession: no browser/Node imports, fully unit-testable with a fake.
  * Single-pass by design (no re-discovery) so it always terminates and never explodes on navigation.
  */
+/**
+ * Controls whose correct behaviour IS to do nothing when clicked.
+ *
+ * Read off the same descriptor the crawler already has, so no extra round trip: `[disabled]` is inert
+ * by definition, an already `[checked]` radio/checkbox is idempotent, and clicking a text field
+ * focuses it rather than changing anything.
+ */
+export declare function legitimatelyInert(desc: string): boolean;
 export declare function crawl(session: CrawlSession, opts: CrawlOptions, sleep: CrawlSleep): Promise<CrawlReport>;
 export {};
-//# sourceMappingURL=crawl.d.ts.map

package/dist/crawl/crawl.js

@@ -1,6 +1,7 @@
-import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
+import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, ContradictionKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
 import { parseInteractive, asRecord, asNumber, asString, sourceOf, } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
+import { findContradictions } from '../events/contradictions.js';
 /** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
 export const CAPPED_SNAPSHOT_NOTE = 'the page exceeded one snapshot, so controls past the cap were never seen — interactiveFound is a floor, not a total; re-run with a narrower `scope` to cover the rest';
 /** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
@@ -33,6 +34,20 @@ function failedRequests(events, floor) {
  * orchestration over a CrawlSession: no browser/Node imports, fully unit-testable with a fake.
  * Single-pass by design (no re-discovery) so it always terminates and never explodes on navigation.
  */
+/**
+ * Controls whose correct behaviour IS to do nothing when clicked.
+ *
+ * Read off the same descriptor the crawler already has, so no extra round trip: `[disabled]` is inert
+ * by definition, an already `[checked]` radio/checkbox is idempotent, and clicking a text field
+ * focuses it rather than changing anything.
+ */
+export function legitimatelyInert(desc) {
+    if (desc.includes('[disabled]'))
+        return true;
+    if (desc.includes('[checked]'))
+        return true;
+    return /\b(textbox|searchbox|combobox|spinbutton)\b/.test(desc);
+}
 export async function crawl(session, opts, sleep) {
     const maxSteps = opts.maxSteps ?? CRAWL_DEFAULTS.MAX_STEPS;
     const settleMs = opts.settleMs ?? CRAWL_DEFAULTS.SETTLE_MS;
@@ -50,7 +65,7 @@ export async function crawl(session, opts, sleep) {
     const coverageCapped = snapshot.truncated === true;
     const anomalies = [];
     const visited = [];
-    const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0 };
+    const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0, contradictions: 0 };
     const seen = new Set();
     let stepsRun = 0;
     for (const item of items) {
@@ -107,9 +122,34 @@ export async function crawl(session, opts, sleep) {
                 ...source,
             });
         }
+        // CONTRADICTIONS: the channels disagree about what this click did. Reported per control, so a
+        // crawl of an unknown app surfaces its false greens without anyone knowing where to look.
+        for (const c of findContradictions(events)) {
+            counts.contradictions += 1;
+            anomalies.push({
+                kind: c.kind,
+                ref: item.ref,
+                desc: item.desc,
+                detail: `${c.claim}, but ${c.counter} — ${c.detail}`,
+                ...source,
+            });
+        }
         // DEAD: the click dispatched but the app produced no activity and no error to explain it.
+        //
+        // Unless the control is SUPPOSED to be inert. Measured on a shipments console: every one of the
+        // crawler's three anomalies was a control behaving correctly — a `[disabled]` button, an already
+        // `[checked]` radio, and a text input (a click focuses it; mutating would be the surprise). An
+        // anomaly list that is 100% false on a real app is worse than no anomaly list, because the agent
+        // spends its budget disproving it and learns to skip the field.
+        //
+        // Deliberately NOT fixed by counting focus as activity: focus moving is not the app reacting, and
+        // treating it as such would make a genuinely dead button that takes focus look alive — trading
+        // noise for the false negative this check exists to catch.
         const dispatched = asRecord(act.result)['dispatched'] !== false && act.ok;
-        if (dispatched && errs.length === 0 && !events.some(isActivity)) {
+        if (dispatched &&
+            errs.length === 0 &&
+            !events.some(isActivity) &&
+            !legitimatelyInert(item.desc)) {
             counts.deadControls += 1;
             anomalies.push({
                 kind: CrawlAnomalyKind.DEAD_CONTROL,
@@ -133,4 +173,3 @@ export async function crawl(session, opts, sleep) {
         ...(coverageCapped ? { coverageNote: CAPPED_SNAPSHOT_NOTE } : {}),
     };
 }
-//# sourceMappingURL=crawl.js.map

package/dist/daemon-resilience.d.ts

@@ -12,6 +12,11 @@ export interface ProcessLike {
     on(event: string, listener: (arg: unknown) => void): unknown;
 }
 type LogFn = (event: string, data: Record<string, unknown>) => void;
+/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
+export declare const CrashKind: {
+    readonly UNHANDLED_REJECTION: "unhandled_rejection";
+    readonly UNCAUGHT_EXCEPTION: "uncaught_exception";
+};
+export type CrashKind = (typeof CrashKind)[keyof typeof CrashKind];
 export declare function installDaemonResilience(proc: ProcessLike, log: LogFn, onFatal: () => void): void;
 export {};
-//# sourceMappingURL=daemon-resilience.d.ts.map

package/dist/daemon-resilience.js

@@ -8,16 +8,78 @@
  * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
  * daemon, which beats crashing silently or limping along corrupt.
  */
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { errorSkeleton, errorTypeOf, fingerprintCrash, MAX_REPORTED_FRAMES, reticleFrames, } from './telemetry/error-fingerprint.js';
+import { getSessionMetrics } from './telemetry/session-metrics.js';
+import { machineSnapshot } from './telemetry/machine-snapshot.js';
+import { getTelemetry } from './telemetry/telemetry.js';
 function describe(value) {
     return value instanceof Error ? value.message : String(value);
 }
+/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
+export const CrashKind = {
+    UNHANDLED_REJECTION: 'unhandled_rejection',
+    UNCAUGHT_EXCEPTION: 'uncaught_exception',
+};
+/**
+ * Report a crash with enough detail to actually diagnose it.
+ *
+ * This is the only place in the product that learns about a crash at all. An uncaught exception in a
+ * long-running daemon takes down every agent attached to it, and the only other record is a line in a
+ * local log nobody sends us.
+ *
+ * The first version sent a hash and nothing else, which made crashes rankable and undiagnosable — you
+ * could see that forty machines hit `a3f2c1d8e9b0` and had no way to learn what that was. So it now
+ * carries the four things an RCA needs: WHERE (our own frames, with function names and line numbers),
+ * WHAT (the message with every variable part stripped), WHEN (the tool in flight), and WHY-ish (the
+ * agent's approach run before it). All of it is our code and our vocabulary; the user's stack frames,
+ * their paths, and the contents of their message are removed before any of it is built.
+ *
+ * Best-effort and wrapped: reporting a crash must never be the reason a crash gets worse.
+ */
+function reportCrash(kind, value) {
+    try {
+        const errorType = errorTypeOf(value);
+        const stack = value instanceof Error ? (value.stack ?? '') : '';
+        const message = describe(value);
+        const { breadcrumb, inFlight } = getSessionMetrics().trail;
+        const machine = machineSnapshot();
+        void getTelemetry().emit(TelemetryEventKind.RUNTIME_CRASHED, {
+            // A crash is ALWAYS reached through something the agent asked for — the daemon does nothing on
+            // its own — so attributing it to the agent is accurate rather than a guess.
+            actor: TelemetryActor.AGENT,
+            crash: {
+                kind,
+                errorType,
+                fingerprint: fingerprintCrash(errorType, stack, message),
+                // The skeleton, not the message: every quoted string, path, URL, id and number is replaced
+                // by `*` first. This is what makes the fingerprint mean something to a human reading a chart.
+                message: errorSkeleton(message).slice(0, 300),
+                // Our own frames, our own published code. The file, the line, and the function — which is the
+                // whole of "where did it break". Frames from the user's app never survive this.
+                frames: reticleFrames(stack).slice(0, MAX_REPORTED_FRAMES),
+                ...(inFlight !== undefined ? { tool: inFlight } : {}),
+                ...(breadcrumb.length > 0 ? { breadcrumb } : {}),
+                // Crashes cluster hard by runtime version and architecture, and we were recording neither.
+                nodeVersion: process.versions.node,
+                arch: process.arch,
+                // "Out of memory" and "our bug" look identical in a stack trace. This is what tells them apart.
+                ...(machine !== undefined ? { machine } : {}),
+            },
+        });
+    }
+    catch {
+        /* a crash report must never be the reason a crash gets worse */
+    }
+}
 export function installDaemonResilience(proc, log, onFatal) {
     proc.on('unhandledRejection', (reason) => {
         log('reticle_daemon_unhandled_rejection', { reason: describe(reason) });
+        reportCrash(CrashKind.UNHANDLED_REJECTION, reason);
     });
     proc.on('uncaughtException', (err) => {
         log('reticle_daemon_uncaught_exception', { error: describe(err) });
+        reportCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
         onFatal();
     });
 }
-//# sourceMappingURL=daemon-resilience.js.map

package/dist/daemon.d.ts

@@ -1,5 +1,5 @@
 export declare function logPath(port: number): string;
-export declare function readPid(port: number): number | null;
+export declare function readPid(port: number, home?: string): number | null;
 export declare function isAlive(pid: number): boolean;
 export declare function writePid(port: number): void;
 /**
@@ -41,10 +41,30 @@ export declare function discoverDaemonPort(): number | null;
  * ~/.reticle and the process.kill(pid,0) liveness probe).
  */
 export declare function reclaimStaleDaemons(home?: string, pidAlive?: (pid: number) => boolean): number[];
+/** The minimal shape of a spawned child that spawnDaemon uses. */
+export interface SpawnedChild {
+    readonly pid?: number | undefined;
+    on(event: string, handler: (...args: unknown[]) => void): unknown;
+    unref(): void;
+}
+/** Injectable deps for spawnDaemon — the testability seam. Defaults to the real implementations. */
+export interface SpawnDaemonDeps {
+    readonly home: string;
+    openFile(path: string, flags: string): number;
+    closeFile(fd: number): void;
+    spawnChild(command: string, args: readonly string[], options: {
+        detached: boolean;
+        stdio: readonly ('ignore' | number)[];
+    }): SpawnedChild;
+    pidAlive(pid: number): boolean;
+}
+export declare function defaultSpawnDaemonDeps(): SpawnDaemonDeps;
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.
  * Writes the PID file from the parent before returning so callers can call isRunning
  * immediately without a race window.
+ *
+ * `deps` is injectable for testing (default: real fs/spawn against ~/.reticle). The same seam
+ * pattern as reclaimStaleDaemons(home, pidAlive).
  */
-export declare function spawnDaemon(nodeExec: string, scriptPath: string, args: string[], port: number): boolean;
-//# sourceMappingURL=daemon.d.ts.map
+export declare function spawnDaemon(nodeExec: string, scriptPath: string, args: string[], port: number, deps?: SpawnDaemonDeps): boolean;

package/dist/daemon.js

@@ -4,8 +4,8 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSyn
 import { spawn } from 'node:child_process';
 import { daemonRegistryFileName, daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, } from '@reticlehq/core';
 const RETICLE_HOME = join(homedir(), '.reticle');
-function pidPath(port) {
-    return join(RETICLE_HOME, `daemon-${port}.pid`);
+function pidPath(port, home = RETICLE_HOME) {
+    return join(home, `daemon-${port}.pid`);
 }
 function registryPath(port) {
     return join(RETICLE_HOME, daemonRegistryFileName(port));
@@ -13,8 +13,8 @@ function registryPath(port) {
 export function logPath(port) {
     return join(RETICLE_HOME, `daemon-${port}.log`);
 }
-export function readPid(port) {
-    const path = pidPath(port);
+export function readPid(port, home = RETICLE_HOME) {
+    const path = pidPath(port, home);
     if (!existsSync(path))
         return null;
     const n = parseInt(readFileSync(path, 'utf8').trim(), 10);
@@ -180,28 +180,41 @@ export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
     }
     return reclaimed;
 }
+export function defaultSpawnDaemonDeps() {
+    return {
+        home: RETICLE_HOME,
+        openFile: openSync,
+        closeFile: closeSync,
+        spawnChild: (command, args, options) => spawn(command, [...args], { detached: options.detached, stdio: [...options.stdio] }),
+        pidAlive: isAlive,
+    };
+}
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.
  * Writes the PID file from the parent before returning so callers can call isRunning
  * immediately without a race window.
+ *
+ * `deps` is injectable for testing (default: real fs/spawn against ~/.reticle). The same seam
+ * pattern as reclaimStaleDaemons(home, pidAlive).
  */
-export function spawnDaemon(nodeExec, scriptPath, args, port) {
-    mkdirSync(RETICLE_HOME, { recursive: true });
-    const path = pidPath(port);
+export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpawnDaemonDeps()) {
+    mkdirSync(deps.home, { recursive: true });
+    const pidFilePath = join(deps.home, `daemon-${port}.pid`);
+    const logFilePath = join(deps.home, `daemon-${port}.log`);
     // O_EXCL spawn-lock: only the FIRST racer to create the pidfile spawns. A concurrent second gets
     // EEXIST — if a LIVE daemon owns the port it skips (no duplicate detached daemon, no clobbered pid);
     // a stale pidfile from a crashed daemon is reclaimed. Returns false when it did not spawn.
     let lockFd;
     try {
-        lockFd = openSync(path, 'wx');
+        lockFd = deps.openFile(pidFilePath, 'wx');
     }
     catch {
-        const existing = readPid(port);
-        if (existing !== null && isAlive(existing))
+        const existing = readPid(port, deps.home);
+        if (existing !== null && deps.pidAlive(existing))
             return false;
         try {
-            unlinkSync(path);
-            lockFd = openSync(path, 'wx');
+            unlinkSync(pidFilePath);
+            lockFd = deps.openFile(pidFilePath, 'wx');
         }
         catch {
             return false; // lost a concurrent reclaim race
@@ -209,13 +222,13 @@ export function spawnDaemon(nodeExec, scriptPath, args, port) {
     }
     let logFd;
     try {
-        logFd = openSync(logPath(port), 'a');
+        logFd = deps.openFile(logFilePath, 'a');
     }
     catch {
         // Log path unwritable (permissions, disk full). Clean up the lock so we don't leave a ghost.
-        closeSync(lockFd);
+        deps.closeFile(lockFd);
         try {
-            unlinkSync(path);
+            unlinkSync(pidFilePath);
         }
         catch {
             // racing another reclaimer — fine
@@ -224,17 +237,17 @@ export function spawnDaemon(nodeExec, scriptPath, args, port) {
     }
     let child;
     try {
-        child = spawn(nodeExec, [scriptPath, ...args], {
+        child = deps.spawnChild(nodeExec, [scriptPath, ...args], {
             detached: true,
             stdio: ['ignore', logFd, logFd],
         });
     }
     catch {
         // spawn can throw synchronously on some platforms (e.g. ENOMEM, invalid args).
-        closeSync(logFd);
-        closeSync(lockFd);
+        deps.closeFile(logFd);
+        deps.closeFile(lockFd);
         try {
-            unlinkSync(path);
+            unlinkSync(pidFilePath);
         }
         catch {
             // racing another reclaimer — fine
@@ -242,7 +255,7 @@ export function spawnDaemon(nodeExec, scriptPath, args, port) {
         return false;
     }
     // The parent's copy of logFd is no longer needed — spawn duplicated it into the child.
-    closeSync(logFd);
+    deps.closeFile(logFd);
     // Suppress the async ENOENT/EACCES that fires when the executable is missing or unexecutable.
     // The failure is already detected synchronously via `child.pid === undefined`; without this
     // handler the error propagates as an uncaught exception and crashes the parent process.
@@ -250,9 +263,9 @@ export function spawnDaemon(nodeExec, scriptPath, args, port) {
     if (child.pid === undefined) {
         // Spawn failed silently (resource exhaustion, invalid executable on some platforms). The pidfile
         // is empty — clean it up so discovery doesn't see a ghost, and report failure honestly.
-        closeSync(lockFd);
+        deps.closeFile(lockFd);
         try {
-            unlinkSync(path);
+            unlinkSync(pidFilePath);
         }
         catch {
             // racing another reclaimer — fine
@@ -260,8 +273,7 @@ export function spawnDaemon(nodeExec, scriptPath, args, port) {
         return false;
     }
     writeFileSync(lockFd, String(child.pid), 'utf8');
-    closeSync(lockFd);
+    deps.closeFile(lockFd);
     child.unref();
     return true;
 }
-//# sourceMappingURL=daemon.js.map

package/dist/domain/domain-model.d.ts

@@ -61,4 +61,3 @@ export interface DomainModel {
     summary: string;
 }
 export declare function buildDomainModel(flows: readonly FlowFile[], contract: CapabilitiesContract | null, runs?: readonly RunRecord[]): DomainModel;
-//# sourceMappingURL=domain-model.d.ts.map

package/dist/domain/domain-model.js

@@ -108,7 +108,7 @@ export function buildDomainModel(flows, contract, runs = []) {
 }
 function buildSummary(flowCount, coverage, gaps, topRisk) {
     if (flowCount === 0) {
-        return 'No saved flows yet — record the critical journeys (reticle_record_start) so the agent learns the app.';
+        return 'No saved flows yet — record the critical journeys (reticle_record{action:"start"}) so the agent learns the app.';
     }
     const parts = [
         `${String(flowCount)} flow${flowCount === 1 ? '' : 's'}: ${String(coverage.asserted)} asserted, ${String(coverage.presenceOnly)} presence-only, ${String(coverage.assertionFree)} assertion-free`,
@@ -124,4 +124,3 @@ function buildSummary(flowCount, coverage, gaps, topRisk) {
     }
     return parts.join('. ') + '.';
 }
-//# sourceMappingURL=domain-model.js.map

package/dist/domain/domain-tools.d.ts

@@ -1,9 +1,2 @@
 import type { ToolDef } from '../tools/tools.js';
-/**
- * reticle_domain — the "learn the app before testing it" tool. Synthesizes every saved flow + the
- * registered capabilities into a compact domain model: the journeys, what each asserts, and the
- * GAPS (declared signals/testids no flow verifies). An agent reads this once instead of crawling
- * the whole app or reading all the source — and it points straight at untested intent.
- */
 export declare const DOMAIN_TOOLS: ToolDef[];
-//# sourceMappingURL=domain-tools.d.ts.map

package/dist/domain/domain-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { asNumber } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { readContract } from '../project/reticle-dir.js';
 import { buildDomainModel } from './domain-model.js';
@@ -10,11 +11,18 @@ import { instrumentationGapsForFlows } from '../oracles/flow-instrument-gaps.js'
  * GAPS (declared signals/testids no flow verifies). An agent reads this once instead of crawling
  * the whole app or reading all the source — and it points straight at untested intent.
  */
+/** Flows detailed when the caller does not ask for a specific count. */
+const DEFAULT_FLOW_DETAIL_LIMIT = 25;
 export const DOMAIN_TOOLS = [
     {
         name: ReticleTool.DOMAIN,
         description: 'Read the app domain model BEFORE testing: every saved flow with its assertion grade, the consequence that MUST hold for it (mustHold = what it actually tests), the anchors/signals it exercises, plus GAPS — declared signals/testids that NO flow asserts (untested intent), and flows that assert no observable consequence. Use this to decide what to test and where the real risk is, instead of crawling the whole app. Reads .reticle/flows/ + .reticle/contract.json (no browser needed).',
-        inputSchema: {},
+        inputSchema: {
+            limit: z
+                .number()
+                .optional()
+                .describe('Most-recent N flows to detail. Defaults to 25 — the per-flow list grows with every saved flow (measured at ~11KB / ~2,700 tokens at 22 flows) and a large project would spend most of an agent context on flows it is not asking about. `flowCount` is always the true total, and the gaps/coverage summary is computed over ALL flows regardless, so capping the detail never changes the analysis.'),
+        },
         outputSchema: {
             flowCount: z.number(),
             flows: z.array(z.object({
@@ -35,6 +43,10 @@ export const DOMAIN_TOOLS = [
                 signals: z.array(z.string()),
                 stores: z.array(z.string()),
             }),
+            flowsTruncated: z
+                .number()
+                .optional()
+                .describe('How many flows were omitted from `flows` by `limit`. Absent means the listing is complete. gaps/coverage always cover every flow.'),
             coverage: z.object({
                 asserted: z.number(),
                 presenceOnly: z.number(),
@@ -54,7 +66,7 @@ export const DOMAIN_TOOLS = [
                 .optional()
                 .describe('Ready-to-apply instrumentation proposals for gaps that have a source location — { file, line, insert, rationale }. Apply, re-verify, and the app’s observability compounds.'),
         },
-        handler: async (deps) => {
+        handler: async (deps, args) => {
             const names = await deps.flows.list();
             const flows = [];
             for (const name of names) {
@@ -69,8 +81,13 @@ export const DOMAIN_TOOLS = [
             // Self-instrumentation: turn located gaps (unasserted flows with a source stamp) into apply-ready diffs.
             const stepsByName = new Map(flows.map((f) => [f.name, f.steps]));
             const instrumentation = proposeInstrumentation(instrumentationGapsForFlows(model.gaps.unassertedFlows, stepsByName));
-            return instrumentation.length > 0 ? { ...model, instrumentation } : model;
+            // The per-flow detail is capped; `flowCount`, `gaps` and `coverage` are computed over every
+            // flow, so the ANALYSIS is never truncated — only the listing an agent reads past is.
+            const cap = asNumber(args['limit']) ?? DEFAULT_FLOW_DETAIL_LIMIT;
+            const capped = model.flows.length > cap
+                ? { ...model, flows: model.flows.slice(-cap), flowsTruncated: model.flows.length - cap }
+                : model;
+            return instrumentation.length > 0 ? { ...capped, instrumentation } : capped;
         },
     },
 ];
-//# sourceMappingURL=domain-tools.js.map

package/dist/domain/flow-risk.d.ts

@@ -31,4 +31,3 @@ export declare function rankByRisk(entries: {
     name: string;
     risk: FlowRisk;
 }[]): string[];
-//# sourceMappingURL=flow-risk.d.ts.map

package/dist/domain/flow-risk.js

@@ -78,4 +78,3 @@ export function rankByRisk(entries) {
         .sort((a, b) => RANK[b.risk.level] - RANK[a.risk.level] || a.name.localeCompare(b.name))
         .map((e) => e.name);
 }
-//# sourceMappingURL=flow-risk.js.map

package/dist/ee/audit-log.d.ts

@@ -12,4 +12,3 @@ interface AuditEvent {
 /** Record an audit event — gated. Throws EnterpriseLicenseError in production without a valid license. */
 export declare function recordAuditEvent(event: AuditEvent, ctx: GateContext): AuditEvent;
 export {};
-//# sourceMappingURL=audit-log.d.ts.map

package/dist/ee/audit-log.js

@@ -9,4 +9,3 @@ export function recordAuditEvent(event, ctx) {
     assertEnterprise('audit-log', ctx);
     return event; // stub: a real implementation persists to the enterprise audit store
 }
-//# sourceMappingURL=audit-log.js.map

package/dist/events/body-failures.d.ts

@@ -0,0 +1,4 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import type { Contradiction } from './contradictions.js';
+/** Contradictions for 2xx responses whose bodies report failure. One per offending call. */
+export declare function findBodyFailures(events: readonly ReticleEvent[]): Contradiction[];