@reticlehq/server 2.2.0 → 2.3.0

package/dist/telemetry/telemetry.js

@@ -0,0 +1,313 @@
+/**
+ * Anonymous adoption telemetry — the OSS runtime's ONLY phone-home for product metrics (DAU/WAU/MAU,
+ * invocations, sessions, installs, tool usage). It answers the "npm downloads don't count, show me
+ * platform usage" question without collecting anything personal:
+ *
+ *   - identity is a random UUID minted locally at `~/.reticle/telemetry-id` (never derived from you),
+ *   - the project is a one-way HASH of the cwd (counts DISTINCT projects, reveals none),
+ *   - it is strictly opt-OUT: `RETICLE_TELEMETRY=0` or the `DO_NOT_TRACK` convention disables it,
+ *   - it is best-effort and non-blocking: a send failure NEVER changes what the tool does.
+ *
+ * Events are `@reticlehq/core`'s `TelemetryEventSchema`, mapped at the wire into PostHog's capture
+ * format (https://posthog.com/docs/api/capture) — PostHog is the analytics backend until Reticle Cloud
+ * grows its own; a project API key is WRITE-ONLY by design, so embedding it in an OSS client is safe.
+ * Everything here is wrapped so a telemetry bug can never surface to a user — a broken metric must not
+ * break a verification.
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID, createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, } from '@reticlehq/core';
+import { SERVER_VERSION } from '../server-version.js';
+const RETICLE_DIR = join(homedir(), '.reticle');
+const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
+const NOTICE_FILE = join(RETICLE_DIR, 'telemetry-notice-shown');
+/** Presence of this file = a persistent, machine-wide opt-out (`reticle telemetry disable`). */
+const OPT_OUT_FILE = join(RETICLE_DIR, 'telemetry-opt-out');
+/** Where the full disclosure lives — printed in the first-run notice and `reticle telemetry status`. */
+const POLICY_URL = 'https://github.com/reticlehq/reticle/blob/main/docs/telemetry.md';
+/** PostHog batch-capture endpoint (US cloud). `RETICLE_TELEMETRY_URL` overrides the host (EU/self-host). */
+const DEFAULT_URL = 'https://us.i.posthog.com';
+const TELEMETRY_PATH = '/batch/';
+/**
+ * The write-only PostHog project key (safe to embed: it can only WRITE events, never read anything —
+ * PostHog's own docs ship it in client-side JS). `RETICLE_TELEMETRY_KEY` overrides it; empty disables.
+ */
+const POSTHOG_KEY = 'phc_q4yCxKMXHfWQ43VAz4HxJXZFLqFi4nBbg5v3avemggYo';
+/**
+ * Skip PostHog person-profile processing: our users are anonymous by construction (never $identify'd),
+ * so profiles buy nothing — and personless events are up to 4x cheaper while unique counts/retention
+ * still key on distinct_id.
+ */
+const POSTHOG_PERSONLESS = { $process_person_profile: false };
+const SEND_TIMEOUT_MS = 2000;
+/**
+ * The sender a `detach: true` emit runs in a disowned child (argv: [url, body]) — an in-process fetch
+ * keeps Node's event loop alive until the POST finishes, which taxed every short-lived CLI command
+ * (`reticle version`/`gate`) ~800ms. Long-lived daemon events still send in-process: a spawn per tool
+ * call would be far heavier than a fetch inside an already-running server.
+ */
+const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'content-type':'application/json'}," +
+    `body:process.argv[2],signal:AbortSignal.timeout(${SEND_TIMEOUT_MS})})` +
+    '.catch(()=>{}).finally(()=>process.exit(0))';
+/** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
+import { isReticleSourceCheckout } from './dev-repo.js';
+import { gitFacts } from './git-facts.js';
+const Env = {
+    DISABLE: 'RETICLE_TELEMETRY', // "0" / "false" / "off" → disabled
+    DO_NOT_TRACK: 'DO_NOT_TRACK', // the cross-tool opt-out convention (any truthy value)
+    URL: 'RETICLE_TELEMETRY_URL', // override the PostHog host (EU cloud / self-hosted)
+    KEY: 'RETICLE_TELEMETRY_KEY', // override the PostHog project key
+    CI: 'CI', // presence marks a CI environment
+    VITEST: 'VITEST', // set by vitest — unit tests must never phone home
+};
+const isDisabled = (env, cwd = process.cwd()) => {
+    const off = new Set(['0', 'false', 'off', 'no']);
+    if (off.has((env[Env.DISABLE] ?? '').toLowerCase()))
+        return true;
+    if (env[Env.VITEST] !== undefined)
+        return true; // a test run is not a user
+    // Developing Reticle is not using Reticle. The `.env` carrying RETICLE_TELEMETRY=0 is gitignored,
+    // so it only exists on the machine that made it — a fresh clone would phone home on a
+    // contributor's first `reticle serve`. The repo marker is committed, so this guarantee travels.
+    if (isReticleSourceCheckout(cwd))
+        return true;
+    const dnt = env[Env.DO_NOT_TRACK];
+    return typeof dnt === 'string' && dnt !== '' && dnt !== '0';
+};
+/** Read (or mint-and-persist) the anonymous machine id. `firstRun` is true the run that created it. */
+const resolveIdentity = () => {
+    try {
+        if (existsSync(ID_FILE)) {
+            const id = readFileSync(ID_FILE, 'utf8').trim();
+            if (id.length > 0)
+                return { anonymousId: id, firstRun: false };
+        }
+        const id = randomUUID();
+        mkdirSync(RETICLE_DIR, { recursive: true });
+        writeFileSync(ID_FILE, id, 'utf8');
+        return { anonymousId: id, firstRun: true };
+    }
+    catch {
+        // Can't persist (read-only home, sandbox): still report, just as a fresh ephemeral id each time.
+        return { anonymousId: randomUUID(), firstRun: false };
+    }
+};
+/**
+ * One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing.
+ *
+ * Prefers a hash of the git ORIGIN over a hash of the cwd. The contract in `@reticlehq/core` always
+ * said "one-way hash of the git remote (or cwd)", but the implementation only ever hashed the path —
+ * which meant the same repo cloned by four teammates, or checked out twice on one machine, counted as
+ * four separate projects. That inflates the project count and, worse, makes team adoption look like
+ * unrelated individuals. Hashing the origin dedupes a real project down to one id across every clone.
+ *
+ * Still one-way, still non-reversible, and still exactly what the published policy describes: the
+ * remote URL itself never leaves the machine, only its SHA-256. The URL is normalized first (scheme,
+ * credentials, `.git` suffix and case removed) so `git@github.com:acme/web.git` and
+ * `https://github.com/Acme/web` are recognized as the same project rather than two.
+ */
+const projectFingerprint = (cwd) => {
+    const { origin } = gitFacts(cwd);
+    return {
+        projectId: createHash('sha256')
+            .update(origin ?? cwd)
+            .digest('hex')
+            .slice(0, 32),
+        // Reported alongside so the analytics knows whether this id is comparable to another machine's.
+        source: origin !== undefined ? ProjectIdSource.GIT_ORIGIN : ProjectIdSource.CWD,
+    };
+};
+/** Print the opt-out notice exactly once per machine (honest disclosure, the OSS-trust bar). */
+const showNoticeOnce = () => {
+    try {
+        if (existsSync(NOTICE_FILE))
+            return;
+        mkdirSync(RETICLE_DIR, { recursive: true });
+        writeFileSync(NOTICE_FILE, '1', 'utf8');
+        process.stderr.write('reticle: anonymous usage telemetry helps improve reticle — no code, no PII, ' +
+            `and your app's data never leaves your machine (${POLICY_URL}). ` +
+            'Opt out any time: reticle telemetry disable\n');
+    }
+    catch {
+        /* notice is a courtesy; never fail on it */
+    }
+};
+/** The current telemetry state and which control set it — what `reticle telemetry status` prints. */
+export const describeTelemetry = (env = process.env, dir = RETICLE_DIR, cwd = process.cwd()) => {
+    // Report the reason that ACTUALLY applies. Saying "environment variable" when the real cause is
+    // the source-checkout guard would send a contributor hunting for a variable that is not set.
+    if (isReticleSourceCheckout(cwd)) {
+        return {
+            enabled: false,
+            reason: 'this is a Reticle source checkout — developing it is not using it',
+            policyUrl: POLICY_URL,
+        };
+    }
+    if (isDisabled(env, cwd)) {
+        return { enabled: false, reason: 'disabled by environment variable', policyUrl: POLICY_URL };
+    }
+    if (existsSync(join(dir, 'telemetry-opt-out'))) {
+        return {
+            enabled: false,
+            reason: 'disabled via `reticle telemetry disable`',
+            policyUrl: POLICY_URL,
+        };
+    }
+    return {
+        enabled: true,
+        reason: 'anonymous usage metrics only — no code, no PII',
+        policyUrl: POLICY_URL,
+    };
+};
+/** Persist (or lift) the machine-wide opt-out — `reticle telemetry disable` / `enable`. */
+export const setTelemetryEnabled = (enabled, dir = RETICLE_DIR) => {
+    const optOutFile = join(dir, 'telemetry-opt-out');
+    if (enabled) {
+        rmSync(optOutFile, { force: true });
+        return;
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(optOutFile, '1', 'utf8');
+};
+const NOOP = { emit: async () => { }, enabled: false, firstRun: false };
+/**
+ * Build the telemetry emitter for this process. Resolves identity + opt-out ONCE; each `emit` builds a
+ * fully-validated core event, maps it into PostHog capture shape, and fires a best-effort POST.
+ * `version` is the running reticle version (for the `version` dimension); `now`/`fetchImpl` are
+ * injected so this is testable without a clock or network.
+ */
+export const createTelemetry = (opts) => {
+    const env = opts.env ?? process.env;
+    const cwd = opts.cwd ?? process.cwd();
+    if (isDisabled(env, cwd))
+        return NOOP;
+    try {
+        if (existsSync(OPT_OUT_FILE))
+            return NOOP; // the persistent `reticle telemetry disable` opt-out
+    }
+    catch {
+        /* unreadable home dir — fall through; the env-var opt-outs above still apply */
+    }
+    const apiKey = env[Env.KEY] ?? POSTHOG_KEY;
+    if (apiKey === '')
+        return NOOP; // no key baked in (dev/test build) — nowhere to send, stay silent
+    const now = opts.now ?? (() => Date.now());
+    const doFetch = opts.fetchImpl ?? fetch;
+    const url = `${(env[Env.URL] ?? DEFAULT_URL).replace(/\/+$/, '')}${TELEMETRY_PATH}`;
+    const ci = env[Env.CI] !== undefined && env[Env.CI] !== '';
+    const os = platform();
+    const { anonymousId, firstRun } = resolveIdentity();
+    /**
+     * One id per PROCESS, minted in memory and never persisted — which is exactly right: a daemon run
+     * IS the session, and a restarted daemon is genuinely a new one. Ephemeral by construction, so it
+     * adds no durable identifier to the machine.
+     */
+    const sessionId = randomUUID();
+    const { projectId, source: projectIdSource } = projectFingerprint(opts.cwd ?? process.cwd());
+    showNoticeOnce();
+    const spawnDetached = opts.spawnImpl ??
+        ((command, args) => {
+            spawn(command, args, { detached: true, stdio: 'ignore' }).unref();
+        });
+    const emit = async (kind, extra) => {
+        const event = {
+            v: TELEMETRY_EVENT_VERSION,
+            anonymousId,
+            sessionId,
+            projectId,
+            event: kind,
+            ts: now(),
+            version: opts.version,
+            ci,
+            os,
+            projectIdSource,
+            ...(extra?.actor !== undefined ? { actor: extra.actor } : {}),
+            ...(extra?.command !== undefined ? { command: extra.command } : {}),
+            ...(extra?.flags !== undefined ? { flags: extra.flags } : {}),
+            ...(extra?.session !== undefined ? { session: extra.session } : {}),
+            ...(extra?.project !== undefined ? { project: extra.project } : {}),
+            ...(extra?.verification !== undefined ? { verification: extra.verification } : {}),
+            ...(extra?.versionChange !== undefined ? { versionChange: extra.versionChange } : {}),
+            ...(extra?.crash !== undefined ? { crash: extra.crash } : {}),
+            ...(extra?.feedback !== undefined ? { feedback: extra.feedback } : {}),
+            ...(extra?.identity !== undefined ? { identity: extra.identity } : {}),
+            ...(extra?.connection !== undefined ? { connection: extra.connection } : {}),
+            ...(extra?.init !== undefined ? { init: extra.init } : {}),
+            ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
+        };
+        // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
+        // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
+        // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
+        // would be invisible to the exact "which stacks report the most bugs" question this exists to
+        // answer. One prefix keeps them grouped in the UI without a nested path.
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, ...rest } = event;
+        // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
+        // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
+        const properties = {
+            ...rest,
+            sessionId: eventSessionId,
+            $session_id: eventSessionId,
+        };
+        // Each block is flattened under its own prefix rather than nested. PostHog filters, breakdowns and
+        // insight builders all operate on TOP-LEVEL properties, so a nested `project.stack` is invisible to
+        // the exact "which stacks retain best" question these exist to answer — you would have to drop to
+        // raw HogQL for every chart. One prefix per block keeps them grouped in the property list without
+        // paying that cost. The two genuine maps (`toolCounts`, `errorKinds`) stay objects: their keys are
+        // open-ended, so flattening them would mint an unbounded number of property names, which is the one
+        // thing that actually degrades a PostHog project.
+        const blocks = {
+            feedback,
+            session,
+            project,
+            verification,
+            version: versionChange,
+            crash,
+            identity,
+            connection,
+            init,
+            bug,
+        };
+        for (const [prefix, block] of Object.entries(blocks)) {
+            for (const [key, value] of Object.entries(block ?? {})) {
+                properties[`${prefix}_${key}`] = value;
+            }
+        }
+        const body = JSON.stringify({
+            api_key: apiKey,
+            batch: [
+                {
+                    event: name,
+                    distinct_id: distinctId,
+                    timestamp: new Date(ts).toISOString(),
+                    properties: { ...properties, ...POSTHOG_PERSONLESS },
+                },
+            ],
+        });
+        try {
+            if (extra?.detach === true && opts.fetchImpl === undefined) {
+                spawnDetached(process.execPath, ['-e', DETACHED_SEND_SCRIPT, url, body]);
+                return;
+            }
+            await doFetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body,
+                signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+            });
+        }
+        catch {
+            /* best-effort: a lost metric must never surface to the user */
+        }
+    };
+    return { emit, enabled: true, firstRun };
+};
+/**
+ * The process-wide emitter. One identity resolution + one opt-out check per process; both the CLI
+ * lifecycle (install/invoke/session) and the per-tool hook in `runTool` share it.
+ */
+let singleton;
+export const getTelemetry = () => (singleton ??= createTelemetry({ version: SERVER_VERSION }));
+export { TelemetryEventKind };

