@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/chat-drives.js

@@ -0,0 +1,409 @@
+/**
+ * The daemon's side of the platform chat: the apps it reports, and the drives it takes.
+ *
+ * Out of `index.ts`, which only calls this and hands it the cloud credentials (the tool surface does
+ * not reach `memory/cloud`; see `withLinkedCredential`): both halves share the same view of which tab is which
+ * app, and keeping them together is what stops a drive attached to one app landing in another that
+ * happens to be on the same port. See `local-apps.ts` and `remote-drive.ts` for each half.
+ */
+import { isUnmatchedRoot } from '../../memory/project/dir/reticle-dir.js';
+import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+import { basename, dirname, join } from 'node:path';
+import { homedir, hostname } from 'node:os';
+import { LinkCapability, ReticleDir, ReticleTool, asRecord, } from '@reticlehq/core';
+import { prepareDrive } from '../../features/harness/platform/drive-target.js';
+import { reticleToolset } from './harness-toolset.js';
+import { projectDirFor, sessionRoot } from '../../memory/project/session-root.js';
+import { readDashboardUrl } from '../../memory/project/sync-status.js';
+import { driveFrame } from '../../features/visual/visual-tools.js';
+import { LEASE_ACQUIRE_TOOL } from './lease-tools.js';
+import { REMOTE_DRIVE_JPEG_QUALITY, endDrivenTab, pickOwnDriveSession, startRemoteDrives, } from '../../features/harness/platform/remote-drive.js';
+import { appKeyOf, appsByPlatform, homeRelative, machineOf, mayOpen, NOT_AN_APP_ADDRESS, nameFromProjectId, pickAppTab, startAppReports, withoutMarks, } from '../../features/harness/platform/local-apps.js';
+import { serverOptionsFromEnv } from '../../features/harness/platform/server-driver.js';
+import { EXPLORE_TOOLS, driveForChat } from './explore-tools.js';
+import { MSG_NO_HARNESS_KEY, harnessLockRefusal, withLinkedCredential } from './harness-explore.js';
+import { runTool } from './invoke-tool.js';
+import { announcedChannels, probeMarkers, notApplicableOf, recordedGaps, } from '../../portal/session/recorded-gaps.js';
+import { probeDevServers } from '../../portal/session/dev-server/dev-server-probe.js';
+import { DriveOrigin, onDriveChange, onDriveStep, runningDrive, stopDrive, } from '../../features/harness/drive-runs.js';
+import { FreeDriveKind, planUrl, requestFreeDrive, } from '../../features/harness/platform/platform-drives.js';
+import { HumanControlKind } from '@reticlehq/core';
+import { onAgentsChange } from '../../hooks/coding-agents.js';
+/** Why a platform drive with no tab of its own runs no tool. */
+const NO_DRIVEN_TAB = 'No tab was picked for this drive, so no tool runs.';
+/** What this daemon does for the platform's chat. Each one is listed only once it is built. */
+export const CHAT_CAPABILITIES = [
+    LinkCapability.DRIVE_SPEC,
+    LinkCapability.TARGET_TAB,
+    LinkCapability.TARGET_HEADLESS,
+    LinkCapability.TARGET_HEADED,
+    LinkCapability.HUD,
+    LinkCapability.TOOL_SESSION,
+    LinkCapability.FRAMES,
+];
+/** A project's own name: its package's, else its id's, else its folder's. */
+const nameOf = async (fs, dir, projectId) => {
+    try {
+        const name = JSON.parse(await fs.readFile(join(dir, 'package.json')))
+            .name;
+        if ('string' === typeof name && 0 < name.length)
+            return name;
+    }
+    catch {
+        // No package, or not JSON: the folder names it.
+    }
+    // Not mapped to a checkout (the daemon's shared `unmatched` directory): the id the SDK stamped.
+    if (undefined !== projectId)
+        return nameFromProjectId(projectId);
+    return basename(dir) || dir;
+};
+/** How often the localhost dev-server scan may run: never more than this, however often we report. */
+const DEV_SERVER_SCAN_EVERY_MS = 30_000;
+/**
+ * Dev servers listening on localhost with no connected Reticle page — an app that is up and not
+ * instrumented, or not dialling. The same probe `doctor` and the no-session diagnosis use, cached.
+ */
+function devServerScan(connectedUrls, now) {
+    let last;
+    return async () => {
+        if (last === undefined || now() - last.at >= DEV_SERVER_SCAN_EVERY_MS)
+            last = { at: now(), ports: await probeDevServers() };
+        const connected = new Set(connectedUrls().map((url) => {
+            try {
+                return Number(new URL(url).port);
+            }
+            catch {
+                return 0;
+            }
+        }));
+        return last.ports
+            .filter((port) => !connected.has(port))
+            .map((port) => ({ url: `http://${LOCALHOST_HOST}:${String(port)}`, port }));
+    };
+}
+const LOCALHOST_HOST = 'localhost';
+export function startChatDrives(deps, sessions, fs, cloud, log) {
+    const env = process.env;
+    const machine = machineOf(hostname(), homedir());
+    const sessionCloud = cloud.sessionCloud;
+    const sessionKey = async (id) => (await sessionCloud(id))?.apiKey;
+    // ponytail: a tab whose project resolves to nothing counts as the daemon's own project here, as it
+    // does for flows and runs; a per-tab "unresolved" app is the upgrade if that ever misleads.
+    const appOf = (id) => {
+        try {
+            const projectId = sessions.list().find((tab) => tab.sessionId === id)?.projectId;
+            return appKeyOf(machine.id, projectDirFor(deps, id), projectId);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // Opened headless, like `reticle drive <url>`, through runTool so it is counted like any call.
+    const openable = (url) => {
+        if (!mayOpen(url, sessions.list().map((tab) => tab.url)))
+            throw new Error(NOT_AN_APP_ADDRESS);
+    };
+    /**
+     * The `.reticle` each reported app writes into, learned from its tabs. A tab the chat opens for an
+     * app is leased into that root: resolved from the page alone, an app with no project id would land
+     * in `unmatched/`, which nothing syncs.
+     */
+    const rootByApp = new Map();
+    /**
+     * The root AND the project a tab the daemon opens for an app is stamped with. Stamped with the
+     * root alone, a page that reports no project of its own opened as nobody's: its run fell to
+     * `unmatched/` and the drive answered a linked project "run reticle connect".
+     */
+    const claimFor = (appKey) => (appKey === undefined ? undefined : rootByApp.get(appKey)) ?? {};
+    /** Where each credential's project was last open on this machine, from the reports. */
+    const lastUrlByKey = new Map();
+    /** Lease the app a credential's project was last open at, for a drive no tab of it can take. */
+    const reopenFor = async (key) => {
+        const last = lastUrlByKey.get(key);
+        if (last === undefined)
+            return undefined;
+        openable(last.url);
+        const id = asRecord(await runTool(LEASE_ACQUIRE_TOOL, deps, { ...last }))['sessionId'];
+        return 'string' === typeof id ? id : undefined;
+    };
+    const open = async (url, appKey) => {
+        openable(url);
+        await runTool(LEASE_ACQUIRE_TOOL, deps, { url, ...claimFor(appKey) });
+    };
+    const pick = (goal, key, app) => undefined === app
+        ? pickOwnDriveSession(sessions.list(), goal, key, sessionKey, () => reopenFor(key))
+        : pickAppTab(app, goal, () => sessions.list(), appOf, (url) => open(url, app.key)).then(async (id) => 
+        // The app the platform named must be one this credential's project owns.
+        'string' === typeof id && (await sessionKey(id)) !== key ? null : id);
+    const drives = startRemoteDrives({
+        env: () => withLinkedCredential(deps, env),
+        connected: () => 0 < sessions.count(),
+        pick,
+        // The spec's target and HUD, applied through the same counted tools an agent would call.
+        prepare: ({ goal, apiKey, app, spec }) => prepareDrive(spec, app?.url ?? undefined, {
+            pickTab: () => pick(goal, apiKey, app),
+            open: async (url, headed, hud) => {
+                openable(url);
+                const lease = asRecord(await runTool(LEASE_ACQUIRE_TOOL, deps, {
+                    url,
+                    ...(headed ? { headed } : {}),
+                    ...(hud === undefined ? {} : { hud }),
+                    ...claimFor(app?.key),
+                }));
+                const id = lease['sessionId'];
+                if ('string' !== typeof id)
+                    throw new Error(`could not open ${url}`);
+                return id;
+            },
+            tuneHud: async (sessionId, hud) => {
+                await reticleToolset(deps, { sessionId }).invoke(ReticleTool.SESSION_TUNE, { hud });
+            },
+            sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        }),
+        // A platform drive: Reticle's own tools on the driven tab, and nothing else. Locked, so a call
+        // naming another tab still lands on this one; with no tab picked, nothing runs at all.
+        session: (sessionId) => {
+            if (sessionId === undefined)
+                return { invoke: () => Promise.reject(new Error(NO_DRIVEN_TAB)) };
+            const tools = reticleToolset(deps, { sessionId, locked: true });
+            return { tools: tools.tools, invoke: (tool, args) => tools.invoke(tool, args) };
+        },
+        drive: async (goal, sessionId, spec) => {
+            const url = sessions.list().find((tab) => tab.sessionId === sessionId)?.url;
+            const outcome = await driveForChat(deps, goal, sessionId, spec?.plan, spec?.confirmDangerous);
+            return url === undefined ? outcome : { ...outcome, url };
+        },
+        // The leased tab, or a desktop window's own capture. A web tab only the SDK reaches has no camera.
+        frame: (sessionId) => sessionId === undefined
+            ? Promise.resolve(undefined)
+            : driveFrame(deps, sessionId, REMOTE_DRIVE_JPEG_QUALITY),
+        settle: (id, outcome) => endDrivenTab(id === undefined ? undefined : sessions.get(id), outcome),
+        log,
+    });
+    const scanDevServers = devServerScan(() => sessions.list().map((tab) => tab.url), () => Date.now());
+    const reports = startAppReports({
+        machine,
+        version: cloud.version,
+        capabilities: CHAT_CAPABILITIES,
+        apps: async () => {
+            // The setup score the dashboard shows is what the app's pages carry, asked of each page
+            // until its app has shown both markers: never only what an act happened to reach.
+            await probeMarkers(sessions.list().flatMap((tab) => {
+                const live = sessions.get(tab.sessionId);
+                const command = live?.command?.bind(live);
+                return command === undefined
+                    ? []
+                    : [{ id: tab.sessionId, url: tab.url, projectId: tab.projectId, command }];
+            }));
+            return appsByPlatform(sessions.list().map((tab) => {
+                const live = sessions.get(tab.sessionId);
+                const sdkVersion = live?.sdkVersion;
+                // What the page announced plus the gaps its verdicts paid for: what the dashboard's
+                // coverage line and coding-agent prompt are built from.
+                const channels = announcedChannels({
+                    id: tab.sessionId,
+                    url: tab.url,
+                    projectId: tab.projectId,
+                    channels: live?.channels,
+                    sourceMapping: live?.sourceMapping,
+                });
+                const gaps = recordedGaps(tab.sessionId).map(({ kind, missing, fix, seenAt }) => ({
+                    kind,
+                    missing,
+                    fix,
+                    seenAt,
+                }));
+                return {
+                    ...tab,
+                    ...(sdkVersion === undefined ? {} : { sdkVersion }),
+                    ...(0 === channels.length ? {} : { channels }),
+                    gaps,
+                    notApplicable: notApplicableOf({
+                        id: tab.sessionId,
+                        url: tab.url,
+                        projectId: tab.projectId,
+                    }),
+                };
+            }), serverOptionsFromEnv(await withLinkedCredential(deps, env)), machine.id, async (tab) => {
+                const root = sessionRoot(deps, tab.sessionId);
+                const dir = dirname(root);
+                const projectId = tab.projectId ?? readProjectId(dir);
+                const stamp = { root, ...(projectId === undefined ? {} : { projectId }) };
+                rootByApp.set(appKeyOf(machine.id, dir, tab.projectId), stamp);
+                const platform = await sessionCloud(tab.sessionId);
+                if (undefined !== platform)
+                    lastUrlByKey.set(platform.apiKey, { url: withoutMarks(tab.url), ...stamp });
+                return {
+                    dir,
+                    name: await nameOf(fs, dir, tab.projectId),
+                    ...(undefined === platform
+                        ? {}
+                        : { platform: { url: platform.url.replace(/\/+$/, ''), apiKey: platform.apiKey } }),
+                };
+            });
+        },
+        open,
+        extras: async () => {
+            const closure = sessions.lastClosure?.();
+            const unsynced = cloud.unsynced?.();
+            return {
+                devServers: await scanDevServers(),
+                ...(closure === undefined
+                    ? {}
+                    : { helloFailure: { reason: closure.reason, at: closure.at } }),
+                ...unsyncedReport(unsynced, homedir()),
+            };
+        },
+        drivePending: (platform) => void drives.tick(platform),
+        // What the platform wants the person told: in the daemon's log, and on the HUD of each open tab
+        // of that project, so somebody who never reads the log still sees "update Reticle".
+        notify: (notice, platform) => {
+            const line = `${notice.text}${notice.url === undefined ? '' : ` ${notice.url}`}`;
+            log(`reticle: from the platform: ${line}`);
+            void (async () => {
+                for (const tab of sessions.list()) {
+                    const key = await sessionKey(tab.sessionId).catch(() => undefined);
+                    if (key === platform.apiKey)
+                        sessions.get(tab.sessionId)?.pushNarration(line);
+                }
+            })();
+        },
+        log,
+    });
+    // Once now, so the chat sees this machine's apps as soon as the daemon is up.
+    void reports.tick();
+    return {
+        stop: () => {
+            drives.stop();
+            reports.stop();
+        },
+    };
+}
+/** The dashboard the tab's project is linked to, when its link names one. */
+function dashboardOf(deps, sessionId) {
+    try {
+        return readDashboardUrl(sessionRoot(deps, sessionId));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Said on the HUD when Link this project ends. */
+const MSG_LINKED = 'Linked. This project now reports to your dashboard.';
+const MSG_LINK_FAILED = 'Could not link this project. Run `reticle connect` in its folder.';
+/** A page with no projectId: linking it would bind a hash-named project nothing here reads. */
+const MSG_LINK_NEEDS_PROJECT = 'This page did not say which project it is, so there is nothing to link yet. Run `npx @reticlehq/server init` in your app (or pass `projectId` to `connect()`), then Link.';
+const MSG_LINK_UNAVAILABLE = 'This Reticle cannot link from the panel. Run `reticle connect` in the project folder.';
+/** Said on the HUD when Stop finds nothing to stop. */
+const MSG_NOTHING_DRIVING = 'No Harness drive is running in this tab.';
+const msgStartTrial = (url) => `Start your trial: ${url}`;
+/**
+ * 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 async function hudDrive(deps, sessionId, 
+/** The panel's control, as the bridge narrowed it (`harness-request.ts`). */
+request, 
+/** The autonomous switch: written through to the platform, which the daemon owns. */
+applySwitch, grant = (platform) => requestFreeDrive(platform, FreeDriveKind.EXPLORE)) {
+    if (HumanControlKind.HARNESS === request.kind)
+        return applySwitch(request.enabled);
+    // What the panel's Run and Stop answer belongs in the Harness log, and in the Agent Log as a summary.
+    const say = (text) => deps.sessions.get?.(sessionId)?.pushNarration(text, true, { harness: true, summary: true });
+    if (HumanControlKind.HARNESS_STOP === request.kind) {
+        const running = runningDrive(sessionId);
+        if (running === undefined || !stopDrive(running.harnessRun))
+            say(MSG_NOTHING_DRIVING);
+        return;
+    }
+    // Before the grant: a drive the gate refuses must not take one. The panel shows the prompt.
+    const env = await withLinkedCredential(deps, process.env, { sessionId });
+    const locked = await harnessLockRefusal(deps, sessionId, env);
+    if (locked !== undefined)
+        return say(locked.split('\n')[0] ?? locked);
+    const platform = serverOptionsFromEnv(env);
+    if (platform === undefined)
+        return say(MSG_NO_HARNESS_KEY);
+    const granted = await grant(platform);
+    if (!granted.granted) {
+        say(granted.message);
+        // At the console's origin (the tab's link names it), never the API's, which 404s when split.
+        if (granted.needsCard)
+            say(msgStartTrial(planUrl(dashboardOf(deps, sessionId) ?? platform.url)));
+        return;
+    }
+    const explore = EXPLORE_TOOLS.find((tool) => ReticleTool.VERIFY_EXPLORE === tool.name);
+    if (explore === undefined)
+        return;
+    try {
+        await runTool(explore, deps, {
+            sessionId,
+            driveId: granted.driveId,
+            origin: DriveOrigin.HUD,
+            wait: 0,
+            ...(request.persona === undefined ? {} : { persona: request.persona }),
+        });
+    }
+    catch (error) {
+        say(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * 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 function projectLinkOnly(link) {
+    return link === undefined
+        ? undefined
+        : (root) => (isUnmatchedRoot(root) ? Promise.resolve(0) : link(root));
+}
+/**
+ * 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 function attachHudHarness(bridge, daemon, applySwitch, 
+/** Link this project: what `reticle connect` does from that folder. Absent: the button says so. */
+link) {
+    bridge.attachHarnessRequest((request, s) => {
+        const root = s.artifactRoot ?? daemon.root;
+        if (HumanControlKind.HARNESS_LINK === request.kind) {
+            const say = (text) => daemon.deps().sessions.get?.(s.id)?.pushNarration(text);
+            if (link === undefined)
+                return say(MSG_LINK_UNAVAILABLE);
+            if (isUnmatchedRoot(root))
+                return say(MSG_LINK_NEEDS_PROJECT);
+            void link(root)
+                .then((code) => say(0 === code ? MSG_LINKED : MSG_LINK_FAILED))
+                .catch(() => say(MSG_LINK_FAILED))
+                .finally(daemon.repaint);
+            return;
+        }
+        void hudDrive(daemon.deps(), s.id, request, (on) => applySwitch(root, on));
+    });
+    onDriveChange(daemon.repaint);
+    // Each step too, so the panel's "N steps so far" counts up instead of sitting at zero.
+    onDriveStep(daemon.repaint);
+    // And "Connected: Claude Code" follows an agent attaching or leaving.
+    onAgentsChange(daemon.repaint);
+}
+/**
+ * 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 function unsyncedReport(unsynced, home) {
+    if (unsynced === undefined)
+        return {};
+    return {
+        // A folder no project claimed cannot be connected, so no board should tell anyone to.
+        unsynced: unsynced
+            .filter((u) => !isUnmatchedRoot(u.root))
+            .map((u) => ({
+            ...u,
+            // The project, not its `.reticle`: the dashboard tells the person to run a command there.
+            root: homeRelative(ReticleDir.ROOT === basename(u.root) ? dirname(u.root) : u.root, home),
+        })),
+    };
+}

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

@@ -5,14 +5,6 @@ interface Control {
 }
 /** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
 export declare function parseControls(tree: string): Control[];
-/**
- * Build the coverage tool over the dispatchable tool table.
- *
- * The table arrives as a thunk rather than an import: `tools.ts` assembles it FROM this module, so
- * importing it back would close a cycle whose failure mode is a load-order-dependent crash rather
- * than an error anyone sees while writing it. The thunk is called inside the handler, long after the
- * table exists. It carries the merged names — the ones `reticle_run` will actually accept — because
- * a tool that merged into a parent is not something an agent can call or a maintainer can cut.
- */
-export declare function buildCoverageTools(toolNames: () => readonly string[]): ToolDef[];
+/** Build the coverage tool. */
+export declare function buildCoverageTools(): ToolDef[];
 export {};

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

@@ -2,9 +2,6 @@ import { z } from 'zod';
 import { sessionRoot } from '../../memory/project/session-root.js';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { coverageRegressed, observabilityOf } from '@reticlehq/engine/evidence/observability.js';
-import { foldFeatureCapture } from './feature-capture.js';
-import { foldToolHitRate } from './tool-hit-rate.js';
-import { allSessionIntents } from '../../memory/intent/open-intents.js';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asString } from '@reticlehq/core';
@@ -55,16 +52,8 @@ export function parseControls(tree) {
     }
     return controls;
 }
-/**
- * Build the coverage tool over the dispatchable tool table.
- *
- * The table arrives as a thunk rather than an import: `tools.ts` assembles it FROM this module, so
- * importing it back would close a cycle whose failure mode is a load-order-dependent crash rather
- * than an error anyone sees while writing it. The thunk is called inside the handler, long after the
- * table exists. It carries the merged names — the ones `reticle_run` will actually accept — because
- * a tool that merged into a parent is not something an agent can call or a maintainer can cut.
- */
-export function buildCoverageTools(toolNames) {
+/** Build the coverage tool. */
+export function buildCoverageTools() {
     return [
         {
             name: ReticleTool.COVERAGE,
@@ -100,25 +89,6 @@ export function buildCoverageTools(toolNames) {
                     .object({ driven: z.number(), observable: z.number(), percent: z.number().optional() })
                     .optional()
                     .describe('Of the controls you DROVE, how many Reticle could fully observe. `untouched` above is work left for you; this is work left in the APP, and driving more controls does not move it. `percent` is OMITTED when nothing was driven, because 0/0 is not 100%.'),
-                featureUse: z
-                    .object({
-                    observed: z.boolean(),
-                    truncated: z.boolean().optional(),
-                    context: z.unknown().optional(),
-                    intents: z.unknown().optional(),
-                    missed: z.unknown().optional(),
-                })
-                    .optional()
-                    .describe('Whether this session used `reticle_context` and `reticle_intent` at all, and what it cost when it did not: `context` counts the calls and what followed each one, `intents` the ledger, `missed` the verdicts drawn against an empty ledger and the reads that re-fetched a fact already established. `observed:false` means nothing was recorded for this session — NOT that nothing was used. An instrument for deciding whether those two features earn their place; nothing here is a fault of yours.'),
-                toolHitRate: z
-                    .object({
-                    observed: z.boolean(),
-                    cells: z.unknown().optional(),
-                    called: z.unknown().optional(),
-                    neverCalled: z.unknown().optional(),
-                })
-                    .optional()
-                    .describe('Which Reticle tools THIS session called, and how reachable each one was: `called` lists every tool with its call count, `neverCalled` the rest of the table, and both carry a `tier` — `default` (advertised to every agent), `extended` (advertised only on the full surface) or `run-only` (reachable solely by naming it to reticle_run). `cells` counts each tier on both sides. `observed:false` means nothing was recorded for this session, NOT that nothing was called. THREE LIMITS, all load-bearing: this is ONE session, so it is evidence about this run and is not a hit rate — a hit rate is a distribution over many sessions. A never-called tool is not a useless tool; one used once a month in an emergency looks identical here to one nobody has ever called, so frequency alone cannot decide a cut. And the counts describe how this run went, never how it should have gone — nothing here is a fault of yours.'),
                 observabilityRegressed: z
                     .object({ was: z.number(), now: z.number() })
                     .optional()
@@ -143,25 +113,6 @@ export function buildCoverageTools(toolNames) {
                 // first without the second is how an agent finishes a pass believing it verified something the
                 // app was never able to confirm.
                 const gaps = session.gaps?.open() ?? [];
-                // Folded here rather than given a tool of its own: this is already the "am I done, and what is
-                // this verdict worth" read, and a number nobody has a reason to ask for separately is one
-                // nobody ever sees. It is a fold over the journal and the intent ledger plus the one thing
-                // neither records — see surface/tools/feature-capture.ts.
-                const featureUse = foldFeatureCapture({
-                    calls: session.capture.calls(),
-                    dropped: session.capture.dropped,
-                    actions: await session.readJournalActions(),
-                    intents: await allSessionIntents(deps, sessionId),
-                    finalActions: session.actionCount,
-                });
-                // Same fold, same reason, one level out: which of the whole tool table this session reached
-                // for, crossed with how reachable each name was. See surface/tools/tool-hit-rate.ts for what it can
-                // and cannot establish — the limits matter more than usual, because this is the number a
-                // decision to DELETE tools would be made on.
-                const toolHitRate = foldToolHitRate({
-                    calls: session.capture?.toolCalls(),
-                    allTools: toolNames(),
-                });
                 // The number, and the floor under it, together. A coverage figure that can only ever be
                 // reported and never contradicted is one an agent learns to satisfy rather than to earn.
                 const observability = observabilityOf(session.actedRefs(), gaps);
@@ -179,8 +130,6 @@ export function buildCoverageTools(toolNames) {
                     ...(gaps.length > 0 ? { instrumentationGaps: gaps, unproven: true } : {}),
                     observability,
                     ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
-                    featureUse,
-                    toolHitRate,
                     ...(true === args['app']
                         ? {
                             app: await foldAppCoverage({

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

@@ -8,13 +8,41 @@ import { ReticleTool } from '@reticlehq/core';
 import { ADVERTISE_ALL_ENV } from './tool-surface.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { isPredicateParam, predicateGrammar, } from '@reticlehq/engine/question/predicate/predicate-eval.js';
+/**
+ * A numeric parameter's enforced bounds, read off the schema that enforces them (#1537).
+ *
+ * The descriptions name a default and rarely a ceiling, so `timeout_ms: 60000` on act_and_wait was
+ * refused and the agent learned the 55000 cap from the error. Read here rather than written into
+ * prose, so the number shown is the number checked and cannot drift from it.
+ */
+function boundsOf(schema) {
+    let inner = schema;
+    for (;;) {
+        if (inner instanceof z.ZodOptional || inner instanceof z.ZodNullable) {
+            inner = inner.unwrap();
+        }
+        else if (inner instanceof z.ZodDefault) {
+            inner = inner.removeDefault();
+        }
+        else if (inner instanceof z.ZodEffects) {
+            inner = inner.innerType();
+        }
+        else
+            break;
+    }
+    if (!(inner instanceof z.ZodNumber))
+        return {};
+    const { minValue: min, maxValue: max } = inner;
+    return { ...(null === min ? {} : { min }), ...(null === max ? {} : { max }) };
+}
 /** Compact param list from a tool's zod shape — name/required/description (the description already
- * carries the type and any enum hints, so no JSON-Schema machinery is needed). */
+ * carries the type and any enum hints, so no JSON-Schema machinery is needed), plus numeric bounds. */
 function paramInfo(shape) {
     return Object.entries(shape).map(([name, schema]) => ({
         name,
         required: !schema.isOptional(),
         description: schema.description ?? '',
+        ...boundsOf(schema),
     }));
 }
 /**

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

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import type { ToolDeps } from './tool-kit.js';
+/** The fields only an empty list carries, declared so a schema-aware client does not strip them. */
+export declare const EMPTY_SESSION_LIST_OUTPUT: {
+    why: z.ZodOptional<z.ZodString>;
+    next_action: z.ZodOptional<z.ZodObject<{
+        action: z.ZodNativeEnum<{
+            readonly START_DEV_SERVER: "start_dev_server";
+            readonly RUN_INIT: "run_init";
+            readonly OPEN_APP: "open_app";
+            readonly REOPEN_APP: "reopen_app";
+            readonly DAEMON_SPLIT: "daemon_split";
+        }>;
+        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;
+    }>>;
+    talk_to_us: z.ZodOptional<z.ZodString>;
+    wired: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    lastKnown: z.ZodOptional<z.ZodObject<{
+        sessionId: z.ZodString;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        url: string;
+    }, {
+        sessionId: string;
+        url: string;
+    }>>;
+};
+/**
+ * Wire the calling project when another project's tab is the one currently connected.
+ *
+ * The list handler only used to reach {@link emptySessionList} when the daemon's whole list was
+ * empty. A live tab in project A then answered project B's first call with A's sessions, and B
+ * was never wired.
+ */
+export declare function wireCallerBesideLiveSessions(deps: ToolDeps, sessions: readonly {
+    projectId?: string;
+}[]): Promise<unknown>;
+export declare function emptySessionList(deps: ToolDeps, sessions: unknown[]): Promise<Record<string, unknown>>;