@reticlehq/server 2.14.0 → 3.2.0

package/dist/features/license/license.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Enterprise license-key verification + the assertEnterprise gate. ENTERPRISE CODE (Reticle Enterprise
+ * License — see./LICENSE), not the FSL that covers the rest of the server.
+ *
+ * Offline + no phone-home (preserves the no-telemetry brand): a key is a signed payload Reticle issues
+ * with its private key; this verifies it against the issuer's PUBLIC key with Ed25519. Dev/eval is a
+ * no-op (requireLicense:false) so the gate never gets in a contributor's way; only a production-mode
+ * caller with requireLicense:true must present a valid, unexpired key. The clock is injected (rule 7).
+ *
+ * Rules for this directory: the free server must never import from ee/; ee/ depends only on protocol +
+ * node + zod. This file imports neither server core nor any sibling outside ee/.
+ */
+import { type KeyObject } from 'node:crypto';
+import { z } from 'zod';
+import { LicenseActivation } from '@reticlehq/core/telemetry';
+/** Outcome of verifying a license key. */
+export declare const LicenseStatus: {
+    readonly VALID: "valid";
+    readonly MISSING: "missing";
+    readonly MALFORMED: "malformed";
+    readonly BAD_SIGNATURE: "bad-signature";
+    readonly EXPIRED: "expired";
+};
+export type LicenseStatus = (typeof LicenseStatus)[keyof typeof LicenseStatus];
+/**
+ * The signed claims inside a key. `exp` is epoch ms; `features` (optional) scopes which ee features
+ * unlock.
+ *
+ * `lid` is the stable licence id and the only safe identity: `org` is a display name a human typed at
+ * signing time, so two organisations with the same name collapse into one and a rename splits one into
+ * two. Every key carries one, minted by the issuer (`scripts/issue-license.mjs`), and it is required
+ * rather than optional because an optional id goes missing on exactly the keys that later need
+ * identifying.
+ */
+declare const LicensePayloadSchema: z.ZodObject<{
+    lid: z.ZodString;
+    org: z.ZodString;
+    plan: z.ZodString;
+    exp: z.ZodNumber;
+    features: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    lid: string;
+    org: string;
+    plan: string;
+    exp: number;
+    features?: string[] | undefined;
+}, {
+    lid: string;
+    org: string;
+    plan: string;
+    exp: number;
+    features?: string[] | undefined;
+}>;
+export type LicensePayload = z.infer<typeof LicensePayloadSchema>;
+type LicenseCheck = {
+    status: typeof LicenseStatus.VALID;
+    payload: LicensePayload;
+}
+/**
+ * EXPIRED carries the payload; the other failures cannot. The line is the SIGNATURE, not the
+ * clock: an expired key was genuinely issued by us and its claims are exactly as trustworthy as
+ * they were yesterday, so the licence id is safe to use. A malformed or wrongly-signed key has no
+ * verified claims at all, and naming a customer from one would mean trusting whatever was pasted.
+ */
+ | {
+    status: typeof LicenseStatus.EXPIRED;
+    payload: LicensePayload;
+} | {
+    status: Exclude<LicenseStatus, typeof LicenseStatus.VALID | typeof LicenseStatus.EXPIRED>;
+};
+/** Sign a payload into a license key — the ISSUER side (Reticle's private key). Exposed for the issuer tool + tests. */
+export declare function signLicenseKey(payload: LicensePayload, privateKey: KeyObject): string;
+/** Verify a key against the issuer public key. Never throws — returns a structured status. */
+export declare function verifyLicenseKey(key: string | undefined, publicKey: KeyObject, now: number): LicenseCheck;
+/**
+ * Where to get a key. A named constant because it appears in the gate's error AND in what
+ * `reticle license` prints, and a contact address that drifts between the two is a support request
+ * that reaches nobody.
+ */
+export declare const LICENSE_CONTACT = "hey@reticle.sh";
+/**
+ * The features a licence gates in THIS build. The single source: `assertEnterprise` callers name a
+ * member rather than a string literal, and `reticle license` reports the list, so what the CLI claims
+ * is gated is derived from what is actually gated rather than a second list somebody maintains.
+ *
+ * It is deliberately short. Reticle's roadmap for enterprise is longer (SSO, SCIM, RBAC, multi-org,
+ * policy gates), and none of it is here yet — printing a roadmap as though it were shipped is how a
+ * buyer discovers on day two that the thing they paid for does not exist. What is listed is what the
+ * running build will actually refuse without a key.
+ */
+export declare const EnterpriseFeature: {
+    /** Recording an audit event. */
+    readonly AUDIT_LOG: "audit-log";
+};
+export type EnterpriseFeature = (typeof EnterpriseFeature)[keyof typeof EnterpriseFeature];
+/** Thrown when a production-mode enterprise feature is used without a valid license. */
+export declare class EnterpriseLicenseError extends Error {
+    readonly feature: string;
+    readonly reason: string;
+    constructor(feature: string, reason: string);
+}
+/** Context for the gate. requireLicense:false ⇒ dev/eval no-op. publicKey injectable for tests. */
+export interface GateContext {
+    requireLicense: boolean;
+    now: () => number;
+    key?: string;
+    publicKey?: KeyObject;
+}
+/**
+ * Gate an enterprise feature. No-op in dev/eval (requireLicense:false). In production it throws
+ * EnterpriseLicenseError unless a valid, unexpired key that covers `feature` is present.
+ */
+export declare function assertEnterprise(feature: string, ctx: GateContext, env?: NodeJS.ProcessEnv, baked?: string): void;
+/** Env names that carry the activation: the operator's key, and the issuer public key baked at release. */
+export declare const LICENSE_KEY_ENV = "RETICLE_LICENSE_KEY";
+export declare const LICENSE_PUBLIC_KEY_ENV = "RETICLE_LICENSE_PUBLIC_KEY";
+/** The human-facing state of enterprise activation on this machine (what `reticle license status` shows). */
+interface LicenseReport {
+    /**
+     * Typed against core's closed list rather than re-listing the strings here: this status is reported
+     * on every telemetry event, so a member added in one place and not the other is a silently
+     * miscounted column (telemetry contract, rule 4).
+     */
+    status: LicenseActivation;
+    /** The stable license id — what usage is attributed to. Present only when `status` is `active`. */
+    licenseId?: string;
+    /**
+     * What a licence unlocks in this build, reported alongside where to get one — being told to set a
+     * variable with no idea what it unlocks is a dead end at the moment somebody is asking. Omitted
+     * once a licence is `active`, where the reader already has it.
+     */
+    gated?: readonly string[];
+    contact: string;
+    /**
+     * The key is valid, and scoped to features this build does not gate, so it unlocks nothing here.
+     * Present only when true: a `false` on every healthy licence is noise on the common case.
+     */
+    coversNothingHere?: boolean;
+    org?: string;
+    plan?: string;
+    expiresAt?: number;
+    features?: string[];
+    detail: string;
+}
+/**
+ * Resolve activation entirely from the environment — the install mechanism: the release bakes the
+ * issuer public key, the operator sets RETICLE_LICENSE_KEY. No public key configured ⇒ evaluation mode
+ * (enterprise features run free, dev/test only). Offline, no phone-home.
+ */
+export declare function describeLicense(now: number, env?: NodeJS.ProcessEnv, baked?: string): LicenseReport;
+/**
+ * Gate an enterprise feature using env-resolved activation. Enforcement is ON when the issuer public key
+ * is configured (a real release). Without it, behaviour splits on runtime:
+ *  - dev/eval (NODE_ENV ≠ production): features run FREE — never blocks a contributor or CI.
+ *  - production (NODE_ENV = production): FAIL CLOSED — a release that reaches production with no
+ *    resolvable issuer key was mis-built (the baked key wasn't stamped in, BAKED_ISSUER_PUBLIC_KEY_PEM
+ *    is still ''), and silently unlocking every ee feature with no key and no warning is the worst
+ *    outcome. Deny instead, with a distinct reason so the misconfiguration is obvious.
+ */
+export declare function assertEnterpriseFromEnv(feature: string, now: number, env?: NodeJS.ProcessEnv, baked?: string): void;
+export {};

