@reticlehq/server 2.11.0 → 2.13.0

package/dist/input/scroll-find.js

@@ -13,61 +13,99 @@ async function queryFirst(session, q) {
     return undefined;
 }
 /**
- * A note attached to `{ found: false, exhausted: true }` only when the failure is
- * actually informative: the document itself had nothing to scroll (scrolled:false with
- * no explicit container), so the target is likely inside a list with its own scroll
- * container. Reaching the genuine end of a scrolled container stays quiet.
+ * A note attached to `{ found: false, exhausted: true }` only when the failure is actually
+ * informative: nothing in the container ever moved (so the "list" being searched was never
+ * scrollable and the target is likely inside one with its own scroll container). Reaching the
+ * genuine ends of a container that DID scroll stays quiet — that is exhaustion, not confusion.
  */
-function exhaustNote(q, data) {
+function exhaustNote(q, data, nothingEverScrolled) {
     if (q.container !== undefined)
         return {};
-    if (false !== data['scrolled'])
+    if (true === data['scrolled'] || !nothingEverScrolled)
         return {};
     return {
         note: "The document did not scroll — the target may be inside a list with its own scroll container. Pass that container's ref as `container`.",
     };
 }
+/** One viewport-height step upward when the last result carried no clientHeight to size it by. */
+const UP_STEP_FALLBACK_PX = 400;
 /**
- * Reveal an element that a windowed/virtualized list has not mounted yet. Queries
- * once (it may already be visible), then scrolls the container ~one viewport at a time, re-querying
- * after each, until the element appears, the list ends, or the maxScrolls budget is spent. Pure
- * orchestration over the session command seam — fully unit-testable with a fake.
+ * Size the upward step off the container the SCROLL result just described, falling back to a
+ * plain viewport height when the result did not carry one.
+ */
+function upStepPx(last) {
+    const h = last['clientHeight'];
+    return 'number' === typeof h && h > 0 ? h : UP_STEP_FALLBACK_PX;
+}
+/**
+ * Reveal an element that a windowed/virtualized list has not mounted yet. Queries once (it may
+ * already be visible), optionally jumps straight to a bisection estimate, then walks the container
+ * a viewport at a time re-querying after each step. Downward first; when the bottom is reached the
+ * walk TURNS AROUND and continues upward, because a list that is already scrolled to its end keeps
+ * its earlier rows mounted above the viewport and a downward-only search answered "exhausted" on
+ * its first step (#505). `exhausted` therefore means BOTH directions are spent, not "the bottom is
+ * here". Pure orchestration over the session command seam — fully unit-testable with a fake.
  */
 export async function scrollToFind(session, q, opts = {}) {
     const max = opts.maxScrolls ?? SCROLL_FIND_DEFAULTS.MAX_SCROLLS;
     const first = await queryFirst(session, q);
     if (first !== undefined)
         return { found: true, element: first, scrolls: 0, exhausted: false };
-    // Bisection: if the caller knows the target index and list size, jump to the estimated offset
-    // in one scroll command rather than stepping a viewport at a time. Then refine linearly.
+    const baseArgs = () => q.container !== undefined ? { ref: q.container } : {};
     let scrolls = 0;
+    let last = {};
+    // Bisection: if the caller knows the target index and list size, jump to the estimated offset in
+    // one scroll command rather than stepping a viewport at a time. The estimate can land on either
+    // side of the target, so refinement below still searches both directions from wherever this put us.
     if (q.targetIndex !== undefined && q.totalCount !== undefined && q.totalCount > 1) {
         const fraction = Math.min(1, Math.max(0, q.targetIndex / q.totalCount));
-        const sr = await session.command(ReticleCommand.SCROLL, {
-            ...(q.container !== undefined ? { ref: q.container } : {}),
-            fraction,
-        });
+        const sr = await session.command(ReticleCommand.SCROLL, { ...baseArgs(), fraction });
         scrolls += 1;
+        last = asRecord(sr.result);
         const hit = await queryFirst(session, q);
         if (hit !== undefined)
             return { found: true, element: hit, scrolls, exhausted: false };
-        // Fall through to linear refinement from current position (already near the target).
+    }
+    let downwardSpent = false;
+    let everScrolled = false;
+    // The downward pass. Spending its whole budget without reaching the end means rows may remain
+    // further down, so that answer is `exhausted:false` and the upward pass never runs.
+    for (let i = 0; i < max && !downwardSpent; i += 1) {
+        const sr = await session.command(ReticleCommand.SCROLL, baseArgs());
+        scrolls += 1;
         const data = asRecord(sr.result);
-        if (true === data['atEnd'] || false === data['scrolled']) {
-            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data) };
-        }
+        last = data;
+        if (true === data['scrolled'])
+            everScrolled = true;
+        const hit = await queryFirst(session, q);
+        if (hit !== undefined)
+            return { found: true, element: hit, scrolls, exhausted: false };
+        // Reached the bottom, or the container would not move downward — turn around before giving up.
+        if (true === data['atEnd'] || true !== data['scrolled'])
+            downwardSpent = true;
+    }
+    // If the downward pass spent its budget it never saw the end, so there is nothing to turn around
+    // for; report honestly rather than doubling a call whose caller asked for `max` steps.
+    if (!downwardSpent) {
+        return { found: false, scrolls, exhausted: false };
     }
