@reticlehq/server 3.5.0 → 3.7.0

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

@@ -1,58 +0,0 @@
-/**
- * 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;
-/**
- * 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

@@ -1,206 +0,0 @@
-/**
- * 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, platformCredentialFrom } 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 cloud = platformCredentialFrom(env);
-    if (cloud === undefined)
-        return undefined;
-    return withModel({ apiKey: cloud.apiKey, baseUrl: cloud.url });
-}
-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 {};
-    }
-}
-/**
- * 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 doFetch = options.fetch ?? ((url, init) => fetch(url, init));
-    return {
-        async turn(input) {
-            const response = await doFetch(openAiCompletionsUrl(options), {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    authorization: `Bearer ${options.apiKey}`,
-                },
-                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)],
-                }),
-            });
-            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/judgement/hunt/hunt-report.d.ts

@@ -1,49 +0,0 @@
-/**
- * Aggregate many crawl runs into the one number the core claim needs.
- *
- * Detection already exists: `reticle_crawl` drives every reachable control and reports contradictions
- * — two channels disagreeing about the same click. It found `swallowed-500-login` and, separately,
- * `ui-advanced-request-failed` on a control whose assertion was green, neither of them planted.
- *
- * What was missing is the arithmetic that turns those into evidence. The claim worth making is not
- * "Reticle can find bugs"; it is:
- *
- *   "Run over N already-merged, already-green changes, it found X real bugs their own tests
- *    certified as passing."
- *
- * That needs no control arm, which is why it is the cheapest credible proof available: the
- * counterfactual is already established, because those changes SHIPPED. An A/B is the second study,
- * and this tells you where to point it.
- *
- * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
- * it across a commit range is a shell loop. This is only the part that must not be done by eye.
- */
-export interface HuntAnomaly {
-    kind: string;
-    ref?: string;
-    desc?: string;
-    detail?: string;
-}
-/** One crawl over one checkout. `label` is whatever identifies it — a commit sha, a PR number. */
-export interface HuntRun {
-    label: string;
-    anomalies: readonly HuntAnomaly[];
-    /** Controls actually driven. A run that drove nothing proves nothing and is reported separately. */
-    stepsRun?: number;
-}
-interface HuntSummary {
-    runs: number;
-    /** Runs that actually drove at least one control. The denominator that can honestly be quoted. */
-    runsWithCoverage: number;
-    /** Runs where at least one CONTRADICTION was found — the headline numerator. */
-    runsWithContradictions: number;
-    contradictions: number;
-    /** Single-channel faults (console errors, failed requests, dead controls). Context, not the claim. */
-    singleChannelFaults: number;
-    byKind: Record<string, number>;
-    /** Labels with contradictions, so each one can be confirmed by hand before it is counted. */
-    flagged: string[];
-    headline: string;
-}
-export declare function summarizeHunt(runs: readonly HuntRun[]): HuntSummary;
-export {};

package/dist/judgement/hunt/hunt-report.js

