@reticlehq/server 2.14.0 → 3.2.0

package/dist/features/harness/openai-driver.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The harness driver for OpenAI's Chat Completions API.
+ *
+ * Third driver, and the reason it exists is comparison rather than capability: people want to know
+ * whether the cheap typed-decision model is good enough for THEIR app, and "cheap versus one
+ * frontier model" is a weaker answer than "cheap versus the two they might otherwise reach for".
+ *
+ * A translation layer, exactly like `driver.ts` — the loop lives in `harness.ts` against
+ * `ModelDriver` and knows nothing about any wire. Chat Completions is a genuinely different shape
+ * from the Messages API, and translating OpenAI into Anthropic's wire on the platform side was
+ * considered and rejected there: it would put a second, undeclared model-shaped transformation
+ * inside the thing being measured. So this speaks the native format and the arm measures OpenAI.
+ *
+ * NOT cache-annotated, and that is a real asymmetry to hold in mind when reading a cost comparison
+ * against the Anthropic arm. OpenAI caches long prefixes automatically and reports it back in
+ * `usage.prompt_tokens_details.cached_tokens`, so the saving is not something this driver arranges;
+ * it is reported below so the number is visible rather than assumed.
+ */
+import type { ModelDriver } from './harness.js';
+import type { HarnessFetch } from './driver.js';
+/**
+ * The default model.
+ *
+ * Deliberately not the largest available, for the same reason `DEFAULT_HARNESS_MODEL` is not: the
+ * driver is choosing what to touch next, and the engine decides the verdict from evidence. A driver
+ * that needed a frontier model would be evidence the engine was not doing its job.
+ */
+export declare const DEFAULT_OPENAI_MODEL = "gpt-5.6-luna";
+export declare const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com";
+export interface OpenAiDriverOptions {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    /** Injected for tests. Defaults to the platform `fetch`. */
+    fetch?: HarnessFetch;
+}
+/**
+ * Read this driver's configuration out of the environment.
+ *
+ * A real OpenAI key goes to OpenAI. The platform key goes to the platform, which forwards with its
+ * own — so somebody who has run `reticle link` can drive with this model having never held an
+ * OpenAI key, which is the entire point of the proxy.
+ */
+export declare function openAiOptionsFromEnv(env: Record<string, string | undefined>): OpenAiDriverOptions | undefined;
+/** Build a driver backed by Chat Completions. */
+export declare function openAiDriver(options: OpenAiDriverOptions): ModelDriver;

package/dist/features/harness/openai-driver.js