package/dist/features/license/license.js

@@ -0,0 +1,287 @@
+/**
+ * Enterprise license-key verification + the assertEnterprise gate. ENTERPRISE CODE (Reticle Enterprise
+ * License — see./LICENSE), not the FSL that covers the rest of the server.
+ *
+ * Offline + no phone-home (preserves the no-telemetry brand): a key is a signed payload Reticle issues
+ * with its private key; this verifies it against the issuer's PUBLIC key with Ed25519. Dev/eval is a
+ * no-op (requireLicense:false) so the gate never gets in a contributor's way; only a production-mode
+ * caller with requireLicense:true must present a valid, unexpired key. The clock is injected (rule 7).
+ *
+ * Rules for this directory: the free server must never import from ee/; ee/ depends only on protocol +
+ * node + zod. This file imports neither server core nor any sibling outside ee/.
+ */
+import { createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto';
+import { z } from 'zod';
+import { LicenseActivation } from '@reticlehq/core/telemetry';
+/** Outcome of verifying a license key. */
+export const LicenseStatus = {
+    VALID: 'valid',
+    MISSING: 'missing',
+    MALFORMED: 'malformed',
+    BAD_SIGNATURE: 'bad-signature',
+    EXPIRED: 'expired',
+};
+/**
+ * The signed claims inside a key. `exp` is epoch ms; `features` (optional) scopes which ee features
+ * unlock.
+ *
+ * `lid` is the stable licence id and the only safe identity: `org` is a display name a human typed at
+ * signing time, so two organisations with the same name collapse into one and a rename splits one into
+ * two. Every key carries one, minted by the issuer (`scripts/issue-license.mjs`), and it is required
+ * rather than optional because an optional id goes missing on exactly the keys that later need
+ * identifying.
+ */
+const LicensePayloadSchema = z.object({
+    lid: z.string().min(1),
+    org: z.string(),
+    plan: z.string(),
+    exp: z.number(),
+    features: z.array(z.string()).optional(),
+});
+/** A key is `base64url(payloadJson).base64url(ed25519Signature)`. */
+const KEY_SEP = '.';
+/** Sign a payload into a license key — the ISSUER side (Reticle's private key). Exposed for the issuer tool + tests. */
+export function signLicenseKey(payload, privateKey) {
+    const json = JSON.stringify(payload);
+    const sig = edSign(null, Buffer.from(json, 'utf8'), privateKey);
+    return `${Buffer.from(json, 'utf8').toString('base64url')}${KEY_SEP}${sig.toString('base64url')}`;
+}
+/** Verify a key against the issuer public key. Never throws — returns a structured status. */
+export function verifyLicenseKey(key, publicKey, now) {
+    if (key === undefined || 0 === key.length)
+        return { status: LicenseStatus.MISSING };
+    const parts = key.split(KEY_SEP);
+    if (parts.length !== 2 ||
+        parts[0] === undefined ||
+        parts[1] === undefined ||
+        0 === parts[0].length) {
+        return { status: LicenseStatus.MALFORMED };
+    }
+    let json;
+    let payload;
+    try {
+        json = Buffer.from(parts[0], 'base64url').toString('utf8');
+        const parsed = LicensePayloadSchema.safeParse(JSON.parse(json));
+        if (!parsed.success)
+            return { status: LicenseStatus.MALFORMED };
+        payload = parsed.data;
+    }
+    catch {
+        return { status: LicenseStatus.MALFORMED };
+    }
+    let signatureOk = false;
+    try {
+        signatureOk = edVerify(null, Buffer.from(json, 'utf8'), publicKey, Buffer.from(parts[1], 'base64url'));
+    }
+    catch {
+        return { status: LicenseStatus.BAD_SIGNATURE };
+    }
+    if (!signatureOk)
+        return { status: LicenseStatus.BAD_SIGNATURE };
+    if (payload.exp <= now)
+        return { status: LicenseStatus.EXPIRED, payload };
+    return { status: LicenseStatus.VALID, payload };
+}
+/**
+ * Where to get a key. A named constant because it appears in the gate's error AND in what
+ * `reticle license` prints, and a contact address that drifts between the two is a support request
+ * that reaches nobody.
+ */
+export const LICENSE_CONTACT = 'hey@reticle.sh';
+/**
+ * The features a licence gates in THIS build. The single source: `assertEnterprise` callers name a
+ * member rather than a string literal, and `reticle license` reports the list, so what the CLI claims
+ * is gated is derived from what is actually gated rather than a second list somebody maintains.
+ *
+ * It is deliberately short. Reticle's roadmap for enterprise is longer (SSO, SCIM, RBAC, multi-org,
+ * policy gates), and none of it is here yet — printing a roadmap as though it were shipped is how a
+ * buyer discovers on day two that the thing they paid for does not exist. What is listed is what the
+ * running build will actually refuse without a key.
+ */
+export const EnterpriseFeature = {
+    /** Recording an audit event. */
+    AUDIT_LOG: 'audit-log',
+};
+/** Thrown when a production-mode enterprise feature is used without a valid license. */
+export class EnterpriseLicenseError extends Error {
+    feature;
+    reason;
+    constructor(feature, reason) {
+        super(`Reticle Enterprise feature "${feature}" requires a valid license (${reason}). Contact ${LICENSE_CONTACT}.`);
+        this.name = 'EnterpriseLicenseError';
+        this.feature = feature;
+        this.reason = reason;
+    }
+}
+/**
+ * Gate an enterprise feature. No-op in dev/eval (requireLicense:false). In production it throws
+ * EnterpriseLicenseError unless a valid, unexpired key that covers `feature` is present.
+ */
+export function assertEnterprise(feature, ctx, env = process.env, baked) {
+    if (!ctx.requireLicense)
+        return;
+    // Resolved exactly as the env-entry point resolves it: BAKED first, env only as the dev/test
+    // hatch. Reading the environment alone denies every valid licence on a real release, where the key
+    // is baked and no env var is set. Two gates, one truth.
+    const publicKey = ctx.publicKey ?? loadPublicKey(resolveIssuerPublicKeyPem(env, baked));
+    if (publicKey === undefined)
+        throw new EnterpriseLicenseError(feature, 'no-issuer-key');
+    const check = verifyLicenseKey(ctx.key, publicKey, ctx.now());
+    if (check.status !== LicenseStatus.VALID)
+        throw new EnterpriseLicenseError(feature, check.status);
+    const { features } = check.payload;
+    if (features !== undefined && !features.includes(feature)) {
+        throw new EnterpriseLicenseError(feature, 'feature-not-licensed');
+    }
+}
+/** Env names that carry the activation: the operator's key, and the issuer public key baked at release. */
+export const LICENSE_KEY_ENV = 'RETICLE_LICENSE_KEY';
+export const LICENSE_PUBLIC_KEY_ENV = 'RETICLE_LICENSE_PUBLIC_KEY';
+/**
+ * Issuer public key COMPILED INTO the build. Empty in the source tree; the release pipeline replaces
+ * this literal with the real spki PEM. Baking it (rather than only reading env) is what makes the
+ * enterprise gate fail closed: a self-hosted operator can no longer disable enforcement by simply
+ * never setting RETICLE_LICENSE_PUBLIC_KEY, because the baked key takes precedence. The public key is
+ * safe to ship openly — it can only verify licenses, never mint them (that needs the private key).
+ */
+const BAKED_ISSUER_PUBLIC_KEY_PEM = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAcg+u61Fs5pwDHcYxFGhaxVaQoUbAdyl+RUdSViZyxDY=\n-----END PUBLIC KEY-----";
+/**
+ * Resolve the issuer public-key PEM enforcement uses: the baked-in release key wins, so it can't be
+ * turned off from the environment. Only when nothing is baked (dev/repo) does the env var apply — that
+ * env path is the test/self-eval escape hatch, not the production switch.
+ */
+function resolveIssuerPublicKeyPem(env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
+    if (baked.length > 0)
+        return baked;
+    const envPem = env[LICENSE_PUBLIC_KEY_ENV];
+    return envPem !== undefined && envPem.length > 0 ? envPem : undefined;
+}
+/**
+ * The two fields every report carries, spread into each branch. One object rather than a field on each
+ * return, because the value that must never go missing is the one on the branch nobody was thinking
+ * about — and the branch an unlicensed reader lands on is exactly that branch.
+ */
+const LICENSE_OFFER = {
+    gated: Object.values(EnterpriseFeature),
+    contact: LICENSE_CONTACT,
+};
+function loadPublicKey(pem) {
+    if (pem === undefined || 0 === pem.length)
+        return undefined;
+    try {
+        return createPublicKey(pem);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve activation entirely from the environment — the install mechanism: the release bakes the
+ * issuer public key, the operator sets RETICLE_LICENSE_KEY. No public key configured ⇒ evaluation mode
+ * (enterprise features run free, dev/test only). Offline, no phone-home.
+ */
+export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
+    const pem = resolveIssuerPublicKeyPem(env, baked);
+    if (pem === undefined || 0 === pem.length) {
+        // In a production runtime this is NOT a benign eval session — it is a mis-built release whose gate
+        // is off, and assertEnterpriseFromEnv now denies rather than unlocking. Say so loudly here too.
+        return isProductionEnv(env)
+            ? {
+                ...LICENSE_OFFER,
+                status: LicenseActivation.INVALID,
+                detail: 'MISCONFIGURED — running in production with no issuer key baked; enterprise features are DENIED (rebuild with BAKED_ISSUER_PUBLIC_KEY_PEM stamped in)',
+            }
+            : {
+                ...LICENSE_OFFER,
+                status: LicenseActivation.EVAL,
+                detail: 'evaluation mode: enterprise features run free (no issuer key configured)',
+            };
+    }
+    const publicKey = loadPublicKey(pem);
+    if (publicKey === undefined)
+        return {
+            ...LICENSE_OFFER,
+            status: LicenseActivation.INVALID,
+            detail: `${LICENSE_PUBLIC_KEY_ENV} is not a valid public key`,
+        };
+    const check = verifyLicenseKey(env[LICENSE_KEY_ENV], publicKey, now);
+    if (check.status === LicenseStatus.VALID) {
+        const { lid, org, plan, exp, features } = check.payload;
+        // A key scoped to features this build does not gate is `active` and unlocks nothing. Both halves
+        // were already on screen (`features` against `gated`) and nothing joined them, so the one word a
+        // customer actually reads told them they were fine while every gated call refused them.
+        const coversNothingHere = features !== undefined && !features.some((f) => LICENSE_OFFER.gated.includes(f));
+        const detail = coversNothingHere
+            ? `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}. This key covers ${features?.join(', ')}, and nothing this build gates (${LICENSE_OFFER.gated.join(', ')}) is included. Contact ${LICENSE_CONTACT}`
+            : `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}`;
+        return {
+            contact: LICENSE_CONTACT,
+            // The one active case that still needs the list: a key covering nothing this build gates is
+            // reported here, and the sentence explaining it is unreadable without both sides named.
+            ...(coversNothingHere ? { gated: LICENSE_OFFER.gated } : {}),
+            status: LicenseActivation.ACTIVE,
+            licenseId: lid,
+            org,
+            plan,
+            expiresAt: exp,
+            ...(features !== undefined ? { features } : {}),
+            ...(coversNothingHere ? { coversNothingHere } : {}),
+            detail,
+        };
+    }
+    if (check.status === LicenseStatus.MISSING) {
+        return {
+            ...LICENSE_OFFER,
+            status: LicenseActivation.MISSING,
+            detail: `set ${LICENSE_KEY_ENV} to activate enterprise features in production. ` +
+                `Request a key from ${LICENSE_CONTACT}`,
+        };
+    }
+    if (check.status === LicenseStatus.EXPIRED) {
+        // The id rides an expired key so the lapse can be identified; without it an expiry is
+        // indistinguishable from any other.
+        return {
+            ...LICENSE_OFFER,
+            status: LicenseActivation.EXPIRED,
+            licenseId: check.payload.lid,
+            org: check.payload.org,
+            expiresAt: check.payload.exp,
+            detail: `license expired. Renew with ${LICENSE_CONTACT} to keep using enterprise features`,
+        };
+    }
+    return {
+        ...LICENSE_OFFER,
+        status: LicenseActivation.INVALID,
+        detail: `license key rejected (${check.status}). ${LICENSE_CONTACT} can re-issue it`,
+    };
+}
+/** True in a production runtime (NODE_ENV=production) — where a missing issuer key is a mis-built
+ *  release, not an eval session, so the gate must fail CLOSED rather than run features free. */
+function isProductionEnv(env) {
+    return 'production' === env['NODE_ENV'];
+}
+/**
+ * Gate an enterprise feature using env-resolved activation. Enforcement is ON when the issuer public key
+ * is configured (a real release). Without it, behaviour splits on runtime:
+ *  - dev/eval (NODE_ENV ≠ production): features run FREE — never blocks a contributor or CI.
+ *  - production (NODE_ENV = production): FAIL CLOSED — a release that reaches production with no
+ *    resolvable issuer key was mis-built (the baked key wasn't stamped in, BAKED_ISSUER_PUBLIC_KEY_PEM
+ *    is still ''), and silently unlocking every ee feature with no key and no warning is the worst
+ *    outcome. Deny instead, with a distinct reason so the misconfiguration is obvious.
+ */
+export function assertEnterpriseFromEnv(feature, now, env = process.env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
+    const publicKey = loadPublicKey(resolveIssuerPublicKeyPem(env, baked));
+    if (publicKey === undefined) {
+        if (isProductionEnv(env)) {
+            throw new EnterpriseLicenseError(feature, 'enterprise-gate-unconfigured');
+        }
+        return; // dev/eval — free
+    }
+    const key = env[LICENSE_KEY_ENV];
+    assertEnterprise(feature, {
+        requireLicense: true,
+        now: () => now,
+        ...(key !== undefined ? { key } : {}),
+        publicKey,
+    });
+}

package/dist/features/visual/visual-store.d.ts

@@ -0,0 +1,22 @@
+import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
+/**
+ * On-disk PNG baselines + diffs under .reticle/visual/. Binary sibling of FlowStore — same
+ * name guard (rejects path traversal before any join) and injected FileSystemPort, but bytes not text.
+ */
+export declare class VisualStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string);
+    /** The absolute baseline path for `name` (for echoing back to the agent). Guards the name so a
+     *  crafted value can never echo a path outside .reticle/visual/ to a future caller that does IO. */
+    baselinePath(name: string, runtime?: string): string;
+    /** The absolute overlay-diff path for `name`. Same name guard as baselinePath. */
+    diffPath(name: string, runtime?: string): string;
+    /** True iff a valid name and a baseline PNG exists on disk. */
+    hasBaseline(name: string, runtime?: string): Promise<boolean>;
+    /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
+    saveBaseline(name: string, png: Uint8Array, runtime?: string): Promise<string>;
+    /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
+    readBaseline(name: string, runtime?: string): Promise<Uint8Array | undefined>;
+    /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
+    saveDiff(name: string, png: Uint8Array, runtime?: string): Promise<string>;
+}