+    // The upward pass gets the caller's budget again, not what is left of it: a list at the bottom of
+    // 14k px needs ~90 scrolls to reach its end and ~90 more to get back, so sharing one budget would
+    // strand the search halfway and answer `exhausted:false` about a list both of whose ends are known.
     for (let i = 0; i < max; i += 1) {
-        const sr = await session.command(ReticleCommand.SCROLL, q.container !== undefined ? { ref: q.container } : {});
+        const sr = await session.command(ReticleCommand.SCROLL, { ...baseArgs(), dy: -upStepPx(last) });
         scrolls += 1;
         const data = asRecord(sr.result);
+        last = data;
+        if (true === data['scrolled'])
+            everScrolled = true;
         const hit = await queryFirst(session, q);
         if (hit !== undefined)
             return { found: true, element: hit, scrolls, exhausted: false };
-        // Reached the bottom or the container would not move — no more rows to reveal.
-        if (true === data['atEnd'] || false === data['scrolled']) {
-            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data) };
+        // The top refusing to move means both directions are spent.
+        if (true !== data['scrolled']) {
+            return { found: false, scrolls, exhausted: true, ...exhaustNote(q, data, !everScrolled) };
         }
     }
-    return { found: false, scrolls, exhausted: false }; // spent the budget; more may lie further down
+    return { found: false, scrolls, exhausted: false }; // spent the upward budget; more may lie above
 }

package/dist/input/scroll-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { QueryBy } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
+import { listIndexSchema, scrollCountSchema } from '../tools/numeric-bounds.js';
 import { scrollToFind } from './scroll-find.js';
 /**
  * reticle_scroll_to — the windowed/virtualized-list escape hatch. A plain reticle_query
@@ -30,16 +31,13 @@ export const SCROLL_TOOLS = [
                 .string()
                 .optional()
                 .describe('Element ref for the scrollable container. Omit to scroll the document.'),
-            maxScrolls: z
-                .number()
+            maxScrolls: scrollCountSchema
                 .optional()
                 .describe('Maximum number of scroll steps before giving up. Default: 20.'),
-            targetIndex: z
-                .number()
+            targetIndex: listIndexSchema
                 .optional()
                 .describe('Known row index of the target in the list. Combine with totalCount for bisection — jumps directly to the estimated offset.'),
-            totalCount: z
-                .number()
+            totalCount: listIndexSchema
                 .optional()
                 .describe('Total item count in the virtualized list. Required for bisection with targetIndex.'),
             sessionId: z

package/dist/input/viewport-tools.js

@@ -2,10 +2,11 @@ import { z } from 'zod';
 import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
+import { MAX_VIEWPORT_PX, MIN_VIEWPORT_PX, viewportPxSchema } from '../tools/numeric-bounds.js';
 import { asString } from '../tools/tools-helpers.js';
 /** Bounds so a viewport request stays sane (and a typo can't ask for a 1px or 100k-px window). */