package/dist/token-auth.d.ts

@@ -21,4 +21,3 @@ export declare function isLoopbackHost(hostHeader: string | undefined): boolean;
  * non-loopback value fails, which is what kills a rebound `http://evil.com` page reading the plane.
  */
 export declare function isLocalWebOrigin(origin: string | undefined, referer: string | undefined): boolean;
-//# sourceMappingURL=token-auth.d.ts.map

package/dist/token-auth.js

@@ -68,4 +68,3 @@ export function isLocalWebOrigin(origin, referer) {
     }
     return true;
 }
-//# sourceMappingURL=token-auth.js.map

package/dist/tools/act-capsule.d.ts

@@ -0,0 +1,23 @@
+import type { ExpectedLink } from '../capsule/divergence.js';
+import type { DivergenceCapsule } from '../capsule/capsule.js';
+import type { ToolDeps } from './tool-kit.js';
+interface CapsuleSaveInputs {
+    deps: ToolDeps;
+    verdict: {
+        pass: boolean;
+        failureReason?: string;
+    };
+    capsule?: DivergenceCapsule | undefined;
+    links: readonly ExpectedLink[];
+    args: Record<string, unknown>;
+    actResult: {
+        result?: unknown;
+    };
+    actedSource?: {
+        file: string;
+        line: number;
+    };
+}
+/** Returns the capsule id when one was written, or undefined when there was nothing to save. */
+export declare function saveFailedAssertCapsule(inputs: CapsuleSaveInputs): Promise<string | undefined>;
+export {};

