@reticlehq/server 3.5.0 → 3.7.0

package/dist/portal/session/recorded-gaps.js

@@ -0,0 +1,251 @@
+/**
+ * The instrumentation gaps each session's verdicts actually recorded, kept for the surfaces that
+ * describe an app rather than one verdict: the platform's app report, the HUD's coverage line and
+ * `doctor`. Fed from the one function every verdict's gaps already pass through (`withGapNovelty`),
+ * so nothing here surveys a page: a gap is listed only because a verdict paid for it.
+ *
+ * Deduped by kind + missing, newest first, bounded per session.
+ */
+import { withRunningDrive } from '../../features/harness/drive-runs.js';
+import { agentLinkOf } from './agent-link.js';
+import { CoverageMarker, InstrumentationGapKind, LINK_APP_GAPS_MAX, ReticleCommand, agentPromptFor, coverageOf, harnessGateOf, harnessUnlockPrompt, CoverageCapability, } from '@reticlehq/core';
+const bySession = new Map();
+const text = (value) => 'string' === typeof value && 0 < value.length ? value : undefined;
+/** Remember gaps a verdict on this session just reported. Malformed entries are skipped. */
+export function recordGaps(sessionId, gaps, now) {
+    let list = bySession.get(sessionId) ?? [];
+    for (const raw of gaps) {
+        const gap = raw;
+        const kind = text(gap['kind']);
+        const missing = text(gap['missing']);
+        const fix = text(gap['fix']);
+        if (kind === undefined || missing === undefined || fix === undefined)
+            continue;
+        const cost = text(gap['cost']);
+        const ref = text(gap['ref']);
+        const source = text(gap['source']);
+        list = [
+            {
+                kind,
+                missing,
+                fix,
+                seenAt: now,
+                ...(cost === undefined ? {} : { cost }),
+                ...(ref === undefined ? {} : { ref }),
+                ...(source === undefined ? {} : { source }),
+            },
+            ...list.filter((g) => g.kind !== kind || g.missing !== missing),
+        ].slice(0, LINK_APP_GAPS_MAX);
+    }
+    if (0 < list.length)
+        bySession.set(sessionId, list);
+}
+/**
+ * The app a tab shows, as a key: its project, else its origin. What one tab of an app has shown
+ * (a file:line, a test id) is a fact about the app, and a fresh tab of it has not acted yet: keyed
+ * by session alone, every new lease reported the app at 75% and the platform locked a Harness run
+ * mid-drive that it had let start at 87.5%.
+ */
+function appKeyOf(tab) {
+    if (tab.projectId !== undefined && 0 < tab.projectId.length)
+        return `project:${tab.projectId}`;
+    if (tab.url === undefined)
+        return undefined;
+    try {
+        return `origin:${new URL(tab.url).origin}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Sessions, and apps, where at least one verdict mapped a control to its file:line. */
+const sourceSeen = new Set();
+/** Mark a tab, and the app it shows, in a seen-set. */
+function markSeen(seen, tab) {
+    seen.add(tab.id);
+    const app = appKeyOf(tab);
+    if (app !== undefined)
+        seen.add(app);
+}
+/** Whether this tab, or any tab of its app, was marked. */
+function wasSeen(seen, tab) {
+    const app = appKeyOf(tab);
+    return seen.has(tab.id) || (app !== undefined && seen.has(app));
+}
+/** A verdict on this tab named a file:line: source mapping is seen, whatever else lacks one. */
+export function noteSourceSeen(tab, source) {
+    if (source !== undefined)
+        markSeen(sourceSeen, tab);
+}
+/** Sessions, and apps, where an acted element carried a `data-testid`. */
+const testidSeen = new Set();
+/** An acted element carried a test id: the app uses them, whatever one control lacks. */
+export function noteTestidSeen(tab, testid) {
+    if (testid !== undefined && 0 < testid.length)
+        markSeen(testidSeen, tab);
+}
+/** What an act result says about the element it reached: its test id and its source stamp. */
+export function noteActedElement(tab, result) {
+    if ('object' !== typeof result || null === result)
+        return;
+    const acted = result;
+    noteTestidSeen(tab, text(acted['testid']));
+    const source = acted['source'];
+    if ('object' === typeof source && null !== source) {
+        const file = text(source['file']);
+        if (file !== undefined)
+            markSeen(sourceSeen, tab);
+    }
+}
+/**
+ * An act's result, passed through after noting what it says about the element it reached. Every act
+ * dispatches through one function, so coverage sees test ids and source stamps from the first
+ * control acted on rather than only from a verdict.
+ */
+export function notedAct(tab, done) {
+    if (done.ok)
+        noteActedElement(tab, done.result);
+    return done;
+}
+/** The markers a page said it carries (`ReticleCommand.MARKERS`), marked for its tab and its app. */
+function noteMarkers(tab, result) {
+    if ('object' !== typeof result || null === result)
+        return;
+    const markers = result['markers'];
+    if (!Array.isArray(markers))
+        return;
+    if (markers.includes(CoverageMarker.SOURCE))
+        markSeen(sourceSeen, tab);
+    if (markers.includes(CoverageMarker.TESTID))
+        markSeen(testidSeen, tab);
+    const notApplicable = result['notApplicable'];
+    if (Array.isArray(notApplicable) && notApplicable.includes(CoverageCapability.SOURCE_MAPPING))
+        markSeen(sourceNotApplicable, tab);
+}
+/** Apps whose page said file:line cannot apply (plain HTML: no plugin, no framework, no stamp). */
+const sourceNotApplicable = new Set();
+/** How long a page gets to say what it carries. Silent and cheap, so a page that cannot is skipped. */
+const MARKERS_PROBE_MS = 2_000;
+/**
+ * Ask each page whose app has not shown both markers yet what it carries. What an act happens to
+ * reach decides nothing then: an app with test ids is seen to have them before anything acted, and a
+ * hidden tab of it says the same. A page that cannot answer (an older SDK, a closed tab) is skipped.
+ * True when a page showed something not known before.
+ */
+export async function probeMarkers(tabs) {
+    const before = sourceSeen.size + testidSeen.size;
+    await Promise.all(tabs
+        .filter((tab) => !(wasSeen(sourceSeen, tab) || wasSeen(sourceNotApplicable, tab)) ||
+        !wasSeen(testidSeen, tab))
+        .map(async (tab) => {
+        const done = await tab
+            .command?.(ReticleCommand.MARKERS, {}, MARKERS_PROBE_MS)
+            .catch(() => undefined);
+        if (true === done?.ok)
+            noteMarkers(tab, done.result);
+    }));
+    return before < sourceSeen.size + testidSeen.size;
+}
+/** What this session's verdicts recorded, newest first. */
+export function recordedGaps(sessionId) {
+    return bySession.get(sessionId) ?? [];
+}
+/** Forget a session that ended. What its app has shown is kept: it is still that app's. */
+export function forgetRecordedGaps(sessionId) {
+    bySession.delete(sessionId);
+    sourceSeen.delete(sessionId);
+    testidSeen.delete(sessionId);
+}
+/** Forget everything, apps included. For tests. */
+export function forgetAllRecordedGaps() {
+    bySession.clear();
+    sourceSeen.clear();
+    testidSeen.clear();
+    sourceNotApplicable.clear();
+}
+/**
+ * The tab's HELLO channels, plus the `source` marker when an act or verdict mapped a control to
+ * its file:line (seen anywhere is seen) or its page said it carries source mapping, and the
+ * `testid` marker once an acted element carried one — the list the platform report sends and
+ * coverage reads. A build that turned the stamp off has no source marker, whatever was seen.
+ */
+export function announcedChannels(tab) {
+    const channels = [...(tab.channels ?? [])];
+    const gaps = recordedGaps(tab.id);
+    // Only the build turning the stamp off overrules the page: one unmapped control does not mean
+    // the app has no source mapping (core's per-control rule).
+    const off = gaps.some((gap) => InstrumentationGapKind.SOURCE_MAPPING_OFF === gap.kind);
+    if (!off && (wasSeen(sourceSeen, tab) || true === tab.sourceMapping))
+        channels.push(CoverageMarker.SOURCE);
+    // Nothing announces test ids, so they are seen on an acted element — and a control the agent
+    // could only reach without one keeps the capability missing.
+    const noTestid = gaps.some((gap) => InstrumentationGapKind.MISSING_TESTID === gap.kind);
+    if (!noTestid && wasSeen(testidSeen, tab))
+        channels.push(CoverageMarker.TESTID);
+    return channels;
+}
+/** The app a tab shows, named for a prompt: its host, else its url. */
+const appNameOf = (url) => {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+};
+/**
+ * The coverage capabilities that do not apply to this tab's app, excluded from both sides of the
+ * score: file:line on a page that said it cannot apply there (plain HTML), until a stamp shows up.
+ * The platform reads the same list from the local-apps report, so both sides move together.
+ */
+export function notApplicableOf(tab) {
+    return wasSeen(sourceNotApplicable, tab) && !wasSeen(sourceSeen, tab)
+        ? [CoverageCapability.SOURCE_MAPPING]
+        : [];
+}
+/**
+ * This tab's coverage and its Harness gate, with the coding-agent prompt when its verdicts recorded
+ * any gap or the gate is shut: below the gate the prompt names every unseen capability, so there is
+ * always something to hand the agent.
+ */
+export function instrumentationOf(tab, 
+/** The app's other tabs: what any of them has seen or recorded counts, as on the platform. */
+siblings = []) {
+    const tabs = [tab, ...siblings];
+    const gaps = [
+        ...new Map(tabs.flatMap((each) => recordedGaps(each.id)).map((g) => [`${g.kind}\u0000${g.missing}`, g])).values(),
+    ];
+    const channels = [...new Set(tabs.flatMap((each) => announcedChannels(each)))];
+    const coverage = coverageOf({ channels, gaps });
+    const url = tab.url ?? '';
+    const appName = appNameOf(url);
+    const notApplicable = notApplicableOf(tab);
+    const gate = harnessGateOf(coverage, notApplicable);
+    const harnessGate = {
+        percent: gate.percent,
+        unlocked: gate.unlocked,
+        ...(gate.reason === undefined ? {} : { reason: gate.reason }),
+    };
+    if (!gate.unlocked)
+        return {
+            ...coverage,
+            harnessGate,
+            prompt: harnessUnlockPrompt({ coverage, gaps, appName, url, notApplicable }),
+        };
+    return 0 === gaps.length
+        ? { ...coverage, harnessGate }
+        : { ...coverage, harnessGate, prompt: agentPromptFor({ gaps, appName, url }) };
+}
+/**
+ * The impact snapshot a tab is pushed, carrying that tab's own coverage, running drive and agent
+ * link (who is attached, and this tab's notes to them). Every
+ * push needs the drive: one without it reads as "no drive", and the drive's own tool calls push.
+ */
+export function withInstrumentation(tab, snapshot) {
+    const pushed = {
+        ...snapshot,
+        instrumentation: { ...instrumentationOf(tab) },
+        agent: agentLinkOf(tab.inboxHistory?.() ?? []),
+    };
+    return withRunningDrive(pushed, tab.id) ?? pushed;
+}

package/dist/portal/session/serving-directory.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which directory the dev server that served a page runs in.
+ *
+ * The tie-breaker for a project several checkouts declare: every git worktree carries the same
+ * committed `.reticle.json`, so the projectId cannot tell them apart, but the process serving the
+ * page runs inside exactly one of them. Lives with the session rather than the artifact resolver
+ * because both observations are about this machine's processes -- daemon state files and `lsof` --
+ * which `memory/project` has no business knowing. The resolver takes the answer as an injected
+ * function; the composition roots pass this one.
+ */
+import { type DevServerEntry } from '@reticlehq/core';
+/** Where `servingDirectoryOf` gets its two observations. Injected so a test needs no processes. */
+export interface ServingDirectoryIo {
+    /** Live dev servers that announced themselves (the Vite plugin writes `devserver-<port>.json`). */
+    devServers: () => readonly DevServerEntry[];
+    /** The working directory of whatever listens on `port`, or null when it cannot be read. */
+    listenerCwd: (port: number) => string | null;
+}
+/**
+ * The directory of the dev server that served `origin`, or undefined when it cannot be observed.
+ *
+ * Two observations, exact one first. A dev server whose plugin announced this port names its own
+ * root and works on every platform. Otherwise the process listening on the port is asked for its
+ * working directory, which covers frameworks with no announcing plugin (Next.js) wherever `lsof`
+ * runs. Loopback only: a remote page's port says nothing about any process on this machine.
+ */
+export declare function servingDirectoryOf(origin: string, io?: ServingDirectoryIo): string | undefined;

package/dist/portal/session/serving-directory.js

@@ -0,0 +1,45 @@
+/**
+ * Which directory the dev server that served a page runs in.
+ *
+ * The tie-breaker for a project several checkouts declare: every git worktree carries the same
+ * committed `.reticle.json`, so the projectId cannot tell them apart, but the process serving the
+ * page runs inside exactly one of them. Lives with the session rather than the artifact resolver
+ * because both observations are about this machine's processes -- daemon state files and `lsof` --
+ * which `memory/project` has no business knowing. The resolver takes the answer as an injected
+ * function; the composition roots pass this one.
+ */
+import { isLoopbackHostname } from '@reticlehq/core';
+import { captureLookup, findListenerCwd } from '../../command/cli/ports/port-holder.js';
+import { reticleStateHome } from '../../command/daemon/daemon.js';
+import { readDevServers } from '../../command/daemon/dev-servers.js';
+const DEFAULT_PORT = { 'http:': 80, 'https:': 443 };
+const liveIo = {
+    devServers: () => readDevServers(reticleStateHome()),
+    listenerCwd: (port) => findListenerCwd(port, captureLookup),
+};
+/**
+ * The directory of the dev server that served `origin`, or undefined when it cannot be observed.
+ *
+ * Two observations, exact one first. A dev server whose plugin announced this port names its own
+ * root and works on every platform. Otherwise the process listening on the port is asked for its
+ * working directory, which covers frameworks with no announcing plugin (Next.js) wherever `lsof`
+ * runs. Loopback only: a remote page's port says nothing about any process on this machine.
+ */
+export function servingDirectoryOf(origin, io = liveIo) {
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isLoopbackHostname(url.hostname))
+        return undefined;
+    const port = '' === url.port ? DEFAULT_PORT[url.protocol] : Number(url.port);
+    if (port === undefined)
+        return undefined;
+    const announced = io.devServers().find((entry) => entry.port === port);
+    if (announced !== undefined)
+        return announced.root;
+    return io.listenerCwd(port) ?? undefined;
+}

package/dist/portal/session/session-health.d.ts

@@ -75,6 +75,17 @@ export interface SessionHealth {
  * That is the trade: an over-firing field gets ignored, and a field nobody reads catches nothing.
  */
 export declare const PENDING_NAVIGATION_NOTICE_MS = 10000;
+/**
+ * Said beside `dispatched` / `settled` on a skewed session, because those fields read as success.
+ *
+ * The reporter's own account of the cost: "the false-positive dispatch confirmation is what cost the
+ * most time — I trusted `dispatched: true, domMutatedWithin: Nms` as real signal for a long time
+ * before suspecting the skew banner." Stating the contradiction is the whole job here; the existing
+ * banner was accurate and simply never appeared where it was needed.
+ */
+/** The skew warning after an agent has read the paragraph once this session. */
+export declare const SKEW_SHORT_WARNING = "version skew: `dispatched`/`settled` here do not prove the app acted \u2014 see session.versionSkew.";
+export declare const SKEW_VERDICT_WARNING: string;
 /**
  * The age of the oldest request that STARTED and never completed, or undefined when there is none
  * worth reporting.
@@ -163,6 +174,13 @@ interface HealthReport {
      * closed list is that an unbounded string can never reach telemetry through it.
      */
     brand: BrowserBrand | undefined;
+    /** Only the keys the page reported, so merging it never erases one an earlier report set. */
+    page: PageIdentity;
+}
+/** Which desktop window a session is, and what its document was served with. */
+export interface PageIdentity {
+    windowLabel?: string;
+    documentStatus?: number;
 }
 /**
  * Narrow a PAGE_HEALTH payload. Every field is optional on the wire — an older SDK does not report

package/dist/portal/session/session-health.js

@@ -27,7 +27,9 @@ export const PENDING_NAVIGATION_NOTICE_MS = 10_000;
  * before suspecting the skew banner." Stating the contradiction is the whole job here; the existing
  * banner was accurate and simply never appeared where it was needed.
  */
-const SKEW_VERDICT_WARNING = 'version skew: `dispatched` and `settled` on this session mean the event was sent, NOT that the ' +
+/** The skew warning after an agent has read the paragraph once this session. */
+export const SKEW_SHORT_WARNING = 'version skew: `dispatched`/`settled` here do not prove the app acted — see session.versionSkew.';
+export const SKEW_VERDICT_WARNING = 'version skew: `dispatched` and `settled` on this session mean the event was sent, NOT that the ' +
     'app acted on it — a skewed pair drops actions silently. Re-read the control (aria-checked, ' +
     'data-state, its text) before trusting any verdict from this session, and converge the versions ' +
     '(see session.versionSkew).';
@@ -161,6 +163,12 @@ export function readHealthEvent(data) {
         runtime: 'string' === typeof data['runtime'] ? data['runtime'] : undefined,
         engine: 'string' === typeof data['engine'] ? data['engine'] : undefined,
         brand: Object.values(BrowserBrand).find((known) => known === data['brand']),
+        page: {
+            ...('string' === typeof data['windowLabel'] ? { windowLabel: data['windowLabel'] } : {}),
+            ...(Number.isInteger(data['documentStatus'])
+                ? { documentStatus: data['documentStatus'] }
+                : {}),
+        },
     };
 }
 /**

package/dist/portal/session/session-info.d.ts

@@ -1,4 +1,6 @@
-import type { SessionHealth } from './session-health.js';
+import type { PageIdentity, SessionHealth } from './session-health.js';
+/** A document served as 4xx/5xx — a dev server's 404 page that still mounted the SDK, say. */
+export declare function isErrorDocument(page: PageIdentity | undefined): boolean;
 export interface SessionInfo {
     sessionId: string;
     url: string;
@@ -17,6 +19,10 @@ export interface SessionInfo {
      * not render like it.
      */
     runtime?: string;
+    /** The desktop window's own name (Tauri's label: `main`, `setup`) — absent on a web page. */
+    window?: string;
+    /** Present only when the document was served as an error (4xx/5xx): a 404 page is not the app. */
+    documentStatus?: number;
     /** Present only when the page's SDK version differs from the daemon's — see version-skew.ts. */
     versionSkew?: string;
     /** ms since the SDK last reported anything (silence ⇒ likely throttled). */
@@ -72,6 +78,7 @@ interface SessionView {
     runtime: string | undefined;
     versionSkew: string | undefined;
     hidden: boolean;
+    page?: PageIdentity;
     health: () => SessionHealth;
     staleMs: () => number;
     pendingMarkCount: () => number;

package/dist/portal/session/session-info.js

@@ -6,6 +6,10 @@
  * it, and separating them keeps the wire-facing shape reviewable on its own.
  */
 import { SESSION_LEASE } from '@reticlehq/core';
+/** A document served as 4xx/5xx — a dev server's 404 page that still mounted the SDK, say. */
+export function isErrorDocument(page) {
+    return (page?.documentStatus ?? 0) >= 400;
+}
 /**
  * Project a live Session into the shape the tools return.
  *
@@ -27,6 +31,8 @@ export function buildSessionInfo(session) {
         hasCapabilities: session.hasCapabilities,
         // Omitted when the page never said, so absence stays readable as "unknown" rather than "web".
         ...(session.runtime === undefined ? {} : { runtime: session.runtime }),
+        ...(session.page?.windowLabel === undefined ? {} : { window: session.page.windowLabel }),
+        ...(isErrorDocument(session.page) ? { documentStatus: session.page?.documentStatus ?? 0 } : {}),
         // On every listing, not buried in a log — skew explains failures that read as app bugs.
         ...(session.versionSkew === undefined ? {} : { versionSkew: session.versionSkew }),
         hidden: session.hidden,
@@ -43,7 +49,8 @@ export function buildSessionInfo(session) {
         base.unresponsive = true;
         base.unresponsive_suggestion =
             'This tab is connected but has stopped answering commands, so every call against it will time ' +
-                'out. Ending the session does not revive the page. Reload the tab, or run `reticle open <url>` ' +
+                'out. Ending the session does not revive the page. Reload the tab, or run ' +
+                '`npx @reticlehq/server open <url>` ' +
                 'to get a fresh one — it will no longer hand this tab back.';
     }
     // Surface human bug reports in reticle_sessions (only when > 0, so a clean session adds nothing).

package/dist/portal/session/session-manager.d.ts

@@ -14,6 +14,17 @@ interface ResolveScope {
 }
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export declare function originOf(url: string | undefined): string | undefined;
+/**
+ * Honest, scoped error when sessions exist but none match the agent's project.
+ *
+ * The daemon takes its default scope from the `.reticle.json` of whichever directory started it, so
+ * attaching from a second project — or another worktree of the SAME project — makes every tool
+ * refuse while `reticle_sessions` shows the tab sitting right there. The old message asked "is that
+ * app running with @reticlehq/core enabled?", which is the one thing that is definitely true, so the
+ * reader goes looking at their app instead of at the scope. Name what IS connected and how to
+ * target it: both facts are already in hand here.
+ */
+export declare function scopeMissError(connected: Session[], scope?: ResolveScope): string;
 /** What a refused hello said about itself: the page it was on and the project it claimed. */
 export interface RefusedPage {
     readonly url?: string;
@@ -31,6 +42,16 @@ export declare class SessionManager {
     setDefaultScope(scope: ResolveScope | undefined): void;
     setConnectionRecorder(record: ((projectId: string | undefined) => void) | undefined): void;
     add(session: Session): Session | undefined;
+    /**
+     * Close a window's connection and refuse its id until the daemon restarts.
+     *
+     * Reported from a Tauri app whose hidden windows kept reconnecting: ending the session only ended
+     * the presenter, so the window came straight back. A reload keeps its id (sessionStorage), so the
+     * id is what stays parked; the 1008 close tells the SDK not to retry. Its tombstone goes too, so a
+     * call naming it is refused rather than handed a sibling window.
+     */
+    park(session: Session): void;
+    isParked(sessionId: string): boolean;
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
     /**
@@ -47,6 +68,13 @@ export declare class SessionManager {
     attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all(): Session[];
+    /**
+     * The connected sessions an id-less call may consider: the active project's, when one is set.
+     *
+     * The same set `resolve()` chooses from, so a caller that falls back from a refused resolution
+     * (an id-less yield) never reaches a tab the project scope would never have handed it.
+     */
+    inScope(): Session[];
     count(): number;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint: (() => string | undefined) | undefined): void;
@@ -68,6 +96,8 @@ export declare class SessionManager {
     setNoSessionNextAction(next: (() => NoSessionNextAction | undefined) | undefined): void;
     noSessionNextAction(): NoSessionNextAction | undefined;
     everConnected(): boolean;
+    /** Whether a session for this project has registered since boot. An unknown id has not. */
+    everConnectedTo(projectId: string): boolean;
     /**
      * Record a bridge-initiated close so `resolve` can explain a session that vanished.
      *
@@ -99,6 +129,15 @@ export declare class SessionManager {
      * a connected tab is in `list()`, not here.
      */
     lastKnown(): SessionIdentity | undefined;
+    /**
+     * The most recent departed session for one project.
+     *
+     * `lastKnown` is the newest tombstone of any project. A shared daemon that quoted it to every
+     * caller told the second project to reopen the first project's tab.
+     */
+    lastKnownFor(projectId: string): SessionIdentity | undefined;
+    /** Every departed session's URL, oldest first. The port scan has to see all of them, not only the newest. */
+    tombstoneUrls(): readonly string[];
     resolve(sessionId?: string, scope?: ResolveScope): Session;
 }
 export {};