@reticlehq/server 3.8.0 → 3.8.2

package/dist/surface/tools/empty-session-list.d.ts

@@ -6,7 +6,7 @@ import type { ToolDeps } from './tool-kit.js';
 export declare const EMPTY_SESSION_LIST_OUTPUT: {
     why: z.ZodOptional<z.ZodString>;
     next_action: z.ZodOptional<z.ZodObject<{
-        action: z.ZodNativeEnum<{
+        action: z.ZodEnum<{
             readonly START_DEV_SERVER: "start_dev_server";
             readonly RUN_INIT: "run_init";
             readonly OPEN_APP: "open_app";
@@ -16,44 +16,20 @@ export declare const EMPTY_SESSION_LIST_OUTPUT: {
         command: z.ZodOptional<z.ZodString>;
         port: z.ZodOptional<z.ZodNumber>;
         reason: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        action: "start_dev_server" | "run_init" | "open_app" | "reopen_app" | "daemon_split";
-        reason: string;
-        port?: number | undefined;
-        command?: string | undefined;
-    }, {
-        action: "start_dev_server" | "run_init" | "open_app" | "reopen_app" | "daemon_split";
-        reason: string;
-        port?: number | undefined;
-        command?: string | undefined;
-    }>>;
+    }, z.core.$strip>>;
     talk_to_us: z.ZodOptional<z.ZodString>;
     next_step: z.ZodOptional<z.ZodObject<{
-        offered: z.ZodNativeEnum<{
+        offered: z.ZodEnum<{
             readonly LEASE: "lease";
             readonly INIT_CONSENT: "init_consent";
         }>;
         lease: z.ZodOptional<z.ZodString>;
         consent: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        offered: "lease" | "init_consent";
-        consent: string;
-        lease?: string | undefined;
-    }, {
-        offered: "lease" | "init_consent";
-        consent: string;
-        lease?: string | undefined;
-    }>>;
+    }, z.core.$strip>>;
     lastKnown: z.ZodOptional<z.ZodObject<{
         sessionId: z.ZodString;
         url: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        sessionId: string;
-        url: string;
-    }, {
-        sessionId: string;
-        url: string;
-    }>>;
+    }, z.core.$strip>>;
 };
 /**
  * The next step for the calling project when another project's tab is the one connected.

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

@@ -153,7 +153,7 @@ export const FEEDBACK_TOOLS = [
             accepted: z.boolean(),
             reason: z.string().optional(),
             redacted: z.array(z.string()),
-            context: z.unknown(),
+            context: z.unknown().optional(),
             note: z.string(),
         },
         example: {

package/dist/surface/tools/gap-novelty.d.ts

@@ -43,5 +43,5 @@ export declare function resetGapNovelty(): void;
  * The output-schema entry for `engineBlindSpots`, shared by every verdict tool so they cannot word
  * it two ways. See `EngineBlindSpotKind` in core.
  */
-export declare const engineBlindSpotsOutput: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+export declare const engineBlindSpotsOutput: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
 export {};

package/dist/surface/tools/gaps/capability-absences.js

@@ -27,9 +27,10 @@ export function capabilityAbsences(session) {
     if (false === session.captureBodies) {
         absences.push({
             capability: 'network-bodies',
-            meaning: 'request and response bodies are not recorded, so an assertion that reads one cannot be ' +
-                'answered here and will be refused before it spends an action',
-            remedy: "pass captureBodies: true to connect() in this app's Reticle setup, then reload the page. " +
+            meaning: 'request bodies and successful response bodies are not recorded (a failed response keeps ' +
+                'its body by default), so an assertion that reads one cannot be answered here and will be ' +
+                'refused before it spends an action',
+            remedy: "pass captureNetworkBodies: true to connect() in this app's Reticle setup, then reload the page. " +
                 'Bodies can carry personal data, so this is off unless a project asks for it.',
         });
     }

package/dist/surface/tools/harness-gate.d.ts

@@ -35,8 +35,8 @@ export declare class HarnessNotLinkedError extends DriveRefusedError {
         who: "human";
         run: string;
     } | {
-        tool: string;
         who: "agent";
+        tool: string;
     })[];
     constructor();
 }

package/dist/surface/tools/harness-toolset.js

@@ -8,7 +8,6 @@
  * agent can reach.
  */
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
 import { AppRuntime, ConsequenceKind, NetInitiator, PredicateKind, ReticleTool, } from '@reticlehq/core';
 import { TOOLS } from './tools.js';
 import { runTool } from './invoke-tool.js';