@@ -1,84 +0,0 @@
-/**
- * Aggregate many crawl runs into the one number the core claim needs.
- *
- * Detection already exists: `reticle_crawl` drives every reachable control and reports contradictions
- * — two channels disagreeing about the same click. It found `swallowed-500-login` and, separately,
- * `ui-advanced-request-failed` on a control whose assertion was green, neither of them planted.
- *
- * What was missing is the arithmetic that turns those into evidence. The claim worth making is not
- * "Reticle can find bugs"; it is:
- *
- *   "Run over N already-merged, already-green changes, it found X real bugs their own tests
- *    certified as passing."
- *
- * That needs no control arm, which is why it is the cheapest credible proof available: the
- * counterfactual is already established, because those changes SHIPPED. An A/B is the second study,
- * and this tells you where to point it.
- *
- * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
- * it across a commit range is a shell loop. This is only the part that must not be done by eye.
- */
-/** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
-const CONTRADICTION_KINDS = [
-    'ui-advanced-request-failed',
-    'signal-contradicted',
-    'response-ignored',
-    'duplicate-request',
-    'request-never-settled',
-    'failure-misattributed',
-];
-const isContradiction = (kind) => CONTRADICTION_KINDS.includes(kind);
-export function summarizeHunt(runs) {
-    const byKind = {};
-    const flagged = [];
-    let contradictions = 0;
-    let singleChannelFaults = 0;
-    let runsWithCoverage = 0;
-    for (const run of runs) {
-        // A run that drove nothing is not evidence of cleanliness. Counting it in the denominator would
-        // dilute the rate with checkouts where the app never even came up — the arithmetic equivalent of
-        // reporting a green because no test ran.
-        if ((run.stepsRun ?? 0) > 0)
-            runsWithCoverage += 1;
-        let flaggedThisRun = false;
-        for (const anomaly of run.anomalies) {
-            byKind[anomaly.kind] = (byKind[anomaly.kind] ?? 0) + 1;
-            if (isContradiction(anomaly.kind)) {
-                contradictions += 1;
-                flaggedThisRun = true;
-            }
-            else {
-                singleChannelFaults += 1;
-            }
-        }
-        if (flaggedThisRun)
-            flagged.push(run.label);
-    }
-    return {
-        runs: runs.length,
-        runsWithCoverage,
-        runsWithContradictions: flagged.length,
-        contradictions,
-        singleChannelFaults,
-        byKind,
-        flagged,
-        headline: buildHeadline(runsWithCoverage, flagged.length, contradictions),
-    };
-}
-/**
- * The sentence that goes in front of someone, phrased so it cannot overstate itself.
- *
- * It counts CHECKOUTS with a finding rather than raw findings, because one broken control clicked
- * five times is one bug and five anomalies. It also says "candidate": every flag still has to be
- * confirmed by hand before it is a bug, and a number that skips that step is the kind of evidence
- * this project exists to distrust.
- */
-function buildHeadline(withCoverage, flaggedRuns, contradictions) {
-    if (0 === withCoverage) {
-        return 'no run drove a single control — nothing was measured, which is not the same as nothing being wrong';
-    }
-    if (0 === flaggedRuns) {
-        return `${String(withCoverage)} merged changes crawled, no cross-channel contradictions found — confirm coverage was real before reading this as clean`;
-    }
-    return `${String(flaggedRuns)} of ${String(withCoverage)} merged, already-green changes carried a candidate false green (${String(contradictions)} contradictions) — each needs manual confirmation before it is counted`;
-}

package/dist/language/flows/buddy-status.d.ts

@@ -1,25 +0,0 @@
-/**
- * The buddy channel. The co-dev experience for the HUMAN: a single ambient line they can park in
- * a statusline or terminal and glance at — never a wall of output, never something they have to ask for.
- *
- * The rule this encodes: say the reassuring thing briefly and the alarming thing specifically. "41 flows
- * nominal" needs no detail; a deviation needs its name, because a status line that says only "1 deviation"
- * forces the human to go digging, which is exactly the work the buddy exists to remove.
- */
-interface BuddyStatusInput {
-    /** Every saved flow. */
-    total: number;
-    /** Flows with a passing artifact. */
-    passing: number;
-    /** Flows that changed files put at risk and that have NO passing artifact — the actionable set. */
-    deviations: readonly string[];
-    /** Flows quarantined as flaky — surfaced, never blocking. */
-    quarantined: readonly string[];
-}
-/**
- * One line, safe to print on every save. Shape:
- * `✓ 41 flows nominal`
- * `✗ 2 deviations: checkout, billing · 39 nominal · 1 flaky quarantined`
- */
-export declare function formatBuddyStatus(input: BuddyStatusInput): string;
-export {};

package/dist/language/flows/buddy-status.js

@@ -1,32 +0,0 @@
-/**
- * The buddy channel. The co-dev experience for the HUMAN: a single ambient line they can park in
- * a statusline or terminal and glance at — never a wall of output, never something they have to ask for.
- *
- * The rule this encodes: say the reassuring thing briefly and the alarming thing specifically. "41 flows
- * nominal" needs no detail; a deviation needs its name, because a status line that says only "1 deviation"
- * forces the human to go digging, which is exactly the work the buddy exists to remove.
- */
-/** How many deviation names to spell out before collapsing to a count (a status line must stay one line). */
-const MAX_NAMED = 2;
-/**
- * One line, safe to print on every save. Shape:
- * `✓ 41 flows nominal`
- * `✗ 2 deviations: checkout, billing · 39 nominal · 1 flaky quarantined`
- */
-export function formatBuddyStatus(input) {
-    const parts = [];
-    const deviations = input.deviations.length;
-    if (0 === deviations) {
-        parts.push(`✓ ${String(input.passing)}/${String(input.total)} flows nominal`);
-    }
-    else {
-        const named = input.deviations.slice(0, MAX_NAMED).join(', ');
-        const rest = deviations - Math.min(MAX_NAMED, deviations);
-        parts.push(`✗ ${String(deviations)} deviation${1 === deviations ? '' : 's'}: ${named}${rest > 0 ? ` +${String(rest)} more` : ''}`);
-        parts.push(`${String(input.passing)} nominal`);
-    }
-    if (input.quarantined.length > 0) {
-        parts.push(`${String(input.quarantined.length)} flaky quarantined`);
-    }
-    return parts.join(' · ');
-}

