@reticlehq/server 3.4.0 → 3.6.0

package/dist/features/harness/driver.js

@@ -1,236 +0,0 @@
-/**
- * The model binding: the one file in the harness that knows there is a network.
- *
- * Everything about the loop lives in harness.ts against the `ModelDriver` interface, so this file is
- * a translation layer and nothing else. That split is not tidiness — it is what lets the loop be
- * tested against a scripted model with no API key, on every run of the unit gate.
- *
- * It speaks the Messages API over `fetch` rather than through a vendor SDK. The loop is ours (the
- * harness owns the step budget and has to record every call even when a run is cut short), so an SDK
- * would contribute one HTTP POST and a dependency — and this package's dependency list is short on
- * purpose.
- */
-import { z } from 'zod';
-import { ReticleEnv, platformCredentialFrom } from '@reticlehq/core';
-/**
- * The default driver model.
- *
- * Deliberately not the largest model available. The harness is not reasoning about business logic; it
- * is exploring an interface and stating consequences, and the verdict is produced by the engine
- * reading what it drove. If finding defects required a frontier model HERE, the engine would not be
- * doing its job — so the model tier is also a standing test of the design.
- */
-export const DEFAULT_HARNESS_MODEL = 'claude-sonnet-5';
-export const DEFAULT_HARNESS_BASE_URL = 'https://api.anthropic.com';
-/** Output cap per turn. A driving turn is a sentence and a tool call, never an essay. */
-const MAX_TOKENS = 4096;
-const ANTHROPIC_VERSION = '2023-06-01';
-const MESSAGES_PATH = '/v1/messages';
-/**
- * How much of one tool result the model is allowed to see.
- *
- * A snapshot of a dense page or a network window on a busy app is far larger than anything the model
- * needs to choose its next click, and a handful of them will fill a context window that then has to
- * be paid for on every subsequent turn. Truncation is announced in the payload rather than silent,
- * because a model that cannot tell it was given a partial reading will reason about it as a complete
- * one — and the tools already have cheaper lenses (`count_only`, `interactive`, `diff`) for exactly
- * this. The full result is in the journal either way; nothing is lost from the record.
- */
-const MAX_RESULT_CHARS = 8000;
-/** The cache breakpoint marker. One object, because it is the same fact in three places. */
-const CACHE_BREAKPOINT = { type: 'ephemeral' };
-/** What one turn of the wire looks like, narrowed at the boundary rather than trusted. */
-const TextBlock = z.object({ type: z.literal('text'), text: z.string() });
-const ToolUseBlock = z.object({
-    type: z.literal('tool_use'),
-    id: z.string(),
-    name: z.string(),
-    input: z.unknown(),
-});
-const OtherBlock = z.object({ type: z.string() }).passthrough();
-const MessageResponse = z.object({
-    content: z.array(z.union([TextBlock, ToolUseBlock, OtherBlock])).default([]),
-    usage: z
-        .object({
-        input_tokens: z.number().default(0),
-        output_tokens: z.number().default(0),
-        cache_read_input_tokens: z.number().nullish(),
-        cache_creation_input_tokens: z.number().nullish(),
-    })
-        .default({ input_tokens: 0, output_tokens: 0 }),
-});
-/**
- * Read the harness's configuration out of the environment.
- *
- * Returns `undefined` when there is no key, which is the ONLY thing that decides whether the harness
- * is available. Stated as a read rather than a throw because "you have not configured this" is a
- * routine answer a caller offers a way out of, not a failure.
- */
-export function harnessOptionsFromEnv(env) {
-    const model = env[ReticleEnv.HARNESS_MODEL];
-    const baseUrl = env[ReticleEnv.HARNESS_BASE_URL];
-    const withOptions = (apiKey, fallbackUrl) => {
-        const url = baseUrl === undefined || 0 === baseUrl.length ? fallbackUrl : baseUrl;
-        return {
-            apiKey,
-            ...(model === undefined || 0 === model.length ? {} : { model }),
-            ...(url === undefined || 0 === url.length ? {} : { baseUrl: url }),
-        };
-    };
-    const apiKey = env[ReticleEnv.HARNESS_KEY];
-    if (apiKey !== undefined && 0 < apiKey.length)
-        return withOptions(apiKey);
-    /**
-     * The platform key, against the platform.
-     *
-     * Reticle's own service answers the Messages API at `/v1/messages` and forwards with ITS provider
-     * key, so a user who has run `reticle link` can drive with a frontier model having never held an
-     * Anthropic key at all. Without this they would be told to set `ANTHROPIC_API_KEY` to a value
-     * beginning `rk_live_` — which works, and reads like a mistake, and is the sort of instruction
-     * people correct on the way past and then cannot explain why nothing runs.
-     *
-     * An explicit `ANTHROPIC_API_KEY` still wins: someone who exported one meant it.
-     */
-    const cloud = platformCredentialFrom(env);
-    if (cloud === undefined)
-        return undefined;
-    return withOptions(cloud.apiKey, cloud.url);
-}
-/** Build a driver backed by the Messages API. */
-export function harnessDriver(options) {
-    const model = options.model ?? DEFAULT_HARNESS_MODEL;
-    const baseUrl = options.baseUrl ?? DEFAULT_HARNESS_BASE_URL;
-    const call = options.fetch ?? ((url, init) => fetch(url, init));
-    return {
-        async turn({ system, tools, history }) {
-            const response = await call(`${baseUrl}${MESSAGES_PATH}`, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    'x-api-key': options.apiKey,
-                    'anthropic-version': ANTHROPIC_VERSION,
-                },
-                body: JSON.stringify({
-                    model,
-                    max_tokens: MAX_TOKENS,
-                    system: [
-                        {
-                            type: 'text',
-                            text: system,
-                            // The system prompt and the tool list are byte-identical on every turn of a drive, and
-                            // a drive is dozens of turns. Caching the prefix is most of the cost of driving an app.
-                            cache_control: CACHE_BREAKPOINT,
-                        },
-                    ],
-                    tools: tools.map(toWireTool),
-                    messages: withConversationCache(history.map(toWireMessage)),
-                }),
-            });
-            const body = await response.text();
-            if (!response.ok) {
-                // Thrown, not returned: the loop calls a model that will not answer a BROKEN drive, and a
-                // broken drive is never reported as clean. Swallowing this would be a verdict about an app
-                // nobody drove.
-                throw new Error(`the model refused the request (HTTP ${String(response.status)}): ${body}`);
-            }
-            const parsed = MessageResponse.parse(JSON.parse(body));
-            const text = parsed.content
-                .filter((block) => 'text' === block.type)
-                .map((block) => block.text)
-                .join('\n');
-            const calls = parsed.content
-                .filter((block) => 'tool_use' === block.type)
-                .map((block) => ({
-                id: block.id,
-                name: block.name,
-                args: isRecord(block.input) ? block.input : {},
-            }));
-            return {
-                text,
-                calls,
-                usage: {
-                    input: parsed.usage.input_tokens,
-                    output: parsed.usage.output_tokens,
-                    // Reported so a missed cache is VISIBLE. A breakpoint that silently stops matching costs
-                    // full price and looks exactly like one that is working from every other angle.
-                    cacheRead: parsed.usage.cache_read_input_tokens ?? 0,
-                    cacheWrite: parsed.usage.cache_creation_input_tokens ?? 0,
-                },
-            };
-        },
-    };
-}
-/**
- * Cache the conversation so far, so the next turn does not pay to re-read it.
- *
- * The API is stateless: every turn re-sends the whole conversation, and a drive is dozens of turns.
- * The system prompt and the tool list are already cached from the first turn — but those are the half
- * that does not grow. The messages are the half that does, and without a breakpoint every byte of
- * them is processed again at full price on every single turn.
- *
- * ONE breakpoint, on the last content block of the most-recently-appended turn. Next turn, this
- * entire conversation is the request's prefix, so it is read at roughly a tenth of the input price
- * rather than processed again. Earlier entries stay valid read points, so the saving accrues as the
- * conversation grows — which is exactly the shape of the cost.
- *
- * Not several breakpoints: four is the hard limit per request and the system block already spends
- * one. More here would buy nothing, because the lookup from a later breakpoint already finds the
- * earlier turn's entry as its prefix.
- *
- * The one thing that would break it is a single turn adding more than twenty content blocks — the
- * lookback window is twenty, and a breakpoint that cannot see the previous entry silently misses. A
- * turn here is one text block, N tool_use blocks and N tool_result blocks, so it would take ten
- * parallel calls in one turn to reach that. Worth knowing; not worth a second breakpoint until it
- * happens, and the cache-read count in `usage` is where it would show up.
- */
-function withConversationCache(messages) {
-    const last = messages[messages.length - 1];
-    if (last === undefined)
-        return [...messages];
-    const content = last.content.map((block, index) => index === last.content.length - 1 ? { ...block, cache_control: CACHE_BREAKPOINT } : block);
-    return [...messages.slice(0, -1), { ...last, content }];
-}
-function toWireTool(tool) {
-    return {
-        name: tool.name,
-        description: tool.description,
-        input_schema: tool.inputSchema,
-    };
-}
-function toWireMessage(entry) {
-    if ('user' === entry.role) {
-        // A text BLOCK rather than a bare string: only a block can carry a cache breakpoint, and the
-        // opening message is the one that would otherwise be a string. It changes the billing and
-        // nothing the model reads.
-        return { role: 'user', content: [{ type: 'text', text: entry.text }] };
-    }
-    if ('assistant' === entry.role) {
-        const blocks = [];
-        if (entry.text.length > 0)
-            blocks.push({ type: 'text', text: entry.text });
-        for (const call of entry.calls) {
-            blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.args });
-        }
-        return { role: 'assistant', content: blocks };
-    }
-    // Every outcome goes back in ONE user message. Splitting tool results across messages teaches the
-    // model to stop asking for calls in parallel, which is most of what makes a drive fast.
-    return {
-        role: 'user',
-        content: entry.outcomes.map((outcome) => ({
-            type: 'tool_result',
-            tool_use_id: outcome.id,
-            content: truncate(JSON.stringify(outcome.result ?? null)),
-            is_error: outcome.isError,
-        })),
-    };
-}
-function truncate(text) {
-    if (text.length <= MAX_RESULT_CHARS)
-        return text;
-    const dropped = String(text.length - MAX_RESULT_CHARS);
-    return `${text.slice(0, MAX_RESULT_CHARS)}\n…[truncated ${dropped} characters — ask for a narrower lens (count_only, interactive, diff, or a path) if you need the rest]`;
-}
-function isRecord(value) {
-    return 'object' === typeof value && null !== value && !Array.isArray(value);
-}

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