package/dist/tools/act-capsule.js

@@ -0,0 +1,47 @@
+/**
+ * Persist a failed assertion as a replayable fail-to-pass capsule.
+ *
+ * : a red assertion is the ONE moment the evidence explaining it is in hand. Persist it as a
+        // replayable fail-to-pass capsule so the bug survives the turn — and becomes a regression flow
+        // the moment it goes green. Best-effort: capturing evidence must never fail the run that found it.
+ *
+ * Split out of act-tools.ts when it crossed the 600-line cap. The seam is real: this is the only
+ * part of the act path that writes to disk, and it is best-effort by design — capturing evidence
+ * must never fail the run that found it.
+ */
+import { ActionType, AnchorKind } from '@reticlehq/core';
+import { CapsuleStore, capsuleId } from '../capsule/capsule-store.js';
+import { ReticleTool } from './tool-names.js';
+import { asRecord, asString } from './tools-helpers.js';
+/** Returns the capsule id when one was written, or undefined when there was nothing to save. */
+export async function saveFailedAssertCapsule(inputs) {
+    const { deps, verdict, capsule, links, args, actResult, actedSource } = inputs;
+    if (verdict.pass || capsule === undefined)
+        return undefined;
+    const id = capsuleId(deps.now(), asString(args['ref']) ?? 'assert');
+    const expectedText = links
+        .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
+        .join(' AND ');
+    const saved = await new CapsuleStore(deps.fs, deps.reticleRoot).save({
+        version: 1,
+        id,
+        createdAt: deps.now(),
+        origin: 'failed-assert',
+        expected: expectedText.length > 0 ? expectedText : 'declared consequence',
+        observed: capsule.firstDivergence?.observed ?? verdict.failureReason ?? 'not observed',
+        steps: [
+            {
+                tool: ReticleTool.ACT,
+                anchor: {
+                    kind: AnchorKind.TESTID,
+                    value: asString(asRecord(actResult.result)['testid']) ?? asString(args['ref']) ?? '',
+                    // Carried so the saved capsule — which outlives this turn and becomes a regression flow
+                    // when it goes green — still knows which file the failure came from.
+                    ...(actedSource === undefined ? {} : { source: actedSource }),
+                },
+                action: (asString(args['action']) ?? ActionType.CLICK),
+            },
+        ],
+    });
+    return saved ? id : undefined;
+}

