@reticlehq/server 3.4.0 → 3.6.0

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

@@ -1,46 +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;
-/** Build a driver backed by Chat Completions. */
-export declare function openAiDriver(options: OpenAiDriverOptions): ModelDriver;

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

@@ -1,194 +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 {};
-    }
-}
-/** 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/memory/project/dir/fill-value-store.d.ts

@@ -1,32 +0,0 @@
-/**
- * The values a drive types into this project's fields, kept so they are paid for once.
- *
- * A generated field value is not a model's opinion to be re-asked every run. It is a FIXTURE: the
- * same label on the same app wants the same value tomorrow, a replay must send exactly what the
- * recording sent or it is not a replay, and a human who dislikes "Acme Corp" should be able to open
- * a file and write something else rather than argue with a model about it. So it lives beside the
- * flows it belongs to, in git, in the project's own directory.
- *
- * Read once at the start of a drive and written once at the end: a drive that fills twenty fields
- * must not write the file twenty times, and nothing else in the process is competing for it.
- *
- * Every failure is silent and answers "no values". A drive must never fail over a fixtures file,
- * and the fallback -- the label heuristic -- is what every drive used before this existed.
- */
-import type { FileSystemPort } from '../fs/fs-port.js';
-/** What a drive holds while it runs: a read-through map plus whatever it learned. */
-export interface FillValueStore {
-    get(label: string): string | undefined;
-    set(label: string, value: string): void;
-    /** Persist, if anything was learned. Silent on failure, like every read here. */
-    flush(): Promise<void>;
-}
-/**
- * A store that remembers within one drive and writes nothing.
- *
- * Used when there is no project directory to write to. A drive must never fail over its fixtures
- * file, and that includes failing to FIND one: the values still de-duplicate inside the run, they
- * are simply not carried into the next one.
- */
-export declare function memoryFillValues(): FillValueStore;
-export declare function openFillValues(fs: FileSystemPort, root: string | undefined): Promise<FillValueStore>;

package/dist/memory/project/dir/fill-value-store.js