@@ -1,188 +0,0 @@
-/**
- * A harness driver with no text generator in it.
- *
- * `driver.ts` binds the harness to a frontier model, and the comment at the top of it has always
- * claimed the tier is "a standing test of the design": the driver is not reasoning about business
- * logic, it is choosing what to touch next and saying what it expects, and if that needed a large
- * model then the engine would not be doing its job. Nothing tested the claim, because the only
- * driver in the repo was a large model.
- *
- * This is the test. Jev is a System One model — it evaluates typed questions against a state and
- * answers with probabilities, in one parallel pass, and it does not emit prose. It therefore cannot
- * invent a tool call. So every call this driver makes is built HERE, deterministically, out of what
- * the page actually offers, and the model's only contribution is picking one of them. That is a
- * strictly smaller surface than a generating driver has, and it is the whole reason this is worth
- * having: a driver that cannot name an element that is not on the page cannot hallucinate one.
- *
- * What did NOT move: the verdict. `decideVerified` still decides, on evidence, with no model in it.
- * A System One model cannot hallucinate a type, but it still returns a PROBABILITY, and a
- * probability is not proof. Anyone reading this file as an invitation to let Jev answer
- * "did it work?" should read `engine/src/evidence/verified.ts` first — the seventeen clauses there
- * 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 type { ModelDriver } from './harness.js';
-import type { HarnessFetch } from './driver.js';
-export declare const DEFAULT_JEV_MODEL = "jev-latest";
-export declare const DEFAULT_JEV_BASE_URL = "https://api.typesafe.ai";
-/**
- * The consequences the driver can declare, and the predicate each one becomes.
- *
- * Declaring one is not optional decoration — it is the difference between a drive and a click. The
- * first version of this driver emitted `act_and_wait` with no `until` at all, and the engine said
- * so in every single result: "the page settled and no channel reported a problem, but nothing was
- * declared to prove — this is not verification". Six actions, zero proved. A flow recorded from that
- * drive passes even when the feature is broken, which is the exact failure this product exists to
- * catch, sitting inside the thing meant to catch it.
- *
- * Every predicate here is BARE — a kind with no specifics — because before acting the driver does
- * not know which endpoint, signal or route to expect. Bare is still consequence-grade evidence: it
- * asserts the app's own machinery moved, which a presence check on screen text does not.
- *
- * Only SIGNAL and NET can be declared bare, and that is a fact about the engine rather than a
- * preference. `engine/src/evidence/already-true.ts` lists the kinds that read live state — element,
- * text, route and state — and those are checked BEFORE the action as well as after, precisely so a
- * condition that already held cannot be sold as something the action caused. A bare predicate of
- * one of those kinds is unconditionally true: there is always a current route, and there is always
- * some store. That file says so in as many words at its `ROUTE` case.
- *
- * This driver tried all four anyway and the engine refused all four, every time, with
- * `already_true` — "the declared consequence was already true before this action, so it proves
- * nothing about it". Signal and net are event-based and floored at the act's own cursor, so they
- * cannot be answered by the past, which is exactly what makes them safe to declare with no
- * specifics. Route and state come back the moment the driver can name a pathname or a store path
- * instead of a bare kind, and they are the stronger evidence when it can.
- *
- * `anyOf` is not a loophole: it reports as live-reading if ANY branch does, so it holds only the
- * two safe kinds for the same reason.
- *
- * ponytail: bare `net` can in principle be satisfied by unrelated traffic inside the action's
- * window — a page polling every second would answer for a button that did nothing. The window is
- * the action's own, not "ever", so the exposure is small but real. The upgrade is to learn the
- * app's vocabulary first (one `reticle_observe` early in the drive gives the actual signal names
- * and endpoint paths) and declare `urlContains`/`name` instead of a bare kind. Until then `state`
- * and `signal` are the trustworthy ones and `net` is the one to distrust on a chatty app.
- */
-export interface Consequence {
-    predicate: Record<string, unknown>;
-    describes: string;
-    /**
-     * Whether a SAVED FLOW can carry this claim, which is a different question from whether the drive
-     * can prove it.
-     *
-     * A recorded step keeps an expectation only in the forms a replay can re-check, and that filter
-     * refuses every unbound kind: `signal "export:generated"` survives, a bare "some signal fires"
-     * does not; `net { method: "POST" }` survives, a bare "some request happens" does not; `not` and
-     * `anyOf` have no representation at all.
-     *
-     * Measured on a real dashboard before this field existed: every one of the four consequences on
-     * offer was unbound, so 0 of 22 steps across 16 machine-driven flows recorded a single
-     * expectation, against 211 of 419 in the hand-authored flows beside them. The drive proved things
-     * and then saved flows that had forgotten all of it. Since a flow is meant to BE the regression
-     * suite, that is the product's own claim failing at its last step: those flows can only ever
-     * catch "the click stopped landing", never "the feature broke".
-     */
-    recordable: boolean;
-}
-/**
- * The app's own route, with Reticle's fingerprints wiped off it.
- *
- * A pooled launcher appends `__reticle_opened=1` to the URL it opens, and that parameter ended up
- * inside a declared consequence: "this click leaves a route containing /?__reticle_opened=1". On a
- * hash-routed app that claim can never hold, because the query string never changes -- only the
- * fragment does -- so every navigation link was a guaranteed red, and the red was about OUR query
- * parameter rather than about the application. Found by making a failed action say what it claimed;
- * before that it read as an ordinary "the declared consequence did not hold".
- *
- * The fragment is kept, and is the point: on a hash-routed app it is the only part that moves.
- */
-export declare function appRoute(route: string): string;
-/**
- * The consequences on offer, given where the app currently is and what it says it can do.
- *
- * Two things shape this list, and the second one was missing for a whole release.
- *
- * It is a function of the CURRENT ROUTE, because "this takes us off the page we are on" is only
- * falsifiable against a route actually read.
- *
- * It is also a function of the app's OWN VOCABULARY, because an unbound claim cannot be saved. A
- * drive that declares "some signal fires" proves something real at the time and writes a flow that
- * asserts nothing, so every later replay passes as long as the clicks still land. Offering the
- * declared signal NAMES turns the same choice into one a flow can keep, and costs nothing extra:
- * the names are already read out of `.reticle` to build the plan.
- */
-export declare function consequencesFor(route: string | undefined, vocabulary?: readonly string[]): Record<string, Consequence>;
-/**
- * One step of the plan the caller built from `.reticle`.
- *
- * Structural rather than imported: this package is a SINK — it is handed a toolset and a driver and
- * reaches into nothing — so the plan arrives as data with the shape it needs and no dependency on
- * where it was built.
- */
-export interface DrivePlanStep {
-    /** `replay` for a journey already recorded, `drive` for declared intent nobody has proved. */
-    kind: string;
-    /** The flow to replay, or the signal/control a drive step is aimed at. */
-    target: string;
-    /** Why this step is worth taking, in the project's own words. */
-    why: string;
-}
-export interface JevDriverOptions {
-    apiKey: string;
-    model?: string;
-    baseUrl?: string;
-    /**
-     * The loop's step budget, so the driver can stop exploring in time to save what it drove.
-     *
-     * The loop does not tell a driver how much budget is left — it does not have to, because a
-     * generating model is expected to call `finish` when it is ready. This driver has a teardown it
-     * must reach, so it needs the number. Absent ⇒ no reserve, and a run that ends on BUDGET keeps
-     * nothing, which is why every caller inside the repo passes it.
-     */
-    maxSteps?: number;
-    /**
-     * What this drive is FOR, read from `.reticle` before it started.
-     *
-     * Replay steps run FIRST and deterministically, with no model call at all — a journey already on
-     * disk must never be re-driven, which is the whole reason the plan exists. Only once they are
-     * done is the model asked anything, and then it is asked against the intent these steps carry
-     * rather than against whatever happens to be on the page.
-     */
-    plan?: readonly DrivePlanStep[];
-    /**
-     * The signal names the app declares, untested ones first, read out of `.reticle` with the plan.
-     *
-     * Offered as consequences so a declaration can name something. Absent is not a failure: the
-     * method-bound network consequences are still recordable, and an app that declares no signals is
-     * simply an app with less to claim.
-     */
-    vocabulary?: readonly string[];
-    /**
-     * What to type into a text field, when the label alone is not enough to guess.
-     *
-     * The one place a drive is a COMPOSITION rather than a decision, and therefore the one place worth
-     * paying a generating model for. Absent ⇒ the label heuristic answers, which is what every drive
-     * did before this seam existed; a drive with no text fields never reaches it either way. See
-     * `fill-values.ts` for why it is escalation rather than a second model in the loop.
-     */
-    fillValue?: (label: string) => Promise<string>;
-    /** Injected for tests. Defaults to the platform `fetch`. */
-    fetch?: HarnessFetch;
-}
-/**
- * Read this driver's configuration out of the environment.
- *
- * A direct Jev key wins over the platform key, so that someone debugging the upstream is never
- * quietly talking to the proxy they were trying to bypass. Returns `undefined` when neither is set,
- * which is a routine answer and not a failure — the caller falls back to the Anthropic driver.
- */
-export declare function jevOptionsFromEnv(env: Record<string, string | undefined>): JevDriverOptions | undefined;
-/**
- * Build a driver backed by a System One model.
- *
- * Every turn emits exactly ONE call. The loop dispatches a turn's calls with `Promise.all`, so an
- * act and the snapshot that reads its result cannot be batched into one turn — they would race, and
- * the snapshot would describe a page mid-flight. One call per turn costs a step and buys a reading
- * that is actually of the page the action produced.
- */
-export declare function jevDriver(options: JevDriverOptions): ModelDriver;