package/dist/language/flows/change/watch-batcher.d.ts

@@ -1,18 +0,0 @@
-/**
- * Debounce batcher for `reticle watch` — a save-heavy editor fires many change events per real edit
- * (temp files, multi-file formats-on-save). This coalesces a burst of changed paths into one flush after
- * a quiet window, so we compute affected flows once per edit, not per keystroke. The scheduler (setTimeout)
- * is injected, keeping the batching logic pure and unit-testable.
- */
-interface WatchBatcher {
-    onChange(file: string): void;
-}
-interface WatchBatcherOptions {
-    debounceMs: number;
-    /** Injected scheduler (setTimeout) — deterministic in tests. */
-    schedule: (fn: () => void, ms: number) => void;
-    /** Called once per quiet window with the unique changed paths since the last flush. */
-    onFlush: (files: string[]) => void;
-}
-export declare function createWatchBatcher(options: WatchBatcherOptions): WatchBatcher;
-export {};

package/dist/language/flows/change/watch-batcher.js

@@ -1,19 +0,0 @@
-export function createWatchBatcher(options) {
-    let pending = new Set();
-    let scheduled = false;
-    return {
-        onChange(file) {
-            pending.add(file);
-            if (scheduled)
-                return;
-            scheduled = true;
-            options.schedule(() => {
-                scheduled = false;
-                const files = [...pending];
-                pending = new Set();
-                if (files.length > 0)
-                    options.onFlush(files);
-            }, options.debounceMs);
-        },
-    };
-}

package/dist/memory/cloud/harness-offer.d.ts

@@ -1,44 +0,0 @@
-/**
- * Whether this workspace has taken the three months of free harness, read by the thing that would
- * advertise it.
- *
- * The HUD can only advertise honestly if it knows, and only the platform knows. This is the read —
- * filed beside the other reads of the linked account rather than with the harness itself, because
- * nothing that DRIVES needs it; the thing that needs it is the snapshot the HUD paints from. Same
- * shape as the harness's own `platform-config.ts` and for the same reasons: it is INFORMATION, not a
- * credential, so every failure answers `undefined`, which every caller must treat as "say nothing"
- * rather than as "not claimed". An offline laptop must not start advertising something the person
- * already owns.
- *
- * It is also SYNCHRONOUS at the point of use. The impact snapshot is built inline, dozens of times a
- * session, and the answer changes about once per workspace lifetime, so a cache that refreshes in
- * the background is the whole design: readers get what we last heard, and a stale answer is only
- * ever stale in the safe direction — the card the person is looking at is the one they can act on.
- */
-import { type HarnessOffer } from '@reticlehq/core';
-/** A GET, narrowed to what this file uses, so a test can answer it without a network. */
-export type OfferFetch = (url: string, init: {
-    method: string;
-    headers: Record<string, string>;
-    signal?: AbortSignal;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-    text(): Promise<string>;
-}>;
-/** Ask the platform where this workspace stands. `undefined` means "no answer", never "not claimed". */
-export declare function fetchHarnessOffer(env: Record<string, string | undefined>, claimUrl: string | undefined, doFetch?: OfferFetch, timeoutMs?: number): Promise<HarnessOffer | undefined>;
-/** What the impact snapshot reads: the last answer, with a refresh kicked off when it goes stale. */
-export interface OfferSource {
-    read(): HarnessOffer | undefined;
-}
-/**
- * A self-refreshing cache over the read above.
- *
- * Deliberately NOT a timer. A daemon that lives for days would otherwise hold an interval whose only
- * job is to re-ask a question nobody is asking, and it would have to be torn down in a place that
- * already has nine teardowns. Refreshing on a stale READ means the work only happens while somebody
- * is actually looking, and the first read of a process — which is always stale — starts the fetch
- * that the second read answers from.
- */
-export declare function harnessOfferSource(env: Record<string, string | undefined>, claimUrl: () => string | undefined, now?: () => number, load?: (claim: string | undefined) => Promise<HarnessOffer | undefined>): OfferSource;