@reticlehq/server 3.6.0 → 3.7.0

package/dist/surface/tools/agent/reteach.js

@@ -0,0 +1,50 @@
+/**
+ * Re-teach on a mistake the primer covers: ONE line, once per rule per agent session.
+ *
+ * After a compaction the agent keeps calling, but the rules it read at the start are gone. The daemon
+ * still knows it is the same agent (same MCP connection), and it can see the mistake in the call it
+ * just answered. So the answer carries the one rule that call broke — and costs nothing when the
+ * agent behaves. Deduplication is `foldNotices`' once-per-session rule.
+ *
+ * Advice only: computed from a result that is already decided, returned as a sentence.
+ */
+import { ReticleTool, Verified, asRecord } from '@reticlehq/core';
+export const ReteachLine = {
+    NO_UNTIL: 'Rule: name the consequence in `until` BEFORE acting — without it the result is "no-fault", which proves nothing.',
+    ALIAS: 'Rule: write predicates in their canonical spelling (see `normalized`); aliases are a courtesy, not the API.',
+    CASE: 'Rule: text checks are exact-case — use ignoreCase: true only when the case truly does not matter.',
+    RELIST: 'Rule: you already have this tab — reuse its sessionId (or omit it) instead of listing sessions again.',
+    COMPACTED: 'Lost track (context compacted)? reticle_run { tool: "reticle_context", args: { compact: true } } returns what this session proved, failed and still owes.',
+};
+const listCounts = new Map();
+/** Tests only. */
+export function resetReteach() {
+    listCounts.clear();
+}
+/** The rule this call broke, if any. */
+export function reteachFor(session, tool, args, result) {
+    const lines = [];
+    if (ReticleTool.ACT_AND_WAIT === tool &&
+        args['until'] === undefined &&
+        args['predicate'] === undefined) {
+        if (Verified.NO_FAULT === result['verified'])
+            lines.push(ReteachLine.NO_UNTIL);
+    }
+    if (Array.isArray(result['normalized']) && result['normalized'].length > 0)
+        lines.push(ReteachLine.ALIAS);
+    const verdict = 'object' === typeof result['verdict'] && null !== result['verdict']
+        ? asRecord(result['verdict'])
+        : result;
+    if (true === verdict['caseOnlyMiss'])
+        lines.push(ReteachLine.CASE);
+    const listing = ReticleTool.SESSIONS === tool ||
+        (ReticleTool.SESSION === tool && (args['action'] === undefined || 'list' === args['action']));
+    if (listing && Array.isArray(result['sessions']) && result['sessions'].length > 0) {
+        const seen = (listCounts.get(session) ?? 0) + 1;
+        listCounts.set(session, seen);
+        // The third listing in one session: the first two are orientation, a third is a lost thread.
+        if (seen >= 3)
+            lines.push(ReteachLine.RELIST, ReteachLine.COMPACTED);
+    }
+    return lines;
+}

package/dist/surface/tools/args/alias-args.d.ts

@@ -15,3 +15,8 @@
  * missing instead of being replaced by a guess.
  */
 export declare function aliasParam(args: Record<string, unknown>, canonical: string, aliases: readonly string[]): Record<string, unknown>;
+/**
+ * The alias a call used for `canonical`, named the way a verdict tool names a normalised predicate
+ * (`normalized: ["name → flowName"]`): accepted, and said, so the agent learns the real spelling.
+ */
+export declare function aliasUsed(args: Record<string, unknown>, canonical: string, aliases: readonly string[]): string[];

package/dist/surface/tools/args/alias-args.js

@@ -23,3 +23,13 @@ export function aliasParam(args, canonical, aliases) {
     }
     return args;
 }
+/**
+ * The alias a call used for `canonical`, named the way a verdict tool names a normalised predicate
+ * (`normalized: ["name → flowName"]`): accepted, and said, so the agent learns the real spelling.
+ */
+export function aliasUsed(args, canonical, aliases) {
+    if (args[canonical] !== undefined)
+        return [];
+    const alias = aliases.find((name) => args[name] !== undefined);
+    return alias === undefined ? [] : [`${alias} → ${canonical}`];
+}