package/dist/tools/act-danger.d.ts

@@ -0,0 +1,7 @@
+import { ActionType } from '@reticlehq/core';
+export declare function assertNotDestructive(action: ActionType, innerArgs: Record<string, unknown>, inspected: unknown): void;
+/**
+ * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
+ * source alone never says so.
+ */
+export declare function assertDragNotDestructive(innerArgs: Record<string, unknown>, from: unknown, to: unknown): void;

package/dist/tools/act-danger.js

@@ -0,0 +1,44 @@
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, isDangerousActionText } from '@reticlehq/core';
+import { asRecord, asString } from './tools-helpers.js';
+/**
+ * Refuse to drive a money-moving or destructive control by accident.
+ *
+ * A native click is indistinguishable from a user's, so an agent exploring an unfamiliar app can
+ * refund a payment or delete an account while "just looking". The guard reads every text surface the
+ * control exposes — its name, its text, its value, where it points, and the form it submits — because
+ * a button labelled only with an icon still says what it does through its `formAction`.
+ *
+ * Opt in per action with `args.confirmDangerous: true`. Deliberately a THROW rather than a warning:
+ * a caller that has not thought about it must not proceed by ignoring a field.
+ */
+function descriptorText(value) {
+    const descriptor = asRecord(value);
+    return [
+        asString(descriptor['name']) ?? '',
+        asString(descriptor['text']) ?? '',
+        asString(descriptor['value']) ?? '',
+        asString(descriptor['href']) ?? '',
+        asString(descriptor['formAction']) ?? '',
+        asString(descriptor['formText']) ?? '',
+    ].join(' ');
+}
+export function assertNotDestructive(action, innerArgs, inspected) {
+    if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
+        return;
+    if (innerArgs[DANGEROUS_ACTION_CONFIRM_ARG] === true)
+        return;
+    if (!isDangerousActionText(descriptorText(inspected)))
+        return;
+    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+}
+/**
+ * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
+ * source alone never says so.
+ */
+export function assertDragNotDestructive(innerArgs, from, to) {
+    if (innerArgs[DANGEROUS_ACTION_CONFIRM_ARG] === true)
+        return;
+    if (!isDangerousActionText(`${descriptorText(from)} ${descriptorText(to)}`))
+        return;
+    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+}