@@ -98,8 +97,8 @@ const INJECTED_PARAMS = new Set(['sessionId']);
  * wedge, it would manufacture one.
  */
 const TOOL_TIMEOUT_MS = 300_000;
-/** What the MCP SDK passes its own converter, restated so the two surfaces cannot drift apart. */
-const MCP_SCHEMA_OPTIONS = { strictUnions: true, pipeStrategy: 'input' };
+/** What the MCP SDK passes zod's own converter, restated so the two surfaces cannot drift apart. */
+const MCP_SCHEMA_OPTIONS = { target: 'draft-7', io: 'input' };
 /** Convert one tool's zod shape into the JSON Schema the model wire wants. */
 function toHarnessTool(tool) {
     const asked = Object.fromEntries(Object.entries(tool.inputSchema).filter(([name]) => !INJECTED_PARAMS.has(name)));
@@ -115,7 +114,7 @@ function toHarnessTool(tool) {
          * argument that decides whether a drive proves anything. Definitions and refs are what every
          * agent driving Reticle over MCP already reads.
          */
-        inputSchema: zodToJsonSchema(z.object(asked), MCP_SCHEMA_OPTIONS),
+        inputSchema: z.toJSONSchema(z.object(asked), MCP_SCHEMA_OPTIONS),
     };
 }
 /**

package/dist/surface/tools/lease-permissions.d.ts

@@ -8,7 +8,7 @@
  */
 import { z } from 'zod';
 import type { BrowserPool } from '../../portal/pool/browser-pool.js';
-export declare const LEASE_PERMISSIONS_ARG: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+export declare const LEASE_PERMISSIONS_ARG: z.ZodOptional<z.ZodArray<z.ZodString>>;
 type PermissionPool = Pick<BrowserPool, 'notificationPermission'>;
 /** The validated list, undefined when the caller passed none, or a refusal naming the right shape. */
 export declare function parseLeasePermissions(raw: unknown): readonly string[] | undefined;

package/dist/surface/tools/lease-readiness.d.ts

@@ -1,7 +1,8 @@
 /**
  * Is a leased tab usable right now? The checks `reticle_lease` runs before it may say `ready: true`.
  * Presence in the sessions map is not enough: the tab has to answer, and it has to be visible.
- * The wait for the tab to connect is here too, with the zero-install reader for a page that stays silent.
+ * The wait for the tab to connect is here too, with the zero-install reader for a page that stays silent,
+ * and the move that takes a reused lease to the page it was asked for.
  */
 import { LeaseNotReadyReason } from '@reticlehq/core';
 /** The narrow slice of a session the probe needs. Anything that quacks like this works. */