@@ -0,0 +1,197 @@
+/**
+ * The harness driver for OpenAI's Chat Completions API.
+ *
+ * Third driver, and the reason it exists is comparison rather than capability: people want to know
+ * whether the cheap typed-decision model is good enough for THEIR app, and "cheap versus one
+ * frontier model" is a weaker answer than "cheap versus the two they might otherwise reach for".
+ *
+ * A translation layer, exactly like `driver.ts` — the loop lives in `harness.ts` against
+ * `ModelDriver` and knows nothing about any wire. Chat Completions is a genuinely different shape
+ * from the Messages API, and translating OpenAI into Anthropic's wire on the platform side was
+ * considered and rejected there: it would put a second, undeclared model-shaped transformation
+ * inside the thing being measured. So this speaks the native format and the arm measures OpenAI.
+ *
+ * NOT cache-annotated, and that is a real asymmetry to hold in mind when reading a cost comparison
+ * against the Anthropic arm. OpenAI caches long prefixes automatically and reports it back in
+ * `usage.prompt_tokens_details.cached_tokens`, so the saving is not something this driver arranges;
+ * it is reported below so the number is visible rather than assumed.
+ */
+import { z } from 'zod';
+import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+/**
+ * The default model.
+ *
+ * Deliberately not the largest available, for the same reason `DEFAULT_HARNESS_MODEL` is not: the
+ * driver is choosing what to touch next, and the engine decides the verdict from evidence. A driver
+ * that needed a frontier model would be evidence the engine was not doing its job.
+ */
+export const DEFAULT_OPENAI_MODEL = 'gpt-5.6-luna';
+export const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com';
+/** The platform's own path, which forwards with Reticle's key rather than the caller's. */
+const PLATFORM_PATH = '/v1/model/openai';
+const OPENAI_PATH = '/v1/chat/completions';
+/** Output cap per turn. A driving turn is a sentence and a tool call, never an essay. */
+const MAX_TOKENS = 4096;
+/** How much of one tool result the model is allowed to see. Same reasoning as the Anthropic driver. */
+const MAX_RESULT_CHARS = 8000;
+const ToolCall = z.object({
+    id: z.string(),
+    function: z.object({ name: z.string(), arguments: z.string().default('{}') }),
+});
+const ChatResponse = z.object({
+    choices: z
+        .array(z.object({
+        message: z.object({
+            content: z.string().nullish(),
+            tool_calls: z.array(ToolCall).nullish(),
+        }),
+    }))
+        .default([]),
+    usage: z
+        .object({
+        prompt_tokens: z.number().default(0),
+        completion_tokens: z.number().default(0),
+        prompt_tokens_details: z.object({ cached_tokens: z.number().nullish() }).nullish(),
+    })
+        .default({ prompt_tokens: 0, completion_tokens: 0 }),
+});
+/**
+ * Read this driver's configuration out of the environment.
+ *
+ * A real OpenAI key goes to OpenAI. The platform key goes to the platform, which forwards with its
+ * own — so somebody who has run `reticle link` can drive with this model having never held an
+ * OpenAI key, which is the entire point of the proxy.
+ */
+export function openAiOptionsFromEnv(env) {
+    const model = env[ReticleEnv.HARNESS_OPENAI_MODEL];
+    const withModel = (rest) => ({
+        ...rest,
+        ...(model === undefined || 0 === model.length ? {} : { model }),
+    });
+    const direct = env[ReticleEnv.HARNESS_OPENAI_KEY];
+    if (direct !== undefined && 0 < direct.length)
+        return withModel({ apiKey: direct });
+    const cloudKey = apiKeyFrom(env);
+    const cloudUrl = env[ReticleEnv.CLOUD_URL];
+    if (cloudKey === undefined || 0 === cloudKey.length)
+        return undefined;
+    if (cloudUrl === undefined || 0 === cloudUrl.length)
+        return undefined;
+    return withModel({ apiKey: cloudKey, baseUrl: cloudUrl });
+}
+function toWireTool(tool) {
+    return {
+        type: 'function',
+        function: { name: tool.name, description: tool.description, parameters: tool.inputSchema },
+    };
+}
+function truncate(text) {
+    return text.length <= MAX_RESULT_CHARS
+        ? text
+        : `${text.slice(0, MAX_RESULT_CHARS)}\n…[truncated: ${String(text.length - MAX_RESULT_CHARS)} more characters]`;
+}
+/**
+ * The history, in Chat Completions' shape.
+ *
+ * The one structural difference from the Messages API, and it matters: a tool result is its OWN
+ * message carrying `tool_call_id`, where Anthropic puts every result for a turn into one user
+ * message. So a turn with three parallel calls becomes one assistant message and three tool
+ * messages. That is the format's requirement rather than a choice — an unanswered `tool_call_id`
+ * is rejected outright, so every outcome must be emitted, including the failures.
+ */
+function toWireMessages(history) {
+    const messages = [];
+    for (const entry of history) {
+        if ('user' === entry.role) {
+            messages.push({ role: 'user', content: entry.text });
+            continue;
+        }
+        if ('assistant' === entry.role) {
+            messages.push({
+                role: 'assistant',
+                content: 0 === entry.text.length ? null : entry.text,
+                ...(0 === entry.calls.length
+                    ? {}
+                    : {
+                        tool_calls: entry.calls.map((call) => ({
+                            id: call.id,
+                            type: 'function',
+                            function: { name: call.name, arguments: JSON.stringify(call.args) },
+                        })),
+                    }),
+            });
+            continue;
+        }
+        for (const outcome of entry.outcomes) {
+            messages.push({
+                role: 'tool',
+                tool_call_id: outcome.id,
+                content: truncate(JSON.stringify(outcome.result)),
+            });
+        }
+    }
+    return messages;
+}
+/** Arguments arrive as a JSON STRING here, not an object — a malformed one is empty, never a throw. */
+function parseArgs(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return 'object' === typeof parsed && null !== parsed ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Build a driver backed by Chat Completions. */
+export function openAiDriver(options) {
+    const model = options.model ?? DEFAULT_OPENAI_MODEL;
+    const baseUrl = options.baseUrl ?? DEFAULT_OPENAI_BASE_URL;
+    const doFetch = options.fetch ?? ((url, init) => fetch(url, init));
+    // The platform does not expose `/v1/chat/completions`; it exposes its own path and forwards. A
+    // base URL that is not OpenAI's is the platform's, which is the only other thing this talks to.
+    const path = DEFAULT_OPENAI_BASE_URL === baseUrl ? OPENAI_PATH : PLATFORM_PATH;
+    return {
+        async turn(input) {
+            const response = await doFetch(`${baseUrl}${path}`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${options.apiKey}`,
+                },
+                body: JSON.stringify({
+                    model,
+                    max_completion_tokens: MAX_TOKENS,
+                    tools: input.tools.map(toWireTool),
+                    messages: [{ role: 'system', content: input.system }, ...toWireMessages(input.history)],
+                }),
+            });
+            const body = await response.text();
+            // Thrown, not returned: a model that will not answer is a BROKEN drive, and a broken drive is
+            // never reported as clean. Swallowing it would be a verdict about an app nobody drove.
+            if (!response.ok)
+                throw new Error(`the model refused the request (HTTP ${String(response.status)}): ${body}`);
+            const parsed = ChatResponse.parse(JSON.parse(body));
+            const message = parsed.choices[0]?.message;
+            const calls = (message?.tool_calls ?? []).map((call) => ({
+                id: call.id,
+                name: call.function.name,
+                args: parseArgs(call.function.arguments),
+            }));
+            const cached = parsed.usage.prompt_tokens_details?.cached_tokens ?? 0;
+            return {
+                text: message?.content ?? '',
+                calls,
+                usage: {
+                    // `prompt_tokens` INCLUDES the cached ones here, unlike the Messages API where the two are
+                    // disjoint. Subtracting keeps `input` meaning the same thing in both drivers: what was
+                    // processed at full price. A cost comparison that summed them would charge the arm that
+                    // cached well for the tokens it did not pay full price for.
+                    input: Math.max(parsed.usage.prompt_tokens - cached, 0),
+                    output: parsed.usage.completion_tokens,
+                    cacheRead: cached,
+                    cacheWrite: 0,
+                },
+            };
+        },
+    };
+}

package/dist/features/harness/platform-config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The driver preference a person set on the platform, read by the daemon that has to honour it.
+ *
+ * Choosing a model in a web UI is worth nothing if the thing doing the driving never asks. This is
+ * the one call that closes that loop: the console writes a per-project preference, and the daemon
+ * reads it before it builds a driver.
+ *
+ * Three rules shape all of it, and they are the difference between a preference and an outage:
+ *
+ *   - it is a PREFERENCE, not a credential. Every failure — no key, no host, a timeout, a 500, a
+ *     body that does not parse — answers `undefined`, and the caller falls back to what the
+ *     environment says. A drive must never fail because a settings endpoint was slow.
+ *   - it is BOUNDED. The fetch is aborted rather than awaited indefinitely. A drive that hangs
+ *     holds a leased browser context with nothing anywhere saying why, and "the preferences API was
+ *     unreachable" is the worst possible reason for that to happen.
+ *   - it never overrides someone who was EXPLICIT. A driver named in the call, or set in the
+ *     environment, wins over the stored preference. Precedence lives in the caller.
+ */
+/** The subset of the platform's answer the harness acts on. */
+export interface PlatformModelConfig {
+    /** `jev` | `anthropic` | `openai`, as the platform spells it. Not validated here. */
+    provider: string;
+    /** Whether the person wants autonomous driving at all. */
+    harnessEnabled: boolean;
+    /**
+     * Whether this workspace may drive on OUR model spend — a claimed free period, or a paid plan.
+     *
+     * Deliberately a second boolean rather than folded into `harnessEnabled`. One is a switch a person
+     * set, the other is a fact about their account, and a daemon that could not tell them apart would
+     * report "you turned this off" to somebody whose free months quietly ran out.
+     */
+    harnessEntitled: boolean;
+}
+/** A GET, narrowed to what this file uses, so a test can answer it without a network. */
+export type ConfigFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/**
+ * Ask the platform which model this project wants driving with.
+ *
+ * `undefined` means "no answer", and every caller must treat that as "carry on with the
+ * environment" rather than as a failure worth reporting. There is deliberately no error channel:
+ * an unreachable settings endpoint is not something the person running a drive can act on, and a
+ * warning printed on a path that then works correctly is how people learn to ignore stderr.
+ */
+export declare function fetchPlatformConfig(env: Record<string, string | undefined>, doFetch?: ConfigFetch, timeoutMs?: number): Promise<PlatformModelConfig | undefined>;

package/dist/features/harness/platform-config.js

@@ -0,0 +1,89 @@
+/**
+ * The driver preference a person set on the platform, read by the daemon that has to honour it.
+ *
+ * Choosing a model in a web UI is worth nothing if the thing doing the driving never asks. This is
+ * the one call that closes that loop: the console writes a per-project preference, and the daemon
+ * reads it before it builds a driver.
+ *
+ * Three rules shape all of it, and they are the difference between a preference and an outage:
+ *
+ *   - it is a PREFERENCE, not a credential. Every failure — no key, no host, a timeout, a 500, a
+ *     body that does not parse — answers `undefined`, and the caller falls back to what the
+ *     environment says. A drive must never fail because a settings endpoint was slow.
+ *   - it is BOUNDED. The fetch is aborted rather than awaited indefinitely. A drive that hangs
+ *     holds a leased browser context with nothing anywhere saying why, and "the preferences API was
+ *     unreachable" is the worst possible reason for that to happen.
+ *   - it never overrides someone who was EXPLICIT. A driver named in the call, or set in the
+ *     environment, wins over the stored preference. Precedence lives in the caller.
+ */
+import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+const CONFIG_PATH = '/v1/model/config';
+/**
+ * How long the daemon will wait for a preference before driving without it.
+ *
+ * Short on purpose. This runs before a drive that takes tens of seconds, so a second of budget is
+ * affordable and a stall is not — and the fallback is not a degraded mode, it is the behaviour
+ * everybody had before this endpoint existed.
+ */
+const TIMEOUT_MS = 2_000;
+function parse(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if ('object' !== typeof parsed || null === parsed)
+            return undefined;
+        const record = parsed;
+        const provider = record['provider'];
+        if ('string' !== typeof provider || 0 === provider.length)
+            return undefined;
+        // Absent reads as enabled: the platform's own default is on, and a daemon that treated a
+        // missing field as "off" would silently disable the feature for anyone on an older API.
+        const enabled = record['harnessEnabled'];
+        // Same rule for both, for the same reason: an older API that reports neither must not have its
+        // silence read as a refusal.
+        const entitled = record['harnessEntitled'];
+        return {
+            provider,
+            harnessEnabled: 'boolean' === typeof enabled ? enabled : true,
+            harnessEntitled: 'boolean' === typeof entitled ? entitled : true,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Ask the platform which model this project wants driving with.
+ *
+ * `undefined` means "no answer", and every caller must treat that as "carry on with the
+ * environment" rather than as a failure worth reporting. There is deliberately no error channel:
+ * an unreachable settings endpoint is not something the person running a drive can act on, and a
+ * warning printed on a path that then works correctly is how people learn to ignore stderr.
+ */
+export async function fetchPlatformConfig(env, doFetch = (url, init) => fetch(url, init), timeoutMs = TIMEOUT_MS) {
+    const key = apiKeyFrom(env);
+    const host = env[ReticleEnv.CLOUD_URL];
+    if (key === undefined || 0 === key.length)
+        return undefined;
+    if (host === undefined || 0 === host.length)
+        return undefined;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const res = await doFetch(`${host.replace(/\/+$/, '')}${CONFIG_PATH}`, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${key}` },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return undefined;
+        return parse(await res.text());
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/features/harness/with-timeout.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bound a promise that may never settle.
+ *
+ * A drive waits in more than one place, and every one of them holds the same scarce thing while it
+ * waits: a leased browser context pointed at the app under test. An unbounded wait therefore does not
+ * cost one run, it wedges the browser — and it is silent, because nothing has failed yet.
+ *
+ * The timer is cleared on both paths. An outstanding timer keeps a short-lived process alive for its
+ * full duration after the work has finished, which turns a fast CLI invocation into a mysteriously
+ * slow one.
+ */
+export declare function withTimeout<T>(work: Promise<T>, ms: number, 
+/**
+ * The whole phrase, subject and verb — "the model did not answer", "the browser never came free".
+ * It is printed in a report somebody reads, and a generic "operation timed out" tells them nothing
+ * about which of a run's several waits gave up.
+ */
+gaveUp: string): Promise<T>;

package/dist/features/harness/with-timeout.js

@@ -0,0 +1,34 @@
+/**
+ * Bound a promise that may never settle.
+ *
+ * A drive waits in more than one place, and every one of them holds the same scarce thing while it
+ * waits: a leased browser context pointed at the app under test. An unbounded wait therefore does not
+ * cost one run, it wedges the browser — and it is silent, because nothing has failed yet.
+ *
+ * The timer is cleared on both paths. An outstanding timer keeps a short-lived process alive for its
+ * full duration after the work has finished, which turns a fast CLI invocation into a mysteriously
+ * slow one.
+ */
+export async function withTimeout(work, ms, 
+/**
+ * The whole phrase, subject and verb — "the model did not answer", "the browser never came free".
+ * It is printed in a report somebody reads, and a generic "operation timed out" tells them nothing
+ * about which of a run's several waits gave up.
+ */
+gaveUp) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error(`${gaveUp} within ${String(ms)}ms`));
+                }, ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Find an enterprise licence key wherever it was reasonably placed.
+ *
+ * The daemon is spawned without an explicit `cwd`, so it inherits whatever directory the editor
+ * launched the MCP server from — in a monorepo that is often the workspace root while the key sits in
+ * the app's own `.env`. Reading `<cwd>/.env` alone therefore misses the key and reports `missing`,
+ * which is indistinguishable from having no licence at all: the failure is silent on both sides.
+ *
+ * So the search runs in two directions: DOWN one level into app directories (the daemon started at
+ * the workspace root) and UP to the project root (the editor started inside the app).
+ *
+ * ONLY the licence key is ever taken out of a file found this way, and that restriction is the point
+ * rather than an optimisation. Bulk-importing a `.env` discovered by walking would let a directory
+ * the caller never named rebind the daemon's port, its telemetry gate or its allowed origins — a far
+ * worse bug than the one this fixes. `loadDotEnv` still owns the local file, where importing
+ * everything is what the caller asked for.
+ */
+/**
+ * The key, or undefined. Never throws, never mutates anything the caller did not ask it to.
+ *
+ * A key already present in `env` always wins: that is the operator stating it explicitly, and a file
+ * silently overriding it is the surprise `loadDotEnv` already refuses to cause.
+ */
+export declare function licenseKeyFromEnvFiles(startDir: string, env?: NodeJS.ProcessEnv): string | undefined;

package/dist/features/license/license-env.js

@@ -0,0 +1,140 @@
+/**
+ * Find an enterprise licence key wherever it was reasonably placed.
+ *
+ * The daemon is spawned without an explicit `cwd`, so it inherits whatever directory the editor
+ * launched the MCP server from — in a monorepo that is often the workspace root while the key sits in
+ * the app's own `.env`. Reading `<cwd>/.env` alone therefore misses the key and reports `missing`,
+ * which is indistinguishable from having no licence at all: the failure is silent on both sides.
+ *
+ * So the search runs in two directions: DOWN one level into app directories (the daemon started at
+ * the workspace root) and UP to the project root (the editor started inside the app).
+ *
+ * ONLY the licence key is ever taken out of a file found this way, and that restriction is the point
+ * rather than an optimisation. Bulk-importing a `.env` discovered by walking would let a directory
+ * the caller never named rebind the daemon's port, its telemetry gate or its allowed origins — a far
+ * worse bug than the one this fixes. `loadDotEnv` still owns the local file, where importing
+ * everything is what the caller asked for.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { LICENSE_KEY_ENV } from './license.js';
+import { discoverProjectConfigs } from '../../command/cli/config/config-discovery.js';
+/** The files a framework tells people to put secrets in, most specific first. */
+const ENV_FILES = ['.env.local', '.env'];
+/** Stop the upward walk here: a licence belongs to a project, not to a machine. */
+const ROOT_MARKERS = ['.git', 'package.json', 'pnpm-workspace.yaml'];
+/** A bound on the upward walk, so a pathological path cannot spin. */
+const MAX_DEPTH = 12;
+function readKey(file) {
+    try {
+        if (!existsSync(file))
+            return undefined;
+        for (const raw of readFileSync(file, 'utf8').split('\n')) {
+            const line = raw.trim();
+            if (0 === line.length || line.startsWith('#'))
+                continue;
+            const eq = line.indexOf('=');
+            if (eq <= 0)
+                continue;
+            if (line.slice(0, eq).trim() !== LICENSE_KEY_ENV)
+                continue;
+            const value = line.slice(eq + 1).trim();
+            const first = value[0];
+            const unquoted = ('"' === first || "'" === first) && value.endsWith(first) && value.length >= 2
+                ? value.slice(1, -1)
+                : value;
+            if (unquoted.length > 0)
+                return unquoted;
+        }
+    }
+    catch {
+        // A licence probe may never take the daemon down, and an unreadable file is not an error here.
+    }
+    return undefined;
+}
+function inDir(dir) {
+    for (const name of ENV_FILES) {
+        const found = readKey(join(dir, name));
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function isRoot(dir) {
+    return ROOT_MARKERS.some((marker) => existsSync(join(dir, marker)));
+}
+/**
+ * The conventional layout, kept as a fallback beside the declaration-driven search above.
+ *
+ * `discoverProjectConfigs` descends only into DECLARED workspaces, which is right and is what a real
+ * monorepo has. But `apps/web` with no `workspaces` entry is a shape people genuinely ship, and for
+ * a licence key the cost of one extra `readdir` is nothing against reporting a licensed install as
+ * unlicensed. Strictly widens coverage; it can never contradict the discovery, only add to it.
+ */
+const CONVENTIONAL_DIRS = ['apps', 'packages'];
+function inConventionalChildren(dir) {
+    for (const group of CONVENTIONAL_DIRS) {
+        const base = join(dir, group);
+        let entries;
+        try {
+            if (!existsSync(base) || !statSync(base).isDirectory())
+                continue;
+            entries = readdirSync(base);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const found = inDir(join(base, entry));
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
+/**
+ * The directories that hold a `.reticle.json`: the apps that were actually instrumented.
+ *
+ * The same discovery the no-session diagnosis uses to tell an agent where the app really is, so the
+ * licence search and that diagnosis can never disagree about where the project lives. It replaced a
+ * guess at `apps/*` and `packages/*`, which missed the workspace shapes people actually ship.
+ */
+function inDiscoveredProjects(dir) {
+    let found;
+    try {
+        found = discoverProjectConfigs(dir).found;
+    }
+    catch {
+        return undefined;
+    }
+    for (const config of found) {
+        const key = inDir(config.directory);
+        if (key !== undefined)
+            return key;
+    }
+    return undefined;
+}
+/**
+ * The key, or undefined. Never throws, never mutates anything the caller did not ask it to.
+ *
+ * A key already present in `env` always wins: that is the operator stating it explicitly, and a file
+ * silently overriding it is the surprise `loadDotEnv` already refuses to cause.
+ */
+export function licenseKeyFromEnvFiles(startDir, env = process.env) {
+    const existing = env[LICENSE_KEY_ENV];
+    if (existing !== undefined && existing.length > 0)
+        return existing;
+    let dir = startDir;
+    for (let depth = 0; depth < MAX_DEPTH; depth++) {
+        const here = inDir(dir) ?? inDiscoveredProjects(dir) ?? inConventionalChildren(dir);
+        if (here !== undefined)
+            return here;
+        if (isRoot(dir))
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}