@reticlehq/server 3.3.0 → 3.5.0

package/dist/features/exhaust/session-port.js

@@ -0,0 +1,102 @@
+/**
+ * A live session, as the explorer's port.
+ *
+ * The one hard part is that a full page load REPLACES the session: the SDK reconnects under the
+ * same id (sessionStorage keeps it) but as a new object, and a command in flight on the old one is
+ * rejected. So every call reads the CURRENT session, and anything that may have navigated waits for
+ * the successor before it answers — the same wait `navigate { reload }` does.
+ */
+import { ActionType, ReticleCommand, ReticleTool, SnapshotMode, asRecord, asString, } from '@reticlehq/core';
+import { RELOAD_RECONNECT_TIMEOUT_MS, waitForReconnect, } from '../../portal/session/session-reconnect.js';
+import { isSessionReplacedError } from '../../portal/session/facts/session-replaced.js';
+export function sessionPort(input) {
+    let current = input.start;
+    /** Wait for the document that replaced `before`. False when none arrived in time. */
+    const successor = async (before) => {
+        const back = await waitForReconnect({
+            current: () => input.sessions.get(before.id),
+            previous: before,
+            timeoutMs: RELOAD_RECONNECT_TIMEOUT_MS,
+            now: input.now,
+            sleep: input.sleep,
+        });
+        const next = input.sessions.get(before.id);
+        if (!back || next === undefined)
+            return false;
+        current = next;
+        return true;
+    };
+    const look = async () => {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            try {
+                const res = await current.command(ReticleCommand.SNAPSHOT, {
+                    mode: SnapshotMode.INTERACTIVE,
+                });
+                const body = asRecord(res.result);
+                const route = asString(asRecord(body['status'])['route']);
+                return { tree: asString(body['tree']) ?? '', ...(route === undefined ? {} : { route }) };
+            }
+            catch (error) {
+                // A click that followed a real link leaves the next read on a dead document.
+                if (!isSessionReplacedError(error) || !(await successor(current)))
+                    break;
+            }
+        }
+        return { tree: '' };
+    };
+    return {
+        current: () => current,
+        look,
+        async reset() {
+            const before = current;
+            try {
+                const res = await before.command(ReticleCommand.NAVIGATE, { url: input.startUrl });
+                if (!res.ok)
+                    return false;
+            }
+            catch (error) {
+                if (!isSessionReplacedError(error))
+                    return false;
+            }
+            if (!(await successor(before)))
+                return false;
+            await input.sleep(input.settleMs);
+            return true;
+        },
+        async act(ref, action, value) {
+            const session = current;
+            const since = session.elapsed();
+            session.beginAction?.(ReticleTool.CRAWL, { ref, action });
+            let ok = false;
+            let replaced = false;
+            try {
+                const res = await session.command(ReticleCommand.ACT, {
+                    ref,
+                    action: 'fill' === action ? ActionType.FILL : ActionType.CLICK,
+                    args: value === undefined ? {} : { value },
+                });
+                ok = res.ok && false !== asRecord(res.result)['dispatched'];
+            }
+            catch (error) {
+                // Following a real link replaces the document mid-command: the click WORKED.
+                if (!isSessionReplacedError(error))
+                    throw error;
+                replaced = true;
+                ok = true;
+            }
+            finally {
+                session.finishAction?.();
+            }
+            await input.sleep(input.settleMs);
+            const events = session.eventsSince(since);
+            if (replaced && (await successor(session)))
+                return { ok, events: [...events, ...current.eventsSince(0)] };
+            return { ok, events };
+        },
+        ...(input.setMocks === undefined
+            ? {}
+            : {
+                mock: (rules) => input.setMocks?.(current.url, rules) ?? Promise.resolve(false),
+            }),
+    };
+}

package/dist/features/harness/drive-report.d.ts

@@ -61,13 +61,4 @@ export declare function replayedFlows(toolCalls: readonly ToolOutcome[]): {
 }[];
 /** Reduce the raw call log to the actions that actually drove the app. */
 export declare function drivenSteps(toolCalls: readonly ToolOutcome[]): DrivenStep[];