-const MIN_DIM = 64;
-const MAX_DIM = 10000;
+const MIN_DIM = MIN_VIEWPORT_PX;
+const MAX_DIM = MAX_VIEWPORT_PX;
 function viewportProvider(deps) {
     const p = deps.realInput;
     return p !== undefined && 'function' === typeof p.setViewport
@@ -20,8 +21,8 @@ export const VIEWPORT_TOOLS = [
             'reticle_visual_diff `masks` and a frozen clock (reticle_clock). Set it once before reticle_screenshot / ' +
             'reticle_visual_diff. Returns { applied, width, height } or the no-provider recommendation.',
         inputSchema: {
-            width: z.number().int().describe('Viewport width in CSS px (e.g. 1280).'),
-            height: z.number().int().describe('Viewport height in CSS px (e.g. 800).'),
+            width: viewportPxSchema.describe('Viewport width in CSS px (e.g. 1280).'),
+            height: viewportPxSchema.describe('Viewport height in CSS px (e.g. 800).'),
             ...sessionIdShape,
         },
         outputSchema: {

package/dist/intent/inline-intent.d.ts

@@ -0,0 +1,37 @@
+import type { ToolDeps } from '../tools/tool-kit.js';
+/**
+ * The ledger id a piece of inline prose is declared under.
+ *
+ * Derived from the statement rather than minted, so the same sentence declared on five verdicts is
+ * one row rather than five, and a DIFFERENT sentence is a different row rather than a false
+ * amendment of the first. The slug is there because the id is what an agent later types to reference
+ * the intent, and a bare digest is unreadable; the digest is there because the slug is truncated and
+ * two long statements sharing a prefix must not share a row.
+ */
+export declare function inlineIntentId(statement: string): string;
+/** What `provenBy` records: which tool drew the verdict, and when. */
+export declare function inlineVerdictId(tool: string, at: number): string;
+export declare function surfaceForInlineIntent(url: string | undefined, flow: string | undefined, 
+/** `file` or `file:line` for the element the verdict acted on, when it had one. */
+sourceLabel?: string): {
+    route?: string;
+    flow?: string;
+    files?: string[];
+} | undefined;
+export declare function linkInlineIntent(deps: ToolDeps, sessionId: string | undefined, intent: string | undefined, 
+/** The predicate this verdict will evaluate, or undefined when it proves nothing (a bare settle). */
+binding: unknown): Promise<string | undefined>;
+/**
+ * Record that this verdict proved the intent. Call only for a verdict that actually proved something.
+ *
+ * The ledger's own rule does the rest: `dischargeIntent` refuses an intent with no binding, so an
+ * intent declared inline on a wait that asserted no consequence stays open and honest instead of
+ * collecting a proof nothing earned.
+ */
+export declare function dischargeInlineIntent(deps: ToolDeps, sessionId: string | undefined, id: string | undefined, proof: {
+    verdictId: string;
+    grade: string;
+    at: number;
+}, 
+/** `file:line` of the element this verdict acted on, when there was one. */
+sourceLabel?: string): Promise<void>;

package/dist/intent/inline-intent.js

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import { IntentStore } from './intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
+/**
+ * Intent declared INLINE, on the tool that is already drawing the verdict.
+ *
+ * `reticle_intent` is on the extended surface, so declaring intent costs an agent a discovery, a
+ * decision and a round trip before it has done anything — three places the capture silently fails,
+ * and it does. `reticle_act_and_wait` and `reticle_assert` are in every agent's tool list already,
+ * so one optional argument there makes the declaration free and discoverable by construction.
+ *
+ * This is a shortcut into the EXISTING ledger, never a second one. It writes `.reticle/intent.json`
+ * through `IntentStore` exactly as `reticle_intent { action: "declare" }` does, so a reviewer reads
+ * one file in one vocabulary and cannot tell from the row which door the intent came in by. The
+ * pattern is `flows/flow-intent.ts`, which does the same job for a saved flow.
+ */
+/** Namespaced like `flow:`, so an inline id never collides with one an agent chose by hand. */
+const INLINE_INTENT_ID_PREFIX = 'inline:';
+const ID_SEPARATOR = ':';
+const SLUG_SEPARATOR = '-';
+const SLUG_MAX = 48;
+const HASH_LENGTH = 8;
+const HASH_ALGORITHM = 'sha1';
+const NON_SLUG = /[^a-z0-9]+/g;
+const SLUG_EDGES = /^-+|-+$/g;
+/**
+ * The ledger id a piece of inline prose is declared under.
+ *
+ * Derived from the statement rather than minted, so the same sentence declared on five verdicts is
+ * one row rather than five, and a DIFFERENT sentence is a different row rather than a false
+ * amendment of the first. The slug is there because the id is what an agent later types to reference
+ * the intent, and a bare digest is unreadable; the digest is there because the slug is truncated and
+ * two long statements sharing a prefix must not share a row.
+ */
+export function inlineIntentId(statement) {
+    const slug = statement
+        .toLowerCase()
+        .replace(NON_SLUG, SLUG_SEPARATOR)
+        .replace(SLUG_EDGES, '')
+        .slice(0, SLUG_MAX)
+        .replace(SLUG_EDGES, '');
+    const digest = createHash(HASH_ALGORITHM).update(statement).digest('hex').slice(0, HASH_LENGTH);
+    return `${INLINE_INTENT_ID_PREFIX}${slug}${SLUG_SEPARATOR}${digest}`;
+}
+/** What `provenBy` records: which tool drew the verdict, and when. */
+export function inlineVerdictId(tool, at) {
+    return `${tool}${ID_SEPARATOR}${String(at)}`;
+}
+/**
+ * Put an inline intent in the ledger and attach the predicate about to be evaluated. Returns the id
+ * the verdict may later discharge, or undefined when there was no intent to record.
+ *
+ * `intent` carries EITHER prose OR the id of an intent already in the ledger. One field rather than
+ * two because the surface is the scarce thing here and the two cases are told apart by the ledger
+ * itself: a string that names an existing row is a reference, anything else is prose. A statement
+ * that happens to equal an existing id is the same intent said twice, so pointing at the row is the
+ * right answer there too, not a collision.
+ *
+ * A referenced intent is never re-declared, which would overwrite the agent's own words with an id,
+ * and its binding is left alone when it already has one — a predicate bound deliberately through
+ * `reticle_intent { action: "bind" }` is a stronger statement than whatever this one call asserts,
+ * and quietly replacing it is exactly the narrowing the ledger exists to make visible.
+ *
+ * Best-effort by construction: a ledger that cannot be written is a small problem, and a verdict
+ * that fails to return because of one is a large problem.
+ */
+/**
+ * The surface an inline intent was captured on, so the store can FILE it.
+ *
+ * Measured on a real corpus: 167 of 173 things a project knew landed in `unsorted`, because
+ * `act_and_wait({ intent })` declared a statement and nothing else. The subject ladder had no flow,
+ * no route and no explicit subject to work from, so every record fell to the bucket of last resort
+ * — and a coverage map that is one pile with six labels tells a manager the team knows nothing,
+ * when the truth is that it knows a great deal and none of it is filed.
+ *
+ * The ROUTE is what makes this work at all, because it is always available: an agent asserting
+ * something is always somewhere. A flow name is better when there is one, and `subjectFor` already
+ * prefers it — this only has to supply both and let that ladder decide.
+ *
+ * Query and hash are dropped. `/issues?category=severe` and `/issues` are the same subject seen
+ * twice; keeping the query would shard one area of the product across every filter anybody used.
+ *
+ * Returns undefined rather than an empty object when there is nothing to record. A surface that
+ * says nothing reads as a capture that looked for a location and found none, rather than one that
+ * never had one — and the second is the truth.
+ */
+/**
+ * Strip a trailing `:line` from a `file:line` label.
+ *
+ * Anchored to the END and to digits, because a Windows path carries its own colon: splitting on the
+ * first one turns `C:\\app\\src\\cart.tsx:12` into `C`, which is a path to nothing and would be
+ * filed as though it were real.
+ */
+const SOURCE_LINE_SUFFIX = /:\d+$/;
+export function surfaceForInlineIntent(url, flow, 
+/** `file` or `file:line` for the element the verdict acted on, when it had one. */
+sourceLabel) {
+    let route;
+    if (url !== undefined) {
+        try {
+            const path = new URL(url).pathname;
+            // A bare origin has no path worth filing under: `/` would put every record in one bucket,
+            // which is the problem this exists to fix rather than a solution to it.
+            if (path.length > 1)
+                route = path;
+        }
+        catch {
+            route = undefined;
+        }
+    }
+    /*
+     * The file, without its line.
+     *
+     * A record is about a FILE; the line is where one verdict happened to touch it, and keeping it
+     * would make the same rule look like a different one every time the file was edited above it.
+     */
+    const file = sourceLabel === undefined || 0 === sourceLabel.length
+        ? undefined
+        : sourceLabel.replace(SOURCE_LINE_SUFFIX, '');
+    if (route === undefined && flow === undefined && file === undefined)
+        return undefined;
+    return {
+        ...(route === undefined ? {} : { route }),
+        ...(flow === undefined ? {} : { flow }),
+        ...(file === undefined ? {} : { files: [file] }),
+    };
+}
+/**
+ * The session's live URL, or undefined when no session can be named.
+ *
+ * `sessions.resolve` throws for every "cannot tell which tab" case, and none of them is a reason to
+ * fail the caller's verdict — a missing surface costs a filing, not a result.
+ */
+function sessionUrl(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).url;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function linkInlineIntent(deps, sessionId, intent, 
+/** The predicate this verdict will evaluate, or undefined when it proves nothing (a bare settle). */
+binding) {
+    if (intent === undefined || 0 === intent.trim().length)
+        return undefined;
+    try {
+        const store = new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now });
+        const existing = (await store.read()).find((row) => row.id === intent);
+        const id = existing?.id ?? inlineIntentId(intent);
+        // Declared WITHOUT a surface on purpose: see dischargeInlineIntent for why the route that
+        // describes this record only exists after the action it is about.
+        if (existing === undefined)
+            await store.declare([{ id, statement: intent }]);
+        if (binding !== undefined && existing?.binding === undefined)
+            await store.bind(id, binding);
+        return id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Record that this verdict proved the intent. Call only for a verdict that actually proved something.
+ *
+ * The ledger's own rule does the rest: `dischargeIntent` refuses an intent with no binding, so an
+ * intent declared inline on a wait that asserted no consequence stays open and honest instead of
+ * collecting a proof nothing earned.
+ */
+export async function dischargeInlineIntent(deps, sessionId, id, proof, 
+/** `file:line` of the element this verdict acted on, when there was one. */
+sourceLabel) {
+    if (id === undefined)
+        return;
+    try {
+        const store = new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now });
+        /*
+         * File it HERE, not at declaration.
+         *
+         * The intent is declared before the action so a verdict can see it open, and at that instant the
+         * agent is still on the page it is leaving — clicking through to /issues from / would have filed
+         * the record under the page it left, or under nothing at all. The route that describes what the
+         * intent is about is the one that exists once the consequence has landed.
+         */
+        const surface = surfaceForInlineIntent(sessionUrl(deps, sessionId), undefined, sourceLabel);
+        if (surface !== undefined)
+            await store.place(id, surface);
+        await store.discharge(id, proof);
+    }
+    catch {
+        // The verdict already stood. The proof is simply not recorded — see dischargeFlowIntent.
+    }
+}

package/dist/intent/intent-shard-store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Reading and writing the sharded intent store, and migrating the flat one into it.
+ *
+ * The operations an agent actually performs, and what each is allowed to cost:
+ *
+ *   index()            every id + one line, always affordable — the session-start read
+ *   subject(name)      the full records for one subject, when it is about to work on that
+ *   get(id)            one record, via the index rather than by scanning shards
+ *   record()/update()  a write that touches ONE shard file plus the index
+ *
+ * The last one is the reason for the whole design. Under the flat file, changing one intent rewrote
+ * all 141, so two sessions touching unrelated subjects raced each other and the loser's write
+ * vanished. Sharded, they only collide when they genuinely edit the same subject.
+ *
+ * ## Migration is automatic, and it does not delete
+ *
+ * `.reticle/intent.json` is read on every load and folded in when the sharded copy has nothing for
+ * an id. That makes the move invisible: an agent on the new store sees old intents immediately, and
+ * an older build still reading the flat file keeps working, because nothing removes it. Deleting it
+ * is a separate decision somebody can take once they believe the migration.
+ */
+import { type Intent } from '@reticlehq/core';
+import type { FileSystemPort } from '../project/fs-port.js';
+import { IntentStatus, type IntentIndex, type IntentRecord } from './intent-shard.js';
+export interface Clock {
+    now: () => number;
+}
+/** What a caller supplies to write an intent. Everything optional is genuinely optional. */
+export interface IntentInput {
+    id: string;
+    statement: string;
+    subject?: string | undefined;
+    why?: string | undefined;
+    source?: string | undefined;
+    status?: IntentStatus | undefined;
+    surface?: Intent['surface'];
+    binding?: unknown;
+}
+export declare class IntentShardStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string, clock: Clock);
+    /**
+     * The cheap read: one line per intent, and the call an agent makes at the start of a session.
+     *
+     * Includes anything still only in the legacy flat file, so the very first call on an unmigrated
+     * project already answers completely — which is what makes the migration invisible rather than a
+     * step somebody has to remember to run.
+     */
+    index(): Promise<IntentIndex>;
+    /** Every record for one subject — the working read, once an agent knows what it is touching. */
+    subject(name: string): Promise<IntentRecord[]>;
+    /** One record by id, or null. */
+    get(id: string): Promise<IntentRecord | null>;
+    /**
+     * Write one intent, creating or updating it.
+     *
+     * Merges onto whatever is already stored, so a caller adding a `why` to a migrated record does not
+     * have to restate its binding — and cannot silently drop it by omission, which is the failure mode
+     * that makes agents afraid to touch a store.
+     */
+    record(input: IntentInput): Promise<IntentRecord>;
+    /**
+     * Fold the flat file into shards on disk, so the move is visible in a diff rather than implicit.
+     *
+     * Idempotent, and it does not delete `.reticle/intent.json`: an older build still reads it, and a
+     * migration that removes its own source cannot be checked afterwards.
+     */
+    migrate(): Promise<{
+        migrated: number;
+        subjects: string[];
+    }>;
+}