package/dist/features/visual/visual-store.js

@@ -0,0 +1,66 @@
+import { isValidFlowName, visualDiffPath, visualDir, visualPath, } from '../../memory/project/dir/reticle-dir.js';
+/**
+ * On-disk PNG baselines + diffs under .reticle/visual/. Binary sibling of FlowStore — same
+ * name guard (rejects path traversal before any join) and injected FileSystemPort, but bytes not text.
+ */
+export class VisualStore {
+    #fs;
+    #root;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#root = root;
+    }
+    /** The absolute baseline path for `name` (for echoing back to the agent). Guards the name so a
+     *  crafted value can never echo a path outside .reticle/visual/ to a future caller that does IO. */
+    baselinePath(name, runtime) {
+        if (!isValidFlowName(name))
+            throw new Error(`invalid visual baseline name: ${name}`);
+        return visualPath(this.#root, name, runtime);
+    }
+    /** The absolute overlay-diff path for `name`. Same name guard as baselinePath. */
+    diffPath(name, runtime) {
+        if (!isValidFlowName(name))
+            throw new Error(`invalid visual diff name: ${name}`);
+        return visualDiffPath(this.#root, name, runtime);
+    }
+    /** True iff a valid name and a baseline PNG exists on disk. */
+    async hasBaseline(name, runtime) {
+        if (!isValidFlowName(name))
+            return false;
+        return this.#fs.exists(visualPath(this.#root, name, runtime));
+    }
+    /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
+    async saveBaseline(name, png, runtime) {
+        if (!isValidFlowName(name))
+            throw new Error(`invalid visual baseline name: ${name}`);
+        // The runtime's own directory, not the shared one — see visualDir.
+        await this.#fs.mkdir(visualDir(this.#root, runtime));
+        const path = visualPath(this.#root, name, runtime);
+        await this.#fs.writeFileBytes(path, png);
+        return path;
+    }
+    /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
+    async readBaseline(name, runtime) {
+        if (!isValidFlowName(name) || !(await this.#fs.exists(visualPath(this.#root, name, runtime)))) {
+            return undefined;
+        }
+        try {
+            return await this.#fs.readFileBytes(visualPath(this.#root, name, runtime));
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return undefined; // exists/read TOCTOU race
+            throw error;
+        }
+    }
+    /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
+    async saveDiff(name, png, runtime) {
+        if (!isValidFlowName(name))
+            throw new Error(`invalid visual baseline name: ${name}`);
+        // Beside its baseline, or a diff lands in a directory the baseline is not in.
+        await this.#fs.mkdir(visualDir(this.#root, runtime));
+        const path = visualDiffPath(this.#root, name, runtime);
+        await this.#fs.writeFileBytes(path, png);
+        return path;
+    }
+}

package/dist/features/visual/visual-tools.d.ts

@@ -0,0 +1,26 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
+ */
+export declare function isCapturePath(path: string): boolean;
+/**
+ * The opt-in pixel layer. Both tools require a DRIVEN browser (reticle drive /
+ * RETICLE_CDP_URL) — the always-on SDK ships no screenshotter — and return a structured NO_PROVIDER
+ * envelope (with a recommendation) instead of throwing when none is attached. Behavioral checks
+ * stay the default; this is the complementary "does it look right" surface, never bundled in.
+ */
+export declare const VISUAL_TOOLS: ToolDef[];