@reticlehq/server 3.8.0 → 3.8.1

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

@@ -10,11 +10,9 @@
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
 import * as production from '../../portal/production/production-activation.js';
-import { fixturePortFor, seedFromStorageState, } from '../../portal/input/storage-fixture.js';
-import { mutationPortFor } from '../../portal/input/network-mutation.js';
 import { z } from 'zod';
 import { leaseNotConnectedHint, leaseReaderFailedHint, leaseStillLoadingHint, } from './lease-hint.js';
-import { connectOrInject, probeLeaseAlive, tabHidden } from './lease-readiness.js';
+import { connectOrInject, moveReusedLease, notReadyReason, probeLeaseAlive, } from './lease-readiness.js';
 import { probeSdkMarker } from './gaps/sdk-marker-probe.js';
 import { observeWebDocument } from '../../portal/session/dev-server/served-document.js';
 import { diagnoseObservedWebCsp } from '@reticlehq/init';
@@ -31,6 +29,7 @@ import { asString } from '@reticlehq/core';
 import { chromiumPreflightRefusal } from '../../command/cli/doctor/browser/chromium-hint.js';
 import { LEASE_PERMISSIONS_ARG, hintOf, notificationReadBack, parseLeasePermissions, permissionRefusal, refuseRegrant, } from './lease-permissions.js';
 import { LEASE_EMULATE_ARG, leaseEmulationOf } from '../../portal/input/viewport-tools.js';