-/**
- * The account, as lines.
- *
- * Proved and not-proved are counted separately and both are stated, because the failure mode this
- * whole product exists to prevent is a reader taking "we did twelve things" for "twelve things
- * work". `unknown` is deliberately grouped under NOT proved and labelled as undecided evidence
- * rather than as a failure — it calls for a better check, not a code change, and collapsing the two
- * would send an agent to rewrite working code.
- */
 export declare function describeDrive(toolCalls: readonly ToolOutcome[], savedFlows: readonly string[]): string;

package/dist/features/harness/drive-report.js

@@ -134,6 +134,18 @@ export function drivenSteps(toolCalls) {
  * rather than as a failure — it calls for a better check, not a code change, and collapsing the two
  * would send an agent to rewrite working code.
  */
+/** The pages the drive's own snapshots reported, in order, each distinct page once. */
+function pagesReached(toolCalls) {
+    const pages = [];
+    for (const call of toolCalls) {
+        if (ReticleTool.SNAPSHOT !== call.name || call.isError)
+            continue;
+        const route = asString(asRecord(asRecord(call.result)['status'])['route']);
+        if (route !== undefined && !pages.includes(route))
+            pages.push(route);
+    }
+    return pages;
+}
 export function describeDrive(toolCalls, savedFlows) {
     const steps = drivenSteps(toolCalls);
     const replays = replayedFlows(toolCalls);
@@ -166,10 +178,16 @@ export function describeDrive(toolCalls, savedFlows) {
     const proved = steps.filter((step) => Verified.YES === step.verified);
     const failed = steps.filter((step) => Verified.NO === step.verified);
     const undecided = steps.filter((step) => Verified.YES !== step.verified && Verified.NO !== step.verified);
+    const pages = pagesReached(toolCalls);
     const lines = [
         ...(replayLine === undefined ? [] : [replayLine]),
         `Drove ${String(steps.length)} action(s): ${String(proved.length)} proved, ` +
             `${String(failed.length)} failed, ${String(undecided.length)} not decided.`,
+        // How DEEP it got. An action count reads the same for a checkout walked to its receipt and for
+        // eleven clicks on the home page; the pages reached are what tell them apart.
+        ...(0 === pages.length
+            ? []
+            : [`Reached ${String(pages.length)} page(s): ${pages.join(' → ')}.`]),
     ];
     for (const step of steps.slice(0, MAX_LISTED)) {
         const verdict = step.verified ?? 'nothing declared';

package/dist/features/harness/driver.js

@@ -11,7 +11,7 @@
  * purpose.
  */
 import { z } from 'zod';
-import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+import { ReticleEnv, platformCredentialFrom } from '@reticlehq/core';
 /**
  * The default driver model.
  *
@@ -91,13 +91,10 @@ export function harnessOptionsFromEnv(env) {
      *
      * An explicit `ANTHROPIC_API_KEY` still wins: someone who exported one meant it.
      */
-    const cloudKey = apiKeyFrom(env);
-    const cloudUrl = env[ReticleEnv.CLOUD_URL];
-    if (cloudKey === undefined || 0 === cloudKey.length)
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
-    if (cloudUrl === undefined || 0 === cloudUrl.length)
-        return undefined;
-    return withOptions(cloudKey, cloudUrl);
+    return withOptions(cloud.apiKey, cloud.url);
 }
 /** Build a driver backed by the Messages API. */
 export function harnessDriver(options) {

package/dist/features/harness/fill-values.d.ts

@@ -31,6 +31,7 @@
  * wrong verdict. Nothing here touches what is judged.
  */
 import { type HarnessDriverOptions } from './driver.js';
+import { type OpenAiDriverOptions } from './openai-driver.js';
 /** What the caller must be able to do for values to survive past this drive. */
 export interface FillCache {
     get(label: string): string | undefined;
@@ -61,7 +62,16 @@ export declare function needsGeneration(label: string): boolean;
  */
 export declare function fillValues(deps: {
     cache?: FillCache;
+    /** GPT, the generator a Jev drive pairs with. Asked ahead of `generator` when both are set. */
+    openai?: OpenAiDriverOptions;
+    /** Anthropic, for a machine that holds only that key. */
     generator?: HarnessDriverOptions;
     /** One line about where the drive is, so a value suits the page it is typed on. */
     context?: () => string;
+    /**
+     * A value the user SUPPLIED for this field — the same `RETICLE_SECRET_<FIELD>` replay reads for
+     * a redacted one. Checked first so a drive gets past a login, and never cached: the cache is a
+     * file on disk.
+     */
+    secret?: (label: string) => string | undefined;
 }): (label: string) => Promise<string>;

package/dist/features/harness/fill-values.js

@@ -31,6 +31,7 @@
  * wrong verdict. Nothing here touches what is judged.
  */
 import { DEFAULT_HARNESS_BASE_URL, } from './driver.js';
+import { DEFAULT_OPENAI_MODEL, OPENAI_REASONING_EFFORT, openAiCompletionsUrl, } from './openai-driver.js';
 /** Deliberately small. A field value is a phrase; anything longer is the model misunderstanding. */
 const MAX_TOKENS = 64;
 const ANTHROPIC_VERSION = '2023-06-01';
@@ -87,6 +88,40 @@ const PROMPT = (label, context) => `A test harness is filling in a form field on
     `Reply with ONLY the value to type. No quotes, no explanation, no markdown. It must be something a ` +
     `real user would plausibly enter, and short. If the field wants an identifier or a code, invent a ` +
     `well-formed one.`;
+/**
+ * A model's one-line answer as a field value, or nothing. A model asked for one value occasionally
+ * answers with a sentence about the value; anything long enough to be prose is not a field value,
+ * and typing prose proves nothing about the app.
+ */
+function asValue(raw) {
+    const text = raw?.trim().split('\n')[0];
+    if (text === undefined || 0 === text.length)
+        return undefined;
+    return 80 < text.length ? undefined : text.replace(/^["']|["']$/g, '');
+}
+/** One string from GPT over Chat Completions — directly, or through the platform with its key. */
+async function generateWithOpenAi(options, label, context) {
+    const call = options.fetch ?? ((url, init) => fetch(url, init));
+    try {
+        const res = await call(openAiCompletionsUrl(options), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${options.apiKey}` },
+            body: JSON.stringify({
+                model: options.model ?? DEFAULT_OPENAI_MODEL,
+                max_completion_tokens: MAX_TOKENS,
+                reasoning_effort: OPENAI_REASONING_EFFORT,
+                messages: [{ role: 'user', content: PROMPT(label, context) }],
+            }),
+        });
+        if (!res.ok)
+            return undefined;
+        const parsed = JSON.parse(await res.text());
+        return asValue(parsed.choices?.[0]?.message?.content ?? undefined);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** One string from a generating model, or nothing. Never throws: a drive must not fail over a field. */
 async function generateOne(options, label, context) {
     const call = options.fetch ?? ((url, init) => fetch(url, init));
@@ -109,17 +144,10 @@ async function generateOne(options, label, context) {
             return undefined;
         const parsed = JSON.parse(await res.text());
         const content = parsed.content ?? [];
-        const text = content
+        return asValue(content
             .filter((block) => 'text' === block.type)
             .map((block) => block.text ?? '')
-            .join('')
-            .trim()
-            .split('\n')[0];
-        if (text === undefined || 0 === text.length)
-            return undefined;
-        // A model asked for one value occasionally answers with a sentence about the value. Anything
-        // long enough to be prose is not a field value, and typing prose proves nothing about the app.
-        return 80 < text.length ? undefined : text.replace(/^["']|["']$/g, '');
+            .join(''));
     }
     catch {
         // Offline, refused, rate-limited, malformed. All the same answer: use the heuristic.
@@ -135,14 +163,25 @@ async function generateOne(options, label, context) {
 export function fillValues(deps) {
     let spent = 0;
     return async (label) => {
+        const supplied = deps.secret?.(label);
+        if (supplied !== undefined && supplied.length > 0)
+            return supplied;
         const cached = deps.cache?.get(label);
         if (cached !== undefined)
             return cached;
         const fallback = heuristicFillValue(label);
-        if (deps.generator === undefined || !needsGeneration(label) || MAX_PER_DRIVE <= spent)
+        const { openai, generator } = deps;
+        if ((openai === undefined && generator === undefined) ||
+            !needsGeneration(label) ||
+            MAX_PER_DRIVE <= spent)
             return fallback;
         spent += 1;
-        const generated = await generateOne(deps.generator, label, deps.context?.() ?? '');
+        const context = deps.context?.() ?? '';
+        const generated = openai !== undefined
+            ? await generateWithOpenAi(openai, label, context)
+            : generator !== undefined
+                ? await generateOne(generator, label, context)
+                : undefined;
         if (generated === undefined)
             return fallback;
         // Cached under the LABEL, not the ref: refs expire with the page, labels are what the next drive

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

@@ -21,7 +21,7 @@
  * exist because this product is the verdict, and a verdict sourced from a model's confidence is the
  * thing Reticle sells the absence of.
  */
-import { RETICLE_URL_PARAM, ReticleEnv, ReticleTool, apiKeyFrom, asRecord, parseInteractive, } from '@reticlehq/core';
+import { RETICLE_URL_PARAM, ReticleEnv, ReticleTool, platformCredentialFrom, asRecord, parseInteractive, } from '@reticlehq/core';
 import { FINISH_TOOL } from './harness.js';
 import { heuristicFillValue } from './fill-values.js';
 export const DEFAULT_JEV_MODEL = 'jev-latest';
@@ -55,12 +55,15 @@ const Tool = {
     RECORD: ReticleTool.RECORD,
     FLOW_SAVE: ReticleTool.FLOW_SAVE,
     FLOW_REPLAY: ReticleTool.FLOW_REPLAY,
+    NAVIGATE: ReticleTool.NAVIGATE,
     FINISH: FINISH_TOOL.name,
 };
 /** The synthetic option meaning "stop driving". Not a tool arg — a key in the choice set. */
 const FINISH_OPTION = 'finish';
 /** The synthetic option meaning "I cannot tell from this page; look again". */
 const RELOOK_OPTION = 'look_again';
+/** Back to the page before this one — a dead end used to end the whole drive where it stood. */
+const BACK_OPTION = 'go_back';
 /**
  * Tools the model may route to, beyond acting on a control.
  *
@@ -244,14 +247,11 @@ export function jevOptionsFromEnv(env) {
         };
     }
     // The ordinary path: the key the user minted on the platform, against the platform's own proxy.
-    // Reticle never ships a Jev key, so without a base URL to send it to this is not a usable driver.
-    const cloudKey = apiKeyFrom(env);
-    const cloudUrl = env[ReticleEnv.CLOUD_URL];
-    if (cloudKey === undefined || 0 === cloudKey.length)
+    // Reticle never ships a Jev key; the URL is the configured platform, else the hosted service.
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
-    if (cloudUrl === undefined || 0 === cloudUrl.length)
-        return undefined;
-    return { apiKey: cloudKey, baseUrl: cloudUrl };
+    return { apiKey: cloud.apiKey, baseUrl: cloud.url };
 }
 /** Strip the snapshot's list marker, so a description reads as a phrase rather than a bullet. */
 function cleanDesc(desc) {
@@ -287,6 +287,8 @@ function readState(history) {
         saved: [],
         tree: undefined,
         route: undefined,
+        pages: [],
+        proved: [],
         replayed: [],
         acted: [],
         blocked: [],
@@ -333,13 +335,22 @@ function readState(history) {
                 if ('string' === typeof tree)
                     state.tree = tree;
                 const route = asRecord(result['status'])['route'];
-                if ('string' === typeof route)
+                if ('string' === typeof route) {
                     state.route = appRoute(route);
+                    if (state.pages.at(-1) !== route)
+                        state.pages.push(route);
+                }
             }
+            if (Tool.NAVIGATE === outcome.name)
+                state.tree = undefined;
             if (Tool.ACT_AND_WAIT === outcome.name) {
                 const ref = asRecord(outcome.args)['ref'];
                 const failure = asRecord(outcome.result)['error'];
                 const refused = outcome.isError && 'string' === typeof failure && failure.includes(DANGEROUS_ARG);
+                const until = asRecord(asRecord(outcome.args)['until']);
+                const signal = until['name'];
+                if ('yes' === asRecord(outcome.result)['verified'] && 'string' === typeof signal)
+                    state.proved.push(signal);
                 if ('string' === typeof ref) {
                     // A refused act never happened, so it is not something this drive has driven. Recording
                     // it as driven would retire the control after an attempt that never reached the app.
@@ -550,7 +561,7 @@ export function jevDriver(options) {
             // ── the one real decision ────────────────────────────────────────────────────────────────
             // What the drive is currently for: the first plan step that is not a replay. Replays are all
             // done by the time we reach here, so whatever is left is the intent nobody has proved.
-            const objective = plan.find((step) => PLAN_REPLAY !== step.kind);
+            const objective = plan.find((step) => PLAN_REPLAY !== step.kind && !drive.proved.includes(step.target));
             const candidates = candidatesFrom(drive.tree);
             /**
              * A page with nothing to act on ends the DRIVE, not just the journey.
@@ -567,11 +578,15 @@ export function jevDriver(options) {
                 return only(request(Tool.RECORD, { action: 'stop', recordingName: drive.open.name }), 'nothing interactive on this page; wind up');
             }
             const criteria = {
-                [FINISH_OPTION]: 'Stop driving: the app has been covered, or nothing here leads anywhere new.',
+                [FINISH_OPTION]: 'Stop driving: every journey started here reached its end state, or nothing leads anywhere new.',
                 [RELOOK_OPTION]: 'Look at the page again without acting, because this reading looks incomplete.',
                 [OBSERVE_OPTION]: 'Read what the application DID since the last action — the requests it made and what it logged. Choose this when something was driven and it is not yet clear whether it worked.',
                 [STATE_OPTION]: "Read the application's own state, which is the strongest evidence there is and the one thing a screen cannot fake.",
             };
+            const previous = drive.pages.at(-2);
+            if (previous !== undefined)
+                criteria[BACK_OPTION] =
+                    `Go back to ${previous}: this page is a dead end, or a journey started there is not finished.`;
             for (const candidate of candidates) {
                 const verb = actionFor(candidate.role);
                 const already = drive.acted.includes(candidate.ref) ? ' (already driven once)' : '';
@@ -580,12 +595,12 @@ export function jevDriver(options) {
             const response = await callJev({ apiKey: options.apiKey, model, baseUrl, path, doFetch }, buildState(input.system, input.history, drive, objective), {
                 next_action: {
                     type: 'choice',
-                    instructions: 'Which single action best advances coverage of this application right now? Prefer a control that completes a real user journey, and prefer something not already driven.',
+                    instructions: 'Which single action carries the current user journey forward toward its END state — a submitted form, a saved record, a confirmation? Finish the journey this page started before opening a new one; prefer something not already driven only once it is finished.',
                     criteria,
                 },
                 journey_complete: {
                     type: 'noul',
-                    instructions: 'The application has been meaningfully covered by the actions driven so far, and further clicking would add nothing.',
+                    instructions: 'Every journey started so far has been carried to its end state and checked there, and further driving would add nothing.',
                 },
             });
             const usage = {
@@ -602,6 +617,8 @@ export function jevDriver(options) {
             }
             if (RELOOK_OPTION === chosen)
                 return only(request(Tool.SNAPSHOT, { mode: 'interactive' }), 'look again', usage);
+            if (BACK_OPTION === chosen && previous !== undefined)
+                return only(request(Tool.NAVIGATE, { url: previous }), `back to ${previous}`, usage);
             // Routing to a READ rather than an action. Neither changes the app, so neither is recorded as
             // something driven — they are how the drive finds out whether what it drove worked.
             if (OBSERVE_OPTION === chosen)

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

@@ -42,5 +42,17 @@ export interface OpenAiDriverOptions {
  * OpenAI key, which is the entire point of the proxy.
  */
 export declare function openAiOptionsFromEnv(env: Record<string, string | undefined>): OpenAiDriverOptions | undefined;
+/**
+ * Where a Chat Completions call goes. 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.
+ */
+export declare function openAiCompletionsUrl(options: Pick<OpenAiDriverOptions, 'baseUrl'>): string;
+/**
+ * The small GPT models refuse function tools on Chat Completions while reasoning is on: measured,
+ * `gpt-5.6-luna` answers 400 to the first request that carries tools. A driving turn is a choice,
+ * not a plan, so no hidden reasoning is also the right depth and the cheapest one.
+ */
+export declare const OPENAI_REASONING_EFFORT = "none";
 /** Build a driver backed by Chat Completions. */
 export declare function openAiDriver(options: OpenAiDriverOptions): ModelDriver;

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

@@ -17,7 +17,7 @@
  * it is reported below so the number is visible rather than assumed.
  */
 import { z } from 'zod';
-import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+import { ReticleEnv, platformCredentialFrom } from '@reticlehq/core';
 /**
  * The default model.
  *
@@ -71,13 +71,10 @@ export function openAiOptionsFromEnv(env) {
     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)
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
-    if (cloudUrl === undefined || 0 === cloudUrl.length)
-        return undefined;
-    return withModel({ apiKey: cloudKey, baseUrl: cloudUrl });
+    return withModel({ apiKey: cloud.apiKey, baseUrl: cloud.url });
 }
 function toWireTool(tool) {
     return {
@@ -142,17 +139,28 @@ function parseArgs(raw) {
         return {};
     }
 }
+/**
+ * Where a Chat Completions call goes. 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.
+ */
+export function openAiCompletionsUrl(options) {
+    const baseUrl = options.baseUrl ?? DEFAULT_OPENAI_BASE_URL;
+    return `${baseUrl}${DEFAULT_OPENAI_BASE_URL === baseUrl ? OPENAI_PATH : PLATFORM_PATH}`;
+}
+/**
+ * The small GPT models refuse function tools on Chat Completions while reasoning is on: measured,
+ * `gpt-5.6-luna` answers 400 to the first request that carries tools. A driving turn is a choice,
+ * not a plan, so no hidden reasoning is also the right depth and the cheapest one.
+ */
+export const OPENAI_REASONING_EFFORT = 'none';
 /** 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}`, {
+            const response = await doFetch(openAiCompletionsUrl(options), {
                 method: 'POST',
                 headers: {
                     'content-type': 'application/json',
@@ -161,6 +169,7 @@ export function openAiDriver(options) {
                 body: JSON.stringify({
                     model,
                     max_completion_tokens: MAX_TOKENS,
+                    reasoning_effort: OPENAI_REASONING_EFFORT,
                     tools: input.tools.map(toWireTool),
                     messages: [{ role: 'system', content: input.system }, ...toWireMessages(input.history)],
                 }),

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

@@ -16,7 +16,7 @@
  *   - 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';
+import { platformCredentialFrom } from '@reticlehq/core';
 const CONFIG_PATH = '/v1/model/config';
 /**
  * How long the daemon will wait for a preference before driving without it.
@@ -68,12 +68,11 @@ function parse(body) {
  * 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)
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
+    const key = cloud.apiKey;
+    const host = cloud.url;
     const controller = new AbortController();
     const timer = setTimeout(() => {
         controller.abort();

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

@@ -39,14 +39,14 @@ declare const LicensePayloadSchema: z.ZodObject<{
     exp: z.ZodNumber;
     features: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
-    lid: string;
     org: string;
+    lid: string;
     plan: string;
     exp: number;
     features?: string[] | undefined;
 }, {
-    lid: string;
     org: string;
+    lid: string;
     plan: string;
     exp: number;
     features?: string[] | undefined;

package/dist/index.d.ts

@@ -15,6 +15,15 @@ export type { ToolDeps, ToolDef } from './surface/tools/tools.js';
 export { createToolInvoker, UNKNOWN_TOOL_ERROR } from './surface/tools/tool-invoker.js';
 export { runTool, SESSION_BOUND_TOOLS, SESSION_EXEMPT_TOOLS } from './surface/tools/invoke-tool.js';
 export type { ToolInvoker } from './surface/tools/tool-invoker.js';
+/**
+ * The port-presence check the CLI commands (`drive`, `verify`, `status`, `doctor`, `kill`) all share,
+ * re-exported so a consumer embedding `start()` in its own process can refuse a taken port the same
+ * honest way instead of letting a raw `EADDRINUSE` stack out — the gap `@reticlehq/test`'s
+ * `bootSession()` had (reticlehq/reticle#1141): it called `start()` directly with no pre-flight probe.
+ */
+export { probePresence, describePresence, PortPresence, } from './command/daemon/binding/port-presence.js';
+export { probeDaemon } from './surface/mcp/proxy/proxy-daemon-probe.js';
+export { fetchStatus } from './command/daemon/binding/daemon-status-probe.js';
 export { BaselineStore, normalizeLines, diffLines } from './memory/project/baselines.js';
 export { RecordingStore } from './language/flows/recording/tape/recordings.js';
 export type { RecordedStep, CompiledProgram } from './language/flows/recording/tape/recordings.js';