@reticlehq/server 3.1.0 → 3.3.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,62 @@
+/**
+ * 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;
+    /**
+     * Whether the platform actually holds a key for the provider this project is pointed at.
+     *
+     * Entitlement and readiness are different facts and the HUD needs both. A workspace can be fully
+     * entitled -- claimed period, `harnessEnabled` on -- against a deployment that has no provider key
+     * configured, and every signal then reads healthy while a drive cannot run. Absent reads as READY,
+     * on the same rule as the two booleans above: an older API that does not report availability must
+     * not have its silence treated as a refusal.
+     */
+    providerReady: 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,97 @@
+/**
+ * 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'];
+        // `available` is keyed by provider and says which ones the platform holds a key for. Read only
+        // the entry for the provider this project uses: another provider being configured says nothing
+        // about whether THIS one can drive.
+        const available = record['available'];
+        const ready = 'object' === typeof available && null !== available
+            ? available[provider]
+            : undefined;
+        return {
+            provider,
+            harnessEnabled: 'boolean' === typeof enabled ? enabled : true,
+            harnessEntitled: 'boolean' === typeof entitled ? entitled : true,
+            providerReady: 'boolean' === typeof ready ? ready : 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/visual/visual-tools.js

@@ -6,6 +6,21 @@ import { ratioSchema } from '../../surface/tools/args/numeric-bounds.js';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { diffPng } from './visual-diff.js';
 import { VisualStore } from './visual-store.js';
+/**
+ * The `.reticle` a capture belongs beside: the driven session's own, stamped when it connected.
+ *
+ * Falls back to the daemon's root only when there is no session to ask — the same fallback the
+ * journal and the run artifact use, and for the same reason: a picture of somebody's app has no
+ * business in a directory that has nothing to do with it.
+ */
+function captureRoot(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).artifactRoot ?? deps.reticleRoot;
+    }
+    catch {
+        return deps.reticleRoot;
+    }
+}
 import { trackCaptureDirectory } from './capture-cleanup.js';
 import { readFile, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -253,7 +268,16 @@ export const VISUAL_TOOLS = [
                 return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
             }
             const name = asString(args['name']) ?? 'default';
-            const store = new VisualStore(deps.fs, deps.reticleRoot);
+            // Beside the app that was captured. The tool RETURNS this path to the agent, so a wrong root
+            // is not only a stray PNG — it is a path the agent is told to look at in a tree that has
+            // nothing to do with the screenshot.
+            //
+            // Taken from the SESSION's own stamp rather than re-resolved, which is what `attach-journal`
+            // and the run artifact already do: the capture came from that session, so the answer is
+            // already in hand, and a second resolution is a second chance to disagree. It also keeps this
+            // directory from reaching into `project` for an address it was deliberately freed from
+            // needing — see `directory-reach`.
+            const store = new VisualStore(deps.fs, captureRoot(deps, sessionId));
             // Scoped to the runtime that produced it: an Electron window, a Tauri webview and a browser
             // tab do not render the same url the same way, and one shared baseline makes every
             // cross-runtime diff wrong. See visualDir.
@@ -292,7 +316,7 @@ export const VISUAL_TOOLS = [
         },
         handler: async (deps, args) => {
             const baseline = asString(args['baseline']) ?? '';
-            const store = new VisualStore(deps.fs, deps.reticleRoot);
+            const store = new VisualStore(deps.fs, captureRoot(deps, asString(args['sessionId'])));
             // Capture FIRST, then fetch the baseline for the runtime that produced these pixels. Reading it
             // by the session's runtime looked equivalent and is not: the route decides the renderer, so a
             // desktop session captured through a driven browser must be compared against the WEB baseline,

package/dist/index.d.ts

@@ -21,7 +21,7 @@ export type { RecordedStep, CompiledProgram } from './language/flows/recording/t
 export { FlowStore, recordedStepToFlowStep } from './language/flows/flows.js';
 export type { FlowResult } from './language/flows/flows.js';
 export type { Clock } from './machine/clock.js';
-export { assertSuccess, successToPredicate, dynamicTestids, successLabel, } from './language/flows/flow-success.js';
+export { assertSuccess, dynamicTestids, successLabel, successToPredicate, } from './language/flows/flow-success.js';
 export { classifyFlowAssertions, FlowAssertionGrade } from './language/flows/flow-classify.js';
 export type { FlowAssertionClassification } from './language/flows/flow-classify.js';
 export { buildDomainModel } from './judgement/domain/domain-model.js';