package/dist/surface/tools/args/confirm-dangerous-arg.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+/**
+ * The per-call acknowledgement of steps the replay guard holds as destructive. Never persisted into
+ * a flow: a destructive confirmation is a decision made for one run.
+ */
+export declare const confirmDangerousArg: (scope: string) => z.ZodOptional<z.ZodBoolean>;

package/dist/surface/tools/args/confirm-dangerous-arg.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+/**
+ * The per-call acknowledgement of steps the replay guard holds as destructive. Never persisted into
+ * a flow: a destructive confirmation is a decision made for one run.
+ */
+export const confirmDangerousArg = (scope) => z.boolean().optional().describe(`Set true to allow destructive controls during ${scope} only.`);

package/dist/surface/tools/assert/assert-source.d.ts

@@ -1,5 +1,20 @@
 import type { Predicate } from '@reticlehq/engine/question/predicate/predicate-schema.js';
 import type { Session } from '../../../portal/session/session.js';
+/**
+ * Any `data-reticle-source` stamp on an ELEMENT anywhere in an assertion's evidence, near misses
+ * included.
+ *
+ * Not a pointer to report: `assertSource` decides that, and it refuses a near miss because that is
+ * a different element. This answers a narrower question, the one the `no-source-mapping` gap asks:
+ * does this build stamp its elements at all? A near miss that carries `source` proves it does, so a
+ * failure whose only located element is a near miss must not tell the agent to install a plugin
+ * that is already working (#1422).
+ *
+ * Only element descriptors count (they carry a `ref` or a `tag`): a console error's `source` is the
+ * browser's script URL and says nothing about build stamps. The depth bound is generous enough for
+ * nested `allOf`/`anyOf` evidence and exists only because evidence is page-supplied.
+ */
+export declare function stampedSourceIn(evidence: unknown, depth?: number): string | undefined;
 /**
  * The `file:line` an ASSERTION is entitled to report — its own evidence, or nothing.
  *

package/dist/surface/tools/assert/assert-source.js

@@ -28,6 +28,46 @@ function evidenceSource(evidence) {
     }
     return agreed;
 }
+/**
+ * Any `data-reticle-source` stamp on an ELEMENT anywhere in an assertion's evidence, near misses
+ * included.
+ *
+ * Not a pointer to report: `assertSource` decides that, and it refuses a near miss because that is
+ * a different element. This answers a narrower question, the one the `no-source-mapping` gap asks:
+ * does this build stamp its elements at all? A near miss that carries `source` proves it does, so a
+ * failure whose only located element is a near miss must not tell the agent to install a plugin
+ * that is already working (#1422).
+ *
+ * Only element descriptors count (they carry a `ref` or a `tag`): a console error's `source` is the
+ * browser's script URL and says nothing about build stamps. The depth bound is generous enough for
+ * nested `allOf`/`anyOf` evidence and exists only because evidence is page-supplied.
+ */
+export function stampedSourceIn(evidence, depth = 0) {
+    if (depth > MAX_EVIDENCE_DEPTH || 'object' !== typeof evidence || null === evidence) {
+        return undefined;
+    }
+    if (Array.isArray(evidence)) {
+        for (const entry of evidence) {
+            const found = stampedSourceIn(entry, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    const entry = evidence;
+    const isElement = 'string' === typeof entry.ref || 'string' === typeof entry.tag;
+    if (isElement && 'string' === typeof entry.source && 0 < entry.source.length) {
+        return entry.source;
+    }
+    for (const value of Object.values(evidence)) {
+        const found = stampedSourceIn(value, depth + 1);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** How deep `stampedSourceIn` follows nested evidence: combinators nest, a page could nest forever. */
+const MAX_EVIDENCE_DEPTH = 16;
 /**
  * The `file:line` an ASSERTION is entitled to report — its own evidence, or nothing.
  *

package/dist/surface/tools/assert/assert-verdict.js

@@ -17,8 +17,9 @@ import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
 import { describeWaitTarget, namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.js';
 import { inFlightRequestLabels, repeatedRequestLabels, } from '../act/settle-in-flight.js';
 import { gradeOfPredicate } from './assert-grade.js';
-import { assertSource } from './assert-source.js';
+import { assertSource, stampedSourceIn } from './assert-source.js';
 import { VerdictAttribution, verdictAttributionOf } from '@reticlehq/core';
+import { noteSourceSeen } from '../../../portal/session/recorded-gaps.js';
 /**
  * The honesty verdict for a plain `reticle_assert`.
  *
@@ -58,7 +59,9 @@ changeUndeclared) {
     // over-warning, which is the correct direction here: the failure this guards against is a green
     // that implies coverage it never had, and a needless caveat costs the agent a sentence.
     const spots = blindSpotsFromState(session.blindSpots(), session.runtime);
-    const statement = buildCoverageStatement(spots);
+    // The window's own counts, so sampling before it is not described as this window's (#1414).
+    const windowSpots = blindSpotsFromState(session.blindSpots(since), session.runtime);
+    const statement = buildCoverageStatement(spots, windowSpots);
     const absenceBlindSpot = absenceBlindSpotNote(predicate, spots);
     // A green resting on hidden matches says the node exists, not that it shows (#1408).
     const hiddenMatch = hiddenMatchNote(predicate, evidence);
@@ -94,12 +97,15 @@ changeUndeclared) {
         background: session.background,
         expectedFailures: declared.netFailures,
         namedNetUrls: declared.netUrls,
+        repeatableNetUrls: declared.repeatableNetUrls,
         renderProved: pass && declared.rendersContent,
         ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
     });
     // Only a spot that IMPEACHES the capture downgrades a general verdict. Structural boundaries are
     // reported as coverage; the narrower absence exception is computed separately above.
-    const impeaching = buildCoverageStatement(spots.filter((sp) => impeachesCapture(sp.kind)));
+    const impeaching = buildCoverageStatement(
+    // The WINDOW's blind spots: sampling before it is a coverage fact, not this verdict's gap (#1414).
+    windowSpots.filter((sp) => impeachesCapture(sp.kind)));
     // A gap in the WINDOW, as opposed to a standing limit of the page. Both mean the same thing to the
     // rule — part of what happened was not seen — so both belong in `blindSpots`, which is the only
     // input `decideVerified` reads for that.
@@ -207,13 +213,25 @@ changeUndeclared) {
             repeated: repeatedRequestLabels(windowEvents),
         },
     });
+    // The one file:line this verdict is entitled to: its own evidence, or — for a failure with no DOM
+    // clause to point at — the control last driven. Returned so the RESPONSE can echo the same value
+    // the journal keeps; one verdict must never carry two different pointers.
+    const source = assertSource({
+        predicate,
+        evidence,
+        pass,
+        lastActSource: session.lastAct.source(),
+    });
     // The same rule the act path uses, fed by what THIS path knows. An assertion drives nothing, so
-    // only two of the four gates can fire here: a red with no remembered source to point at, and a
-    // state assertion against an app that registers no store.
+    // only two of the four gates can fire here: a red with nothing located, and a state assertion
+    // against an app that registers no store. "Nothing located" reads the verdict's own source first,
+    // then any stamp in its evidence (a near miss carries one), and only then the last act: before,
+    // it read only the last act, so a red asked before any act reported `no-source-mapping` while its
+    // own near misses carried file:line (#1422).
     const gaps = gapsForAction({
         pass,
         ...(changeUndeclared === undefined ? {} : { changeUndeclared }),
-        source: session.lastAct.source(),
+        source: source ?? stampedSourceIn(evidence) ?? session.lastAct.source(),
         stateAsked: declaresState(predicate),
         stateUnwatched: isStateUnwatched(spots),
         // What the app DECLARED, so an under-instrumented one is told without having to be asked.
@@ -224,16 +242,8 @@ changeUndeclared) {
         domMutated: false,
         signalsFired: 0,
     });
+    noteSourceSeen(session, source ?? stampedSourceIn(evidence));
     noteSessionGaps(session, gaps);
-    // The one file:line this verdict is entitled to: its own evidence, or — for a failure with no DOM
-    // clause to point at — the control last driven. Returned so the RESPONSE can echo the same value
-    // the journal keeps; one verdict must never carry two different pointers.
-    const source = assertSource({
-        predicate,
-        evidence,
-        pass,
-        lastActSource: session.lastAct.source(),
-    });
     // Who can act on this verdict, derived from the clause that decided it — see `attributedTo` below.
     const attributedTo = verdictAttributionOf(decision.verifiedReason);
     return {

package/dist/surface/tools/browser-tools.js

@@ -9,6 +9,32 @@ import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { sessionIdShape, commandOrThrow } from './tool-kit.js';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
+/** Said when a lease's page now has no Reticle SDK: only the browser can still act on it. */
+const MSG_LEASE_WITHOUT_SDK = 'This page has no Reticle SDK, so only browser-level actions apply here (navigate, screenshot). ' +
+    'The lease is kept: navigate back to the app and it reattaches.';
+/** Navigate a lease through its browser page, and wait for its SDK to come back. */
+async function navigateLease(deps, sessionId, url, args) {
+    const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
+    const went = (await deps.pool?.gotoLease(sessionId, url, timeoutMs)) ?? false;
+    if (!went)
+        return { ok: false, url, reason: 'the leased page did not navigate' };
+    const back = await waitForSession(deps, sessionId, timeoutMs);
+    return back
+        ? { ok: true, url, confirmed: true, sessionId }
+        : { ok: true, url, confirmed: false, waitedMs: timeoutMs, note: MSG_LEASE_WITHOUT_SDK };
+}
+/** Whether the session reconnects within the budget. */
+async function waitForSession(deps, sessionId, timeoutMs) {
+    const start = deps.now();
+    for (;;) {
+        if (deps.sessions.get(sessionId) !== undefined)
+            return true;
+        if (deps.now() - start >= timeoutMs)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, LEASE_POLL_MS));
+    }
+}
+const LEASE_POLL_MS = 100;
 export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
@@ -85,6 +111,16 @@ export const BROWSER_TOOLS = [
             const requested = asString(args['url']);
             if (requested === undefined || 0 === requested.length)
                 return { ok: false, reason: 'url required' };
+            const named = asString(args['sessionId']);
+            // A lease whose page has no SDK right now (it was navigated to an image, a PDF, another site):
+            // the page is still the lease's, so it is navigated through the browser and reattaches when it
+            // is back on the app, instead of answering "no connected session" for good.
+            if (named !== undefined && deps.sessions.get(named) === undefined) {
+                const leaseUrl = deps.pool?.leaseUrl(named);
+                if (leaseUrl !== undefined) {
+                    return navigateLease(deps, named, carryReticleIdentity(leaseUrl, requested), args);
+                }
+            }
             // Record navigate as an action. Its window is usually empty (the page unloads and the SDK
             // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
             const session = deps.sessions.resolve(asString(args['sessionId']));
@@ -125,7 +161,13 @@ export const BROWSER_TOOLS = [
                         priorIds,
                     }, timeoutMs)
                     : null;
-                return navigateResult(result, arrival, timeoutMs);
+                const answer = navigateResult(result, arrival, timeoutMs);
+                // A lease navigated off its app (an image, a PDF) is kept, and says what still works.
+                const offApp = null === arrival &&
+                    true === result.ok &&
+                    deps.pool?.leaseUrl(session.id) !== undefined &&
+                    deps.sessions.get(session.id) === undefined;
+                return offApp ? { ...answer, note: MSG_LEASE_WITHOUT_SDK } : answer;
             }
             finally {
                 session.finishAction();

package/dist/surface/tools/chat-drives.d.ts

@@ -2,6 +2,9 @@ import type { SessionInfo } from '../../portal/session/session-info.js';
 import { LinkCapability, type PresenterTone } from '@reticlehq/core';
 import type { ToolDeps } from './tool-kit.js';
 import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import { type ProbedTab } from '../../portal/session/recorded-gaps.js';
+import { type FreeDrive } from '../../features/harness/platform/platform-drives.js';
+import { HumanControlKind, type LinkUnsyncedRoot } from '@reticlehq/core';
 /** What this daemon does for the platform's chat. Each one is listed only once it is built. */
 export declare const CHAT_CAPABILITIES: readonly LinkCapability[];
 /** The slice of the session manager this needs. */
@@ -11,6 +14,16 @@ export interface ChatDriveSessions {
     get(id: string): {
         autoEnd(text: string, tone: PresenterTone): void;
         pushNarration(text: string): void;
+        readonly sdkVersion?: string | undefined;
+        readonly channels?: readonly string[] | undefined;
+        /** Asks the page what it carries (`probeMarkers`). Absent on a test double. */
+        command?: ProbedTab['command'];
+        readonly sourceMapping?: boolean | undefined;
+    } | undefined;
+    /** The last page handshake the bridge refused, when there was one. */
+    lastClosure?(): {
+        at: number;
+        reason: string;
     } | undefined;
 }
 export interface ChatDriveCloud {
@@ -20,7 +33,69 @@ export interface ChatDriveCloud {
         apiKey: string;
     } | undefined>;
     version: string;
+    /** Folders holding runs the platform never got (the sync daemon's last count). Absolute roots. */
+    unsynced?: () => readonly {
+        root: string;
+        runs: number;
+        linked: boolean;
+    }[];
 }
 export declare function startChatDrives(deps: ToolDeps, sessions: ChatDriveSessions, fs: FileSystemPort, cloud: ChatDriveCloud, log: (line: string) => void): {
     stop: () => void;
 };
+/**
+ * The panel's Harness controls. The switch is the platform's autonomous mode, unchanged. Run Harness
+ * and Stop drive. A run asks the platform for the drive's grant, then starts it
+ * through the same explore an agent calls (counted, recorded, polled the same way); its lines and
+ * steps reach the HUD log as the drive narrates them. A refused grant says why, and where to start
+ * a trial when it wants a card.
+ */
+export declare function hudDrive(deps: ToolDeps, sessionId: string, 
+/** The panel's control, as the bridge narrowed it (`harness-request.ts`). */
+request: {
+    kind: typeof HumanControlKind.HARNESS;
+    enabled: boolean;
+} | {
+    kind: typeof HumanControlKind.HARNESS_RUN;
+    persona?: string;
+} | {
+    kind: typeof HumanControlKind.HARNESS_STOP;
+}, 
+/** The autonomous switch: written through to the platform, which the daemon owns. */
+applySwitch: (enabled: boolean) => void, grant?: (platform: {
+    url: string;
+    apiKey: string;
+}) => Promise<FreeDrive>): Promise<void>;
+/**
+ * The link a panel sign-in makes once it lands: the tab's project, never a page that did not say
+ * which project it is (that would bind a hash-named project nothing here reads).
+ */
+export declare function projectLinkOnly(link: ((root: string) => Promise<number>) | undefined): ((root: string) => Promise<number>) | undefined;
+/**
+ * The panel's Harness controls on a bridge: the switch writes through to the platform, so console
+ * and panel cannot disagree; Run and Stop drive, in the project of the tab that asked.
+ */
+export declare function attachHudHarness(bridge: {
+    attachHarnessRequest(handler: (request: Parameters<typeof hudDrive>[2] | {
+        kind: typeof HumanControlKind.HARNESS_LINK;
+    }, session: {
+        id: string;
+        artifactRoot?: string | undefined;
+    }) => void): void;
+}, daemon: {
+    /** Read when a control arrives: the daemon builds its deps after it wires the bridge. */
+    deps: () => ToolDeps;
+    /** Where a tab with no project of its own drives. */
+    root: string;
+    /** Repaint every panel, so a running drive shows its Stop button and a finished one hides it. */
+    repaint: () => void;
+}, applySwitch: (root: string, on: boolean) => void, 
+/** Link this project: what `reticle connect` does from that folder. Absent: the button says so. */
+link?: (root: string) => Promise<number>): void;
+/**
+ * The `unsynced` field of a report. Sent empty too, once this daemon has counted: the platform reads
+ * an absent list as "no news" and kept a "never sent" banner for runs that had long been sent.
+ */
+export declare function unsyncedReport(unsynced: readonly LinkUnsyncedRoot[] | undefined, home: string): {
+    unsynced?: LinkUnsyncedRoot[];
+};