@@ -1,88 +0,0 @@
-/**
- * The values a drive types into this project's fields, kept so they are paid for once.
- *
- * A generated field value is not a model's opinion to be re-asked every run. It is a FIXTURE: the
- * same label on the same app wants the same value tomorrow, a replay must send exactly what the
- * recording sent or it is not a replay, and a human who dislikes "Acme Corp" should be able to open
- * a file and write something else rather than argue with a model about it. So it lives beside the
- * flows it belongs to, in git, in the project's own directory.
- *
- * Read once at the start of a drive and written once at the end: a drive that fills twenty fields
- * must not write the file twenty times, and nothing else in the process is competing for it.
- *
- * Every failure is silent and answers "no values". A drive must never fail over a fixtures file,
- * and the fallback -- the label heuristic -- is what every drive used before this existed.
- */
-import { ReticleDir } from '@reticlehq/core';
-import { join } from 'node:path';
-/** Stamped so a later format change can tell an old file from a broken one. */
-const VERSION = 1;
-/** A label is a UI string and can be anything; a value that is not a string is not usable. */
-function parse(text) {
-    try {
-        const raw = JSON.parse(text);
-        if ('object' !== typeof raw || null === raw)
-            return {};
-        const values = raw.values;
-        if ('object' !== typeof values || null === values)
-            return {};
-        const out = {};
-        for (const [label, value] of Object.entries(values))
-            if ('string' === typeof value && 0 < value.length)
-                out[label] = value;
-        return out;
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * A store that remembers within one drive and writes nothing.
- *
- * Used when there is no project directory to write to. A drive must never fail over its fixtures
- * file, and that includes failing to FIND one: the values still de-duplicate inside the run, they
- * are simply not carried into the next one.
- */
-export function memoryFillValues() {
-    const values = new Map();
-    return {
-        get: (label) => values.get(label),
-        set: (label, value) => void values.set(label, value),
-        flush: () => Promise.resolve(),
-    };
-}
-export async function openFillValues(fs, root) {
-    if (root === undefined || 0 === root.length)
-        return memoryFillValues();
-    const path = join(root, ReticleDir.FILL_VALUES_FILE);
-    let values = {};
-    try {
-        if (await fs.exists(path))
-            values = parse(await fs.readFile(path));
-    }
-    catch {
-        /* an unreadable fixtures file is the same as an absent one */
-    }
-    let learned = false;
-    return {
-        get: (label) => values[label],
-        set: (label, value) => {
-            if (values[label] === value)
-                return;
-            values[label] = value;
-            learned = true;
-        },
-        async flush() {
-            if (!learned)
-                return;
-            try {
-                await fs.mkdir(root);
-                const file = { version: VERSION, values };
-                await fs.writeFile(path, `${JSON.stringify(file, null, 2)}\n`);
-            }
-            catch {
-                /* the drive already happened; losing the cache costs a regeneration, not a result */
-            }
-        },
-    };
-}

package/docs/local-registry.md

@@ -1,143 +0,0 @@
----
-title: Local registry
-description: 'Exercise local, unpublished Reticle changes in a real external app before they ship.'
-icon: box
----
-
-To test unpublished `@reticlehq/*` changes in a real external app, publish the workspace to a local Verdaccio with `bash scripts/local-registry.sh`, then point that app's `.npmrc` at `http://localhost:4873/` as the **default** registry, not scoped to `@reticlehq`, for the reason in step 2. That is the whole procedure; the rest of this page is the detail.
-
-> **For normal use, Reticle is on public npm.** Just `npm i -D @reticlehq/react @reticlehq/vite-plugin` (see [Getting Started](getting-started.md)). You only need this guide to test **local, unpublished changes** to the Reticle packages in a real external app before they ship.
-
-Because the `@reticlehq/*` packages depend on each other via the workspace protocol, plain `npm pack` tarballs don't resolve cleanly. The reliable way to exercise your in-progress changes in a real app is a tiny **local registry** (Verdaccio), the same path CI uses to validate a publish.
-
-## 1. Publish @reticlehq/\* to a local registry
-
-From the Reticle repo:
-
-```bash
-bash scripts/local-registry.sh
-```
-
-This starts a **fresh** Verdaccio on `http://localhost:4873`, creates a user/token, and publishes all `@reticlehq/*` packages there at the current workspace version:
-
-| Package | What you install it for |
-| --- | --- |
-| **`@reticlehq/react`** | **install this**: the browser SDK kit you embed (re-exports the browser sensor, so one install gives both `reticle` and `install`) |
-| `@reticlehq/vite-plugin` | dev-only source mapping + `connect()` injection (Vite) |
-| `@reticlehq/next` | Next.js build wrapper (`withReticle`) |
-| `@reticlehq/server` | the bridge + MCP server (your agent runs it, `npx @reticlehq/server mcp`) |
-| `@reticlehq/babel-plugin` | React 19 source stamping (Babel) |
-| `@reticlehq/test` | write declarative, signal-bound specs (`reticleTest`) |
-| `@reticlehq/eslint-plugin` | the `require-signal-on-mutation` lint rule |
-| `@reticlehq/core` | shared wire contract (pulled in automatically) |
-
-For a browser app, install `@reticlehq/react` plus the build plugin for your framework (`@reticlehq/vite-plugin` or `@reticlehq/next`); `@reticlehq/server` is what your agent runs. (Verified: an external `npm i @reticlehq/react` resolves its graph, including `@reticlehq/core`, and imports correctly.) Leave the registry running.
-
-> Note: pre-2.0 docs used a single `@reticlehq/core` umbrella package that re-exported everything; it's been split into the audience-scoped packages above.
-
-## 2. Point your app at the local registry
-
-In your app's project root, add an `.npmrc` pointing the **default** registry at Verdaccio. Verdaccio proxies npm for everything it does not hold, so the rest of your dependencies still resolve normally:
-
-```ini
-registry=http://localhost:4873/
-```
-
-**A scope-only line does not work, and fails in a way that reads as a Reticle bug.** `@reticlehq/core` depends on **`open-verification`**, the protocol package, which is deliberately _unscoped_ because the protocol is not ours to namespace. With `@reticlehq:registry=…` npm sends that one request to npmjs and the install dies:
-
-```
-npm error 404 Not Found - GET https://registry.npmjs.org/open-verification
-npm error 404  The requested resource 'open-verification@3.1.0' could not be found
-```
-
-`reticle init` then correctly reports `⚠ Install dependencies` and skips wiring the build plugin, so the app is left un-instrumented by a registry mistake two steps earlier.
-
-There is no scoped form that fixes this: npm's per-registry setting is `@scope:registry`, and an unscoped package has no scope to key on. The default-registry line above is the only thing that works. Point it back at npm (`npm config delete registry`, or delete the `.npmrc`) when you are done testing.
-
-## 3. Install + wire it up
-
-Install the SDK kit plus the Vite build plugin (source mapping + `connect()` injection):
-
-```bash
-npm i -D @reticlehq/react @reticlehq/vite-plugin
-# Next.js instead of Vite? npm i -D @reticlehq/react @reticlehq/next
-# optional: npm i -D @reticlehq/eslint-plugin   # require-signal-on-mutation lint rule
-```
-
-Then follow [Getting Started](getting-started.md): embed `reticle.connect()` (dev only) from `@reticlehq/react`, add the MCP server to your agent, and (React) `install()` the adapter from `@reticlehq/react`. For the fastest agent loop, also do [Step 6: make your app agent-legible](getting-started.md) (testids, `reticle.signal`, `registerStore`, `registerCapabilities`) and the [integration patterns](integration-patterns.md) (`createReticleEmitter` for zero prod-bundle cost).
-
-> **Upgrading.** `scripts/local-registry.sh` resets Verdaccio and republishes at whatever version the workspace is on right now, so your app will not pick up a rebuild on its own. Pull it explicitly with `@latest`:
->
-> ```bash
-> npm i -D @reticlehq/react@latest @reticlehq/vite-plugin@latest @reticlehq/eslint-plugin@latest
-> ```
-
-**Run the MCP server** from the local registry too; `npx @reticlehq/server` _is_ the server:
-
-```jsonc
-// .mcp.json: point npx at the local registry so it fetches @reticlehq/server from Verdaccio
-{
-  "mcpServers": {
-    "reticle": {
-      "command": "npx",
-      "args": ["--registry", "http://localhost:4873/", "@reticlehq/server", "mcp"],
-    },
-  },
-}
-```
-
-## Next.js specifics (verified on Next 15 / React 19)
-
-`next.config.mjs`:
-
-```js
-import reticleNext from '@reticlehq/next';
-/** @type {import('next').NextConfig} */
-const nextConfig = {};
-export default reticleNext.withReticle(nextConfig); // dev-only; keeps SWC; adds file:line mapping
-```
-
-Mount the SDK from a dev-only client component (see the Next.js section in [Getting Started](getting-started.md)).
-
-## Real input for hover/drag (optional)
-
-Synthetic events can't trigger native `onMouseEnter`/pointer state (hover menus, tooltips, pointer drag). Enable **real input** so the server drives genuine pointer input and `reticle_act` reports `inputMode:"real"`:
-
-- **Easiest (`reticle drive`):** Reticle launches its own scriptable, headless-capable browser at your app URL (no flags to juggle):
-
-  ```bash
-  npx --registry http://localhost:4873/ @reticlehq/server drive http://localhost:4310   # add --headed to watch
-  ```
-
-- **Or attach to your own browser:** launch it with `--remote-debugging-port=9222`, then point the MCP server at it via `env`:
-
-  ```jsonc
-  // .mcp.json
-  {
-    "mcpServers": {
-      "reticle": {
-        "command": "npx",
-        "args": ["--registry", "http://localhost:4873/", "@reticlehq/server", "mcp"],
-        "env": { "RETICLE_CDP_URL": "http://localhost:9222" },
-      },
-    },
-  }
-  ```
-
-With neither set, Reticle stays synthetic (zero extra deps) and says so via `inputMode`. See [usage §18](usage.md#18-real-input-mode-native-hover--drag).
-
-## Write replayable specs + git-checked flows
-
-- **Specs:** with `@reticlehq/test`, turn checks into `reticleTest("…", async t => { await t.act(...); await t.expectSignal(...) })`. They are signal/testid-bound, `reticle_clock` for determinism, `t.expectInputModeReal()` to skip-with-reason when real input isn't active. Run them headless via `reticle drive` (the same path CI uses).
-- **Flows:** record a flow once and Reticle writes it to a git-checked `.reticle/flows/<name>.json` (anchored on testid/signal); `reticle_flow_replay` re-resolves anchors at run time and reports **legible drift** with a nearest-match; `reticle_verify { action: "heal" }` proposes/applies the rebind. A fresh agent reads `.reticle/contract.json` to learn your testable surface without grepping source.
-
-## When you're ready for real npm
-
-The same packages publish to public npm unchanged: `pnpm -r publish --access public` after `npm login`. The Verdaccio run above is a faithful rehearsal of that.
-
-## Cleanup
-
-```bash
-pkill -f verdaccio     # stop the local registry
-# remove the line from your app's .npmrc when you switch to published packages
-```