package/dist/tools/act-helpers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure coercion + grading helpers behind the act tools.
+ *
+ * Split out when act-tools.ts crossed the 600-line cap. The seam is that nothing here touches a
+ * session, a command, or a tool definition — these are total functions over their arguments, which
+ * is why they can be tested without a browser and why they were the right thing to move.
+ */
+import { ActionType } from '@reticlehq/core';
+import type { ElementBox } from '../input/real-input.js';
+import { HonestyGrade } from '../honesty/honesty.js';
+import type { ExpectedLink } from '../capsule/divergence.js';
+/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
+export declare function gradeOf(links: readonly ExpectedLink[]): HonestyGrade;
+/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
+export declare function asBox(value: unknown): ElementBox | undefined;
+/** Outcome of a real-input attempt — real success (result set) or synthetic with a reason. */
+export declare function asActionType(value: unknown): ActionType | undefined;

package/dist/tools/act-helpers.js

@@ -0,0 +1,40 @@
+/**
+ * Pure coercion + grading helpers behind the act tools.
+ *
+ * Split out when act-tools.ts crossed the 600-line cap. The seam is that nothing here touches a
+ * session, a command, or a tool definition — these are total functions over their arguments, which
+ * is why they can be tested without a browser and why they were the right thing to move.
+ */
+import { ActionType } from '@reticlehq/core';
+import { HonestyGrade } from '../honesty/honesty.js';
+import { asNumber, asRecord, asString } from './tools-helpers.js';
+/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
+export function gradeOf(links) {
+    if (links.some((l) => l.kind === 'signal'))
+        return HonestyGrade.SIGNAL;
+    if (links.some((l) => l.kind === 'net'))
+        return HonestyGrade.NET;
+    if (links.some((l) => l.kind === 'state'))
+        return HonestyGrade.STATE;
+    return HonestyGrade.PRESENCE;
+}
+/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
+export function asBox(value) {
+    const b = asRecord(asRecord(value)['box']);
+    const x = asNumber(b['x']);
+    const y = asNumber(b['y']);
+    const w = asNumber(b['width']);
+    const h = asNumber(b['height']);
+    if (x === undefined || y === undefined || w === undefined || h === undefined)
+        return undefined;
+    if (w <= 0 || h <= 0)
+        return undefined; // zero-area (display:none) ⇒ native click would miss
+    return { x, y, width: w, height: h };
+}
+/** Outcome of a real-input attempt — real success (result set) or synthetic with a reason. */
+export function asActionType(value) {
+    const raw = asString(value);
+    if (raw === undefined)
+        return undefined;
+    return Object.values(ActionType).includes(raw) ? raw : undefined;
+}

package/dist/tools/act-tools.d.ts

@@ -1,3 +1,10 @@
 import { type ToolDef } from './tool-kit.js';
+/**
+ * Narrow the wire's `action` to a real ActionType, or undefined.
+ *
+ * It used to be `asString(args['action']) ?? ''`, so an unknown or missing action became the empty
+ * string and travelled on — reaching the browser as a command it could not perform, and reported back
+ * as a generic failure rather than "that is not an action". Validate at the boundary, per the project's
+ * unknown-plus-narrowing rule, so a typo is rejected where it can still be explained.
+ */
 export declare const ACT_TOOLS: ToolDef[];
-//# sourceMappingURL=act-tools.d.ts.map