+export { sessionMutationPort, sessionPerturbationPort, suiteFixturePort, suiteFixtureSeed, } from './session-ports.js';
 /**
  * Everything the daemon already knows about why a leased tab might not have dialled in.
  *
@@ -54,11 +53,13 @@ import { LEASE_EMULATE_ARG, leaseEmulationOf } from '../../portal/input/viewport
  */
 async function observedCspBlock(url, port) {
     const document = await observeWebDocument(url);
-    if (document === undefined)
+    if (document === undefined) {
         return undefined;
+    }
     const refusesSocket = diagnoseObservedWebCsp(document, port).some((finding) => `${finding.problem} ${finding.fix}`.includes(CONNECT_SRC));
-    if (!refusesSocket)
+    if (!refusesSocket) {
         return undefined;
+    }
     const allow = `ws://localhost:${String(port)} ws://127.0.0.1:${String(port)}`;
     return {
         problem: `its ${CONNECT_SRC} does not allow ws://localhost:${String(port)}`,
@@ -102,8 +103,9 @@ export function appendReticleParams(url, session, projectId, hud) {
         if (projectId !== undefined && projectId.length > 0) {
             u.searchParams.set(RETICLE_URL_PARAM.PROJECT, projectId);
         }
-        if (hud !== undefined)
+        if (hud !== undefined) {
             u.searchParams.set(RETICLE_URL_PARAM.HUD, hud);
+        }
         return u.toString();
     }
     catch {
@@ -137,8 +139,9 @@ function newLeaseId() {
  * so `lease-abc` cannot claim `lease-abcdef`.
  */
 export function resolveLeasedSessionId(sessions, leaseId) {
-    if (sessions.get(leaseId) !== undefined)
+    if (sessions.get(leaseId) !== undefined) {
         return leaseId;
+    }
     return sessions.all().find((s) => sessionParamOf(s.url) === leaseId)?.id;
 }
 /**
@@ -156,17 +159,20 @@ export function resolveLeasedSessionId(sessions, leaseId) {
  */
 export function carryReticleIdentity(fromUrl, toUrl) {
     const session = sessionParamOf(fromUrl);
-    if (session === undefined)
+    if (session === undefined) {
         return toUrl;
+    }
     // Already addressed (a caller passing the stamped URL back) — appending would be a no-op at best.
-    if (sessionParamOf(toUrl) !== undefined)
+    if (sessionParamOf(toUrl) !== undefined) {
         return toUrl;
+    }
     const projectId = projectParamOf(fromUrl);
     return appendReticleParams(toUrl, session, projectId);
 }
 function projectParamOf(url) {
-    if (url === undefined)
+    if (url === undefined) {
         return undefined;
+    }
     try {
         return new URL(url).searchParams.get(RETICLE_URL_PARAM.PROJECT) ?? undefined;
     }
@@ -175,8 +181,9 @@ function projectParamOf(url) {
     }
 }
 function sessionParamOf(url) {
-    if (url === undefined)
+    if (url === undefined) {
         return undefined;
+    }
     try {
         return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
     }
@@ -209,8 +216,9 @@ export async function acquireLeasedSession(pool, sessions, url, projectId, seedS
         registeredId = resolveLeasedSessionId(sessions, lease.sessionId);
         return registeredId !== undefined;
     });
-    if (registeredId !== undefined)
+    if (registeredId !== undefined) {
         pool.alias?.(registeredId, lease.sessionId);
+    }
     const effectiveId = registeredId ?? lease.sessionId;
     if (seedStorage !== undefined) {
         const session = sessions.get(effectiveId);
@@ -244,7 +252,8 @@ export const LEASE_ACQUIRE_TOOL = {
     inputSchema: {
         url: z
             .string()
-            .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard).'),
+            .optional()
+            .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard). Omit it to lease the one dev server that runs in this project folder.'),
         projectId: z
             .string()
             .optional()
@@ -311,6 +320,10 @@ export const LEASE_ACQUIRE_TOOL = {
             .boolean()
             .optional()
             .describe('True when this acquire returned an existing live lease on the same origin rather than minting a second context.'),
+        navigated: z
+            .boolean()
+            .optional()
+            .describe('Present when a reused lease was on another page. True: its tab was moved to url. False: it could not be moved, and url is the page it is on.'),
         hint: z.string().optional(),
         production: production.PRODUCTION_LEASE_OUTPUT,
         versionSkew: z
@@ -322,11 +335,14 @@ export const LEASE_ACQUIRE_TOOL = {
     },
     handler: async (deps, args) => {
         const pool = deps.pool;
-        if (pool === undefined)
+        if (pool === undefined) {
             throw new Error(POOL_UNAVAILABLE);
-        const url = asString(args['url']);
-        if (url === undefined || 0 === url.length)
-            throw new Error('reticle_lease{action:"acquire"} requires a url');
+        }
+        const given = asString(args['url']);
+        const url = given === undefined || 0 === given.length ? await deps.projectAppUrl?.() : given;
+        if (url === undefined) {
+            throw new Error('reticle_lease{action:"acquire"} requires a url: no single dev server runs in this project folder. Start the app, or pass the url it serves.');
+        }
         // Preflight the browser before spending the round trip. Without it a missing Playwright Chromium
         // only surfaces inside pool.acquire, where the launch failure is caught and reported as
         // "could not open <url> — is the app running?" — sending the caller to debug an app that is
@@ -334,8 +350,9 @@ export const LEASE_ACQUIRE_TOOL = {
         // installed" so error-recovery routes it to the NO_POOL fix (install + drive a human tab).
         if (deps.browserProbe !== undefined) {
             const refusal = chromiumPreflightRefusal(await deps.browserProbe());
-            if (refusal !== undefined)
+            if (refusal !== undefined) {
                 throw new Error(refusal);
+            }
         }
         const projectId = asString(args['projectId']);
         const root = asString(args['root']);
@@ -438,16 +455,16 @@ export const LEASE_ACQUIRE_TOOL = {
                     // old, or there may be none at all — `unresponsive` is set by past commands failing, and
                     // its own contract says absence means "answering, OR NOT ASKED YET". So the happy path of
                     // a first acquire pays nothing for this.
+                    const tabUrl = () => deps.sessions.get(resolved)?.url;
+                    const moved = await moveReusedLease(tabUrl, url, () => pool.gotoLease(existing, carryReticleIdentity(tabUrl(), url)), deps.now);
                     const reusedSession = deps.sessions.get(resolved);
-                    const alive = await probeLeaseAlive(reusedSession);
-                    const reuseReason = !alive
-                        ? LeaseNotReadyReason.SDK_STOPPED_ANSWERING
-                        : tabHidden(reusedSession)
-                            ? LeaseNotReadyReason.TAB_HIDDEN
-                            : undefined;
+                    const reuseReason = false === moved?.arrived
+                        ? LeaseNotReadyReason.SDK_NEVER_DIALLED
+                        : notReadyReason(await probeLeaseAlive(reusedSession), reusedSession);
                     return {
                         sessionId: resolved,
-                        url,
+                        url: moved?.url ?? url,
+                        ...(moved === undefined ? {} : { navigated: moved.navigated }),
                         ready: reuseReason === undefined,
                         ...(reuseReason === undefined ? {} : { notReadyReason: reuseReason }),
                         reused: true,
@@ -470,8 +487,9 @@ export const LEASE_ACQUIRE_TOOL = {
             }
             const sessionId = newLeaseId();
             // Before the page can dial in: the session is stamped with its root the moment it registers.
-            if (root !== undefined)
+            if (root !== undefined) {
                 claimArtifactRoot(sessionId, root);
+            }
             const navUrl = appendReticleParams(activated?.url ?? url, sessionId, projectId, hud);
             let lease;
             try {
@@ -490,11 +508,13 @@ export const LEASE_ACQUIRE_TOOL = {
                 });
             }
             catch (err) {
-                if (err instanceof PoolAtCapacityError)
+                if (err instanceof PoolAtCapacityError) {
                     throw err;
+                }
                 const refusal = permissionRefusal(err);
-                if (refusal !== undefined)
+                if (refusal !== undefined) {
                     throw refusal;
+                }
                 if (err instanceof Error && err.message.startsWith('Storage seeding failed')) {
                     throw new Error(scrubSeedFromError(err.message, validatedSeed));
                 }
@@ -516,8 +536,9 @@ export const LEASE_ACQUIRE_TOOL = {
             // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
             // without this the touches miss, the lease ages out despite continuous activity, and the
             // reaper closes the context mid-flow. See BrowserPool.alias and #157.
-            if (registeredId !== undefined)
+            if (registeredId !== undefined) {
                 pool.alias(registeredId, lease.sessionId);
+            }
             const effectiveSessionId = registeredId ?? lease.sessionId;
             const session = deps.sessions.get(effectiveSessionId);
             if (validatedSeed !== undefined && session !== undefined) {
@@ -528,17 +549,29 @@ export const LEASE_ACQUIRE_TOOL = {
             }
             // The lease now exists, so any HUD a human is watching has just gone dark. Say so. A lease whose
             // reader failed is already released, so there is nothing to say.
-            if (readerFailure === undefined)
+            if (readerFailure === undefined) {
                 tellWatchers(deps, projectId, AGENT_DRIVING_ELSEWHERE);
+            }
             // ready means the SDK dialled in — not that contracts match. Carry the skew warning on acquire
             // so the agent does not learn it only after a CDP tool invents a closed page (#688).
             const mintReason = readerFailure?.reason ??
-                (!ready
-                    ? LeaseNotReadyReason.SDK_NEVER_DIALLED
-                    : tabHidden(session)
-                        ? LeaseNotReadyReason.TAB_HIDDEN
-                        : undefined);
+                notReadyReason(ready, session, LeaseNotReadyReason.SDK_NEVER_DIALLED);
             const versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
+            let notReadyHint;
+            if (!ready) {
+                if (readerFailure !== undefined) {
+                    notReadyHint = leaseReaderFailedHint(url, readerFailure);
+                }
+                else if (true === stillLoading) {
+                    notReadyHint = leaseStillLoadingHint(url, Date.now() - waitStartedAt);
+                }
+                else if (activated !== undefined) {
+                    notReadyHint = production.notActivatedHint(url);
+                }
+                else {
+                    notReadyHint = await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId));
+                }
+            }
             return {
                 sessionId: registeredId ?? lease.sessionId,
                 url,
@@ -563,15 +596,7 @@ export const LEASE_ACQUIRE_TOOL = {
                 ...(versionSkew === undefined ? {} : { versionSkew }),
                 ...production.summary(activated),
                 ...(initScript === undefined ? {} : { hostStub: HOST_STUB_NOTE }),
-                ...hintOf(ready
-                    ? undefined
-                    : readerFailure !== undefined
-                        ? leaseReaderFailedHint(url, readerFailure)
-                        : true === stillLoading
-                            ? leaseStillLoadingHint(url, Date.now() - waitStartedAt)
-                            : activated !== undefined
-                                ? production.notActivatedHint(url)
-                                : await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId)), ready ? await notificationReadBack(pool, lease.sessionId, permissions) : undefined),
+                ...hintOf(notReadyHint, ready ? await notificationReadBack(pool, lease.sessionId, permissions) : undefined),
             };
         }
         finally {
@@ -605,8 +630,9 @@ const LEASE_RELEASE_TOOL = {
     },
     handler: async (deps, args) => {
         const pool = deps.pool;
-        if (pool === undefined)
+        if (pool === undefined) {
             throw new Error(POOL_UNAVAILABLE);
+        }
         const sessionId = asString(args['sessionId']);
         if (sessionId === undefined || 0 === sessionId.length) {
             throw new Error('reticle_lease{action:"release"} requires a sessionId');
@@ -635,8 +661,9 @@ export async function releaseLease(deps, pool, sessionId) {
     dropArtifactRootClaim(sessionId);
     // Only once the LAST lease is gone. Announcing "live again" while another lease still drives
     // would be a lie, and a HUD that says the wrong thing is worse than one that says nothing.
-    if (0 === pool.activeCount())
+    if (0 === pool.activeCount()) {
         tellWatchers(deps, projectId, AGENT_DRIVING_HERE_AGAIN);
+    }
     return pool.activeCount();
 }
 /**
@@ -664,11 +691,13 @@ const PREFER_EXISTING_NOTE = 'a non-leased tab for this app was already connecte
  */
 function liveTabFor(deps, projectId, url) {
     const pool = deps.pool;
-    if (pool === undefined)
+    if (pool === undefined) {
         return undefined;
+    }
     const wanted = originOf(url);
-    if (wanted === undefined)
+    if (wanted === undefined) {
         return undefined;
+    }
     try {
         const candidates = deps.sessions
             .all()
@@ -692,8 +721,9 @@ function liveTabFor(deps, projectId, url) {
  */
 function tellWatchers(deps, projectId, text) {
     const pool = deps.pool;
-    if (pool === undefined)
+    if (pool === undefined) {
         return;
+    }
     try {
         const candidates = deps.sessions
             .all()
@@ -707,96 +737,3 @@ function tellWatchers(deps, projectId, text) {
     }
 }
 export const LEASE_TOOLS = [LEASE_ACQUIRE_TOOL, LEASE_RELEASE_TOOL];
-/**
- * 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 async function suiteFixtureSeed(realInput, appUrl) {
-    if (realInput === undefined)
-        return undefined;
-    try {
-        const port = await fixturePortFor(realInput, appUrl);
-        if (port === undefined)
-            return undefined;
-        return seedFromStorageState(await port.capture(), appUrl);
-    }
-    catch {
-        return 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 async function sessionPerturbationPort(realInput, appUrl) {
-    if (realInput === undefined || appUrl === undefined)
-        return undefined;
-    const setMocks = realInput.setMocks?.bind(realInput);
-    if (setMocks === undefined)
-        return undefined;
-    if (!(await realInput.isAvailableFor(appUrl)))
-        return undefined;
-    return {
-        slow: async (rules) => {
-            await setMocks(appUrl, [...rules]);
-        },
-        /** Clearing is the undo. A page left slowed is damage the next run inherits. */
-        clear: async () => {
-            await setMocks(appUrl, []);
-        },
-    };
-}
-/**
- * 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 async function suiteFixturePort(realInput, appUrl) {
-    if (realInput === undefined || appUrl === undefined)
-        return undefined;
-    try {
-        return await fixturePortFor(realInput, appUrl);
-    }
-    catch {
-        return 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 async function sessionMutationPort(realInput, appUrl) {
-    if (realInput === undefined || appUrl === undefined)
-        return undefined;
-    try {
-        return await mutationPortFor(realInput, appUrl);
-    }
-    catch {
-        // A provider that cannot answer is the same answer as a provider that cannot break anything.
-        return undefined;
-    }
-}

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

@@ -705,7 +705,9 @@ export const OBSERVE_TOOLS = [
                 .optional()
                 .describe('Total matches before `limit` — present only when capped.'),
             droppedOldest: z.number().optional().describe('How many older matches `limit` dropped.'),
-            hint: z.object({ totalInWindow: z.number(), byLevel: z.record(z.number()) }).optional(),
+            hint: z
+                .object({ totalInWindow: z.number(), byLevel: z.record(z.string(), z.number()) })
+                .optional(),
             cost: z.object({ bytes: z.number(), tokens: z.number() }).optional(),
             ...bufferOutputShape,
         },

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

@@ -199,7 +199,7 @@ export const READ_TOOLS = [
         },
         outputSchema: {
             recordingName: z.string(),
-            program: z.unknown(),
+            program: z.unknown().optional(),
             warning: z.string().optional(),
             proposedConsequences: z
                 .array(z.unknown())
@@ -386,7 +386,7 @@ export const READ_TOOLS = [
             ...sessionIdShape,
         },
         outputSchema: {
-            stores: z.record(z.unknown()).optional(),
+            stores: z.record(z.string(), z.unknown()).optional(),
             storeNames: z.array(z.string()).optional(),
             found: z.boolean().optional(),
             value: z.unknown().optional(),
@@ -598,9 +598,9 @@ export const READ_TOOLS = [
             ...sessionIdShape,
         },
         outputSchema: {
-            local: z.record(z.string()).optional(),
-            session: z.record(z.string()).optional(),
-            cookies: z.record(z.string()).optional(),
+            local: z.record(z.string(), z.string()).optional(),
+            session: z.record(z.string(), z.string()).optional(),
+            cookies: z.record(z.string(), z.string()).optional(),
             area: z.string().optional(),
             key: z.string().optional(),
             value: z.string().optional(),

package/dist/surface/tools/session-ports.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Provider capabilities handed to features as ports: a suite fixture to seed from, save/restore,
+ * slowing the page and breaking it. Each is `undefined` when the provider cannot do it. They sit on
+ * the tool side because a feature reaching into the input layer directly would depend on a driver.
+ */
+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, SeedStorage } from '@reticlehq/core';
+/**
+ * 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>;

package/dist/surface/tools/session-ports.js

@@ -0,0 +1,102 @@
+import { fixturePortFor, seedFromStorageState, } from '../../portal/input/storage-fixture.js';
+import { mutationPortFor } from '../../portal/input/network-mutation.js';
+/**
+ * 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 async function suiteFixtureSeed(realInput, appUrl) {
+    if (realInput === undefined) {
+        return undefined;
+    }
+    try {
+        const port = await fixturePortFor(realInput, appUrl);
+        if (port === undefined) {
+            return undefined;
+        }
+        return seedFromStorageState(await port.capture(), appUrl);
+    }
+    catch {
+        return 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 async function sessionPerturbationPort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    const setMocks = realInput.setMocks?.bind(realInput);
+    if (setMocks === undefined) {
+        return undefined;
+    }
+    if (!(await realInput.isAvailableFor(appUrl))) {
+        return undefined;
+    }
+    return {
+        slow: async (rules) => {
+            await setMocks(appUrl, [...rules]);
+        },
+        /** Clearing is the undo. A page left slowed is damage the next run inherits. */
+        clear: async () => {
+            await setMocks(appUrl, []);
+        },
+    };
+}
+/**
+ * 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 async function suiteFixturePort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    try {
+        return await fixturePortFor(realInput, appUrl);
+    }
+    catch {
+        return 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 async function sessionMutationPort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    try {
+        return await mutationPortFor(realInput, appUrl);
+    }
+    catch {
+        // A provider that cannot answer is the same answer as a provider that cannot break anything.
+        return undefined;
+    }
+}

package/dist/surface/tools/tool-kit.d.ts

@@ -94,6 +94,8 @@ export interface ToolDeps<Ext = unknown> {
         url: string;
         notice: string;
     } | undefined>;
+    /** The one dev server running in the caller's project folder, for a lease that names no url. */
+    projectAppUrl?: () => Promise<string | undefined>;
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */
@@ -170,13 +172,13 @@ export interface ToolDeps<Ext = unknown> {
 export interface ToolDef<Ext = unknown> {
     name: string;
     description: string;
-    inputSchema: z.ZodRawShape;
+    inputSchema: Record<string, z.ZodType>;
     /**
      * JSON Schema-compatible output schema for this tool. When present, the MCP server advertises it
      * in the tools/list response so schema-aware clients (like @reticlehq/cli) can validate outputs and
      * compose tool calls safely. Also drives TOON encoding for snapshot/query results.
      */
-    outputSchema?: z.ZodRawShape;
+    outputSchema?: Record<string, z.ZodType>;
     /**
      * One concrete, valid call — the shape, not the prose.
      *
@@ -369,7 +371,7 @@ export declare const SCREENSHOT_DOC = " `screenshot.path` is a picture of the pa
  * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
  * whole release, and every key that went missing was a channel nobody could see was missing.
  */
-export declare const sessionEnvelopeShape: z.ZodRawShape;
+export declare const sessionEnvelopeShape: Record<string, z.ZodType>;
 /** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
 export declare function commandOrThrow(deps: ToolDeps, sessionId: string | undefined, name: ReticleCommand, args: Record<string, unknown>): Promise<unknown>;
 /** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */

package/dist/surface/tools/tools.js

@@ -324,7 +324,7 @@ export const RAW_TOOLS = withCompactEnvelope([
                 states: z.array(z.string()),
                 visible: z.boolean(),
                 attrs: z
-                    .record(z.string())
+                    .record(z.string(), z.string())
                     .optional()
                     .describe('Present only for attributes requested via `attrs` and found on the element.'),
                 source: z