@@ -16,6 +17,11 @@ interface ProbeableSession {
  * default `false`. The pool foregrounding the page is what covers the gap; this catches the rest.
  */
 export declare function tabHidden(session: unknown): boolean;
+/**
+ * Why a lease that connected is not ready: `failed` when it did not answer, `tab_hidden` when it
+ * answers from a hidden tab, nothing when it is ready.
+ */
+export declare function notReadyReason(answered: boolean, session: unknown, failed?: LeaseNotReadyReason): LeaseNotReadyReason | undefined;
 /**
  * Does this tab still answer?
  *
@@ -68,4 +74,20 @@ export interface LeaseReaderFailure {
     reason: LeaseNotReadyReason;
     cause: string;
 }
+/**
+ * Move a reused lease to the page it was asked for (#1667).
+ *
+ * Reuse hands back the tab wherever the last caller left it. Answering with the requested url
+ * while the tab stayed elsewhere sent the next read to another page. So the tab goes there, and
+ * the answer waits for its SDK to come back on that page, as a minted lease's does.
+ *
+ * `undefined` when there is nothing to move: the tab is already there, or its url is unknown.
+ * Otherwise `navigated` says whether the tab got there, `url` is the page it is on, and `arrived`
+ * whether its SDK connected there within the wait.
+ */
+export declare function moveReusedLease(tabUrl: () => string | undefined, requested: string, goto: () => Promise<boolean>, now: () => number): Promise<{
+    navigated: boolean;
+    url: string;
+    arrived: boolean;
+} | undefined>;
 export {};

package/dist/surface/tools/lease-readiness.js

@@ -1,9 +1,10 @@
 /**
  * Is a leased tab usable right now? The checks `reticle_lease` runs before it may say `ready: true`.
  * Presence in the sessions map is not enough: the tab has to answer, and it has to be visible.
- * The wait for the tab to connect is here too, with the zero-install reader for a page that stays silent.
+ * The wait for the tab to connect is here too, with the zero-install reader for a page that stays silent,
+ * and the move that takes a reused lease to the page it was asked for.
  */
-import { LeaseNotReadyReason, ReticleCommand } from '@reticlehq/core';
+import { LeaseNotReadyReason, ReticleCommand, RETICLE_URL_PARAM } from '@reticlehq/core';
 import { NotHtmlDocumentError } from '../../portal/pool/zero-install.js';
 /**
  * How long a liveness probe waits for the tab to say anything at all.
@@ -25,6 +26,16 @@ export function tabHidden(session) {
         'object' === typeof session &&
         true === session.info?.().hidden);
 }
+/**
+ * Why a lease that connected is not ready: `failed` when it did not answer, `tab_hidden` when it
+ * answers from a hidden tab, nothing when it is ready.
+ */
+export function notReadyReason(answered, session, failed = LeaseNotReadyReason.SDK_STOPPED_ANSWERING) {
+    if (!answered) {
+        return failed;
+    }
+    return tabHidden(session) ? LeaseNotReadyReason.TAB_HIDDEN : undefined;
+}
 /**
  * Does this tab still answer?
  *
@@ -47,8 +58,9 @@ export function tabHidden(session) {
  */
 export async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_MS) {
     const send = session?.command;
-    if (send === undefined)
+    if (send === undefined) {
         return true;
+    }
     try {
         await send.call(session, ReticleCommand.CAPABILITIES, {}, timeoutMs);
         return true;
@@ -70,8 +82,9 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  */
 export async function waitForLeasedSession(isConnected, sleeper = sleep, attempts = LEASE_READY_ATTEMPTS, pollMs = LEASE_READY_POLL_MS) {
     for (let i = 0; i < attempts; i++) {
-        if (isConnected())
+        if (isConnected()) {
             return true;
+        }
         await sleeper(pollMs);
     }
     return isConnected();
@@ -86,8 +99,9 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
  * that stayed silent through the whole readiness wait is the one that gets a reader.
  */
 export async function connectOrInject(lease, isConnected, wait = waitForLeasedSession, graceRounds = LEASE_LOADING_GRACE_ROUNDS) {
-    if (await wait(isConnected))
+    if (await wait(isConnected)) {
         return { ready: true, zeroInstall: false };
+    }
     let injected;
     try {
         injected = true === (await lease.injectReader?.());
@@ -97,20 +111,24 @@ export async function connectOrInject(lease, isConnected, wait = waitForLeasedSe
         await lease.release?.().catch(() => undefined);
         return { ready: false, zeroInstall: false, readerFailure: readerFailureOf(err) };
     }
-    if (injected && (await wait(isConnected)))
+    if (injected && (await wait(isConnected))) {
         return { ready: true, zeroInstall: true };
+    }
     // A slow first dev compile can hold the document past both waits, and its app connects a moment
     // later (#1555). Keep waiting while the page itself says it is still loading, bounded so a page
     // that never finishes cannot hold the acquire forever.
     for (let round = 0; round < graceRounds; round++) {
-        if (!(await pageStillLoading(lease)))
+        if (!(await pageStillLoading(lease))) {
             break;
-        if (await wait(isConnected))
+        }
+        if (await wait(isConnected)) {
             return { ready: true, zeroInstall: injected };
+        }
     }
     // Re-check right before answering: a connect that landed during the last loading probe counts.
-    if (isConnected())
+    if (isConnected()) {
         return { ready: true, zeroInstall: injected };
+    }
     return (await pageStillLoading(lease))
         ? { ready: false, zeroInstall: false, stillLoading: true }
         : { ready: false, zeroInstall: false };
@@ -137,3 +155,51 @@ function readerFailureOf(err) {
         cause,
     };
 }
+/** How long a moved lease's SDK gets to come back on the new page: the mint path's wait. */
+const REUSED_ARRIVAL_MS = LEASE_READY_ATTEMPTS * LEASE_READY_POLL_MS;
+/** A URL as a page: without Reticle's own params or the fragment. Undefined when it is not a URL. */
+function pageOf(url) {
+    if (url === undefined) {
+        return undefined;
+    }
+    try {
+        const u = new URL(url);
+        for (const param of Object.values(RETICLE_URL_PARAM)) {
+            u.searchParams.delete(param);
+        }
+        u.hash = '';
+        return u.href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Move a reused lease to the page it was asked for (#1667).
+ *
+ * Reuse hands back the tab wherever the last caller left it. Answering with the requested url
+ * while the tab stayed elsewhere sent the next read to another page. So the tab goes there, and
+ * the answer waits for its SDK to come back on that page, as a minted lease's does.
+ *
+ * `undefined` when there is nothing to move: the tab is already there, or its url is unknown.
+ * Otherwise `navigated` says whether the tab got there, `url` is the page it is on, and `arrived`
+ * whether its SDK connected there within the wait.
+ */
+export async function moveReusedLease(tabUrl, requested, goto, now) {
+    const from = tabUrl();
+    const target = pageOf(requested);
+    if (pageOf(from) === undefined || target === undefined || pageOf(from) === target) {
+        return undefined;
+    }
+    const went = await Promise.resolve()
+        .then(goto)
+        .catch(() => false);
+    if (!went) {
+        return { navigated: false, url: from ?? requested, arrived: true };
+    }
+    const start = now();
+    while (pageOf(tabUrl()) !== target && now() - start < REUSED_ARRIVAL_MS) {
+        await sleep(LEASE_READY_POLL_MS);
+    }
+    return { navigated: true, url: requested, arrived: pageOf(tabUrl()) === target };
+}

package/dist/surface/tools/lease-tools.d.ts

@@ -9,14 +9,11 @@
  *
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
-import type { RealInputProvider } from '../../portal/input/real-input.js';
-import { type StorageFixturePort } from '../../portal/input/storage-fixture.js';
-import { type NetworkMutationPort } from '../../portal/input/network-mutation.js';
-import type { Perturbation } from '@reticlehq/core';
 import { type SeedStorage } from '@reticlehq/core';
 import { HudVisibility } from '@reticlehq/core';
 import { type ToolDef, type ToolDeps } from './tool-kit.js';
 import { type BrowserPool } from '../../portal/pool/browser-pool.js';
+export { sessionMutationPort, sessionPerturbationPort, suiteFixturePort, suiteFixtureSeed, } from './session-ports.js';
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
@@ -101,51 +98,3 @@ export declare const LEASE_ACQUIRE_TOOL: ToolDef;
  */
 export declare function releaseLease(deps: ToolDeps, pool: BrowserPool, sessionId: string): Promise<number>;
 export declare const LEASE_TOOLS: ToolDef[];
-/**
- * The state a suite should boot its flows from: whatever the agent is already sitting in.
- *
- * This is the join the fixture work was building toward. A suite's flows each start from cold, so
- * fifty of them prove the login works fifty times — and the flow that LOGS OUT leaves every flow
- * after it signed out, which no navigation repairs, because the problem is not where the subject is
- * but what it holds. A seed is applied to an isolated context BEFORE the first navigation, which is
- * exactly and only when a fixture can work.
- *
- * Best-effort, deliberately. A fixture is an OPTIMISATION over running from cold, and running from
- * cold is correct: a suite that refused to start because a cookie jar could not be read would have
- * traded a slow answer for no answer. Every "no" here — no provider, no storage support, nothing
- * driven, a browser that threw, nothing worth seeding — produces the same honest `undefined`, and
- * the suite runs exactly as it did before any of this existed.
- */
-export declare function suiteFixtureSeed(realInput: RealInputProvider | undefined, appUrl: string): Promise<SeedStorage | undefined>;
-/**
- * A way to make this session's page SLOW on purpose, or nothing.
- *
- * The third of these seams, for the same reason as the other two: a feature reaching into the input
- * layer directly is a feature depending on a driver, and the boundary guard asks about it.
- *
- * Installs delays and NOTHING else. A rule that carried a status or a body would substitute a
- * response the server never sent, and an app raced against invented data produces invented races —
- * a fabricated defect handed to somebody at 3am, which is worse than finding nothing.
- */
-export declare function sessionPerturbationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<{
-    slow(rules: readonly Perturbation[]): Promise<void>;
-    clear(): Promise<void>;
-} | undefined>;
-/**
- * Save/restore for this session's page, or nothing.
- *
- * The same job as `suiteFixtureSeed` next door, stopping one step earlier: that one captures and
- * converts, this hands back the PORT so a caller can re-apply what it captured later. It lives here
- * for the reason written above — a feature reaching into the input layer directly is a feature
- * depending on a driver, and the boundary guard asks about it. It asked.
- */
-export declare function suiteFixturePort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<StorageFixturePort | undefined>;
-/**
- * A way to break this session's page, or nothing.
- *
- * Sits beside `suiteFixtureSeed` because it is the same shape of job: turning a provider capability
- * into something a feature can use, on the one side of the graph that is allowed to know about both.
- * A flow tool reaching into the input layer directly would be a feature depending on a driver, which
- * is the reach the boundary guard exists to ask about.
- */
-export declare function sessionMutationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<NetworkMutationPort | undefined>;