@relvehq/agent-ready 0.0.0-stage → 0.3.0

package/dist/refine/prompts.d.ts

@@ -0,0 +1,49 @@
+import { type PageInput } from "./types";
+export interface PromptSettings {
+    pageType: string;
+    version: number;
+    requiredSections: string[];
+    tokenBudget: number;
+    /** Kept from the POC table; not enforced yet. */
+    recallThreshold: number | null;
+}
+export interface RefinePrompt {
+    /** "<page_type>-v<version>", e.g. "tool-v1": the doc's prompt_version. */
+    id: string;
+    system: string;
+    user: string;
+    settings: PromptSettings;
+}
+export declare function parsePrompt(source: string): RefinePrompt;
+export interface FilledPrompt {
+    system: string;
+    user: string;
+}
+export interface FillOptions {
+    generatedAt: string;
+    /** {{SITE_NAME}}. Default: the page's host without "www.". */
+    siteName?: string;
+    /** {{PAGE_KIND_HINT}}. Default: guessPageKind(input). */
+    kindHint?: PageKind;
+}
+/** Put the page into the prompt. Every {{PLACEHOLDER}} the recipe defines is filled. */
+export declare function fillPrompt(prompt: RefinePrompt, input: PageInput, opts: FillOptions): FilledPrompt;
+/** The page kinds guessPageKind can name; passed to a `page` prompt as {{PAGE_KIND_HINT}}. */
+export declare const PAGE_KINDS: readonly ["home", "product", "pricing", "article", "docs", "listing", "event", "about", "contact", "legal", "other"];
+export type PageKind = (typeof PAGE_KINDS)[number];
+/**
+ * A first guess at the page's kind, from the path and JSON-LD. Only a hint:
+ * the prompt tells the model to confirm it from the page or pick better.
+ * Path rules win over generic JSON-LD (every page has an Organization block).
+ */
+export declare function guessPageKind(input: Pick<PageInput, "url" | "jsonLd">): PageKind;
+/** The prompt key that takes any path no other prompt claims. */
+export declare const FALLBACK_PROMPT = "page";
+/** The prompt for a path: a matching page-type prompt, else the any-page prompt, else null. */
+export declare function promptFor(path: string, prompts: Record<string, RefinePrompt>, rules?: PageTypeRules): RefinePrompt | null;
+/** Which prompt a path uses: the first matching prefix. Relve's types by default. */
+export type PageTypeRules = ReadonlyArray<readonly [prefix: string, pageType: string]>;
+export declare const DEFAULT_PAGE_TYPES: PageTypeRules;
+export declare function pageTypeFor(path: string, rules?: PageTypeRules): string | null;
+/** Many prompt files -> the newest version per page type. */
+export declare function promptsByType(prompts: RefinePrompt[]): Record<string, RefinePrompt>;

package/dist/refine/prompts.js

@@ -0,0 +1,178 @@
+"use strict";
+// Refine, step 2: a prompt file -> the model's messages.
+//
+// A prompt file is the POC's format (changes/markdown-poc/prompts/*-v1.md):
+//
+//   ## SYSTEM     the rules (may hold {{SOURCE_HASH}}, {{PROMPT_VERSION}},
+//                 {{GENERATED_AT}} in its front matter template)
+//   ## USER       the template the page is filled into ({{PAGE_URL}},
+//                 {{PAGE_TEXT}}, {{PAGE_LINKS}}, {{JSON_LD}})
+//   ---
+//   ## Settings   a table: page_type, version, required_sections,
+//                 token_budget, recall_threshold
+//
+// The settings are checked by code (refine/check.ts), never by the model.
+// EDGE-SAFE (pure).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PAGE_TYPES = exports.FALLBACK_PROMPT = exports.PAGE_KINDS = void 0;
+exports.parsePrompt = parsePrompt;
+exports.fillPrompt = fillPrompt;
+exports.guessPageKind = guessPageKind;
+exports.promptFor = promptFor;
+exports.pageTypeFor = pageTypeFor;
+exports.promptsByType = promptsByType;
+const types_1 = require("./types");
+function parsePrompt(source) {
+    const md = source.replace(/^/, "").replace(/\r\n?/g, "\n");
+    const sys = /^## SYSTEM[ \t]*$/m.exec(md);
+    const usr = /^## USER[ \t]*$/m.exec(md);
+    const set = /^## Settings\b.*$/m.exec(md);
+    if (!sys || !usr || !set || !(sys.index < usr.index && usr.index < set.index)) {
+        throw new Error("agent-ready refine: a prompt needs '## SYSTEM', '## USER' and '## Settings', in that order.");
+    }
+    const system = md.slice(sys.index + sys[0].length, usr.index).trim();
+    const user = md
+        .slice(usr.index + usr[0].length, set.index)
+        .trim()
+        .replace(/\n-{3,}\s*$/, "")
+        .trim();
+    const rows = {};
+    for (const m of md.slice(set.index).matchAll(/^\|\s*`(\w+)`\s*\|(.+)\|\s*$/gm)) {
+        rows[m[1]] = Array.from(m[2].matchAll(/`([^`]+)`/g), (v) => v[1]);
+    }
+    const one = (k) => rows[k]?.[0];
+    const pageType = one("page_type");
+    const version = Number(one("version"));
+    const tokenBudget = Number(one("token_budget"));
+    if (!pageType || !Number.isFinite(version) || !Number.isFinite(tokenBudget)) {
+        throw new Error("agent-ready refine: the Settings table needs page_type, version and token_budget.");
+    }
+    const recall = Number(one("recall_threshold"));
+    return {
+        id: `${pageType}-v${version}`,
+        system,
+        user,
+        settings: {
+            pageType,
+            version,
+            requiredSections: rows.required_sections ?? [],
+            tokenBudget,
+            recallThreshold: Number.isFinite(recall) ? recall : null,
+        },
+    };
+}
+/** Put the page into the prompt. Every {{PLACEHOLDER}} the recipe defines is filled. */
+function fillPrompt(prompt, input, opts) {
+    const u = new URL(input.url);
+    const vars = {
+        PAGE_URL: input.url,
+        PAGE_TEXT: input.text,
+        PAGE_LINKS: (0, types_1.formatLinks)(input.links),
+        JSON_LD: JSON.stringify(input.jsonLd, null, 2),
+        SOURCE_HASH: input.sourceHash,
+        PROMPT_VERSION: prompt.id,
+        GENERATED_AT: opts.generatedAt,
+        SITE_NAME: opts.siteName ?? u.hostname.replace(/^www\./, ""),
+        SITE_URL: u.origin,
+        PAGE_KIND_HINT: opts.kindHint ?? guessPageKind(input),
+    };
+    // A function replacer, so "$" in page text is never read as a pattern.
+    const fill = (s) => s.replace(/\{\{([A-Z_]+)\}\}/g, (m, k) => (k in vars ? vars[k] : m));
+    return { system: fill(prompt.system), user: fill(prompt.user) };
+}
+/** The page kinds guessPageKind can name; passed to a `page` prompt as {{PAGE_KIND_HINT}}. */
+exports.PAGE_KINDS = ["home", "product", "pricing", "article", "docs", "listing", "event", "about", "contact", "legal", "other"];
+const KIND_BY_LD = [
+    [/^(Article|BlogPosting|NewsArticle|TechArticle|Report|ScholarlyArticle)$/, "article"],
+    [/^(Event|BusinessEvent|EducationEvent|Hackathon|SocialEvent)$/, "event"],
+    [/^(Product|SoftwareApplication|WebApplication|MobileApplication|Service|Course)$/, "product"],
+    [/^(CollectionPage|ItemList|SearchResultsPage)$/, "listing"],
+    [/^(AboutPage|ProfilePage)$/, "about"],
+    [/^(ContactPage)$/, "contact"],
+    [/^(HowTo)$/, "docs"],
+];
+const KIND_BY_PATH = [
+    [/^\/(pricing|plans|prices)(\/|$)/, "pricing"],
+    [/^\/(blog|news|articles?|posts?|stories|insights|press|case-stud(y|ies)|resources\/blog)(\/|$)/, "article"],
+    [/^\/(docs?|documentation|help|support|guides?|kb|knowledge-base|faq|learn|api)(\/|$)/, "docs"],
+    [/^\/(events?|webinars?|conferences?)(\/|$)/, "event"],
+    [/^\/(about|about-us|company|team|careers|jobs|mission)(\/|$)/, "about"],
+    [/^\/(contact|contact-us|locations?|stores?)(\/|$)/, "contact"],
+    [/^\/(privacy|terms|legal|cookies?|policies|policy|refunds?|security|gdpr|tos)(-[\w-]+)?(\/|$)/, "legal"],
+    [/^\/(products?|services?|solutions?|features?|tools?|apps?|platform|integrations?)\/[^/]+/, "product"],
+    [/^\/(products?|services?|solutions?|tools?|category|categories|collections?|shop|catalog|directory|tags?)(\/|$)/, "listing"],
+];
+/**
+ * A first guess at the page's kind, from the path and JSON-LD. Only a hint:
+ * the prompt tells the model to confirm it from the page or pick better.
+ * Path rules win over generic JSON-LD (every page has an Organization block).
+ */
+function guessPageKind(input) {
+    let path = "/";
+    try {
+        path = new URL(input.url).pathname.replace(/\/+$/, "") || "/";
+    }
+    catch {
+        // keep "/"
+    }
+    if (path === "/")
+        return "home";
+    for (const [re, kind] of KIND_BY_PATH)
+        if (re.test(path.toLowerCase()))
+            return kind;
+    for (const t of ldTypes(input.jsonLd))
+        for (const [re, kind] of KIND_BY_LD)
+            if (re.test(t))
+                return kind;
+    return "other";
+}
+function ldTypes(blocks) {
+    const out = [];
+    const visit = (v, depth) => {
+        if (!v || typeof v !== "object" || depth > 3)
+            return;
+        if (Array.isArray(v))
+            return v.forEach((x) => visit(x, depth + 1));
+        const o = v;
+        const t = o["@type"];
+        if (typeof t === "string")
+            out.push(t);
+        else if (Array.isArray(t))
+            out.push(...t.filter((x) => typeof x === "string"));
+        if (o["@graph"])
+            visit(o["@graph"], depth + 1);
+        if (o.mainEntity)
+            visit(o.mainEntity, depth + 1);
+    };
+    visit(blocks, 0);
+    return out;
+}
+/** The prompt key that takes any path no other prompt claims. */
+exports.FALLBACK_PROMPT = "page";
+/** The prompt for a path: a matching page-type prompt, else the any-page prompt, else null. */
+function promptFor(path, prompts, rules = exports.DEFAULT_PAGE_TYPES) {
+    const type = pageTypeFor(path, rules);
+    return (type && prompts[type]) || prompts[exports.FALLBACK_PROMPT] || null;
+}
+exports.DEFAULT_PAGE_TYPES = [
+    ["/tool/", "tool"],
+    ["/agent/", "agent"],
+    ["/events/", "event"],
+    ["/blog/", "blog"],
+];
+function pageTypeFor(path, rules = exports.DEFAULT_PAGE_TYPES) {
+    for (const [prefix, type] of rules)
+        if (path.startsWith(prefix) && path.length > prefix.length)
+            return type;
+    return null;
+}
+/** Many prompt files -> the newest version per page type. */
+function promptsByType(prompts) {
+    const out = {};
+    for (const p of prompts) {
+        const cur = out[p.settings.pageType];
+        if (!cur || p.settings.version > cur.settings.version)
+            out[p.settings.pageType] = p;
+    }
+    return out;
+}

package/dist/refine/refine.d.ts

@@ -0,0 +1,38 @@
+import { type CheckIssue, type CheckOptions } from "./check";
+import { type ModelClient } from "./model";
+import { type RefinePrompt } from "./prompts";
+import type { PageInput } from "./types";
+export type RefineStatus = "ok" | "unchanged" | "rejected" | "error";
+export interface RefineOptions extends CheckOptions {
+    /** Absolute page URL. */
+    url: string;
+    prompt: RefinePrompt;
+    model: ModelClient;
+    /** The page's HTML, when the caller already has it (else it is fetched). */
+    html?: string;
+    fetch?: typeof fetch;
+    /** The stored doc's fingerprint: equal to the page's -> "unchanged", no model call. */
+    previousHash?: string | null;
+    /** Extra attempts after a failed check, each told what failed. Default 1. */
+    retries?: number;
+    now?: () => Date;
+    /** {{SITE_NAME}} for the any-page prompt. Default: the host. */
+    siteName?: string;
+}
+export interface RefineResult {
+    status: RefineStatus;
+    url: string;
+    input: PageInput | null;
+    /** The last document the model wrote (kept on "rejected", for review). */
+    doc: string | null;
+    issues: CheckIssue[];
+    attempts: number;
+    tokens: number | null;
+    generatedAt: string | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    error: string | null;
+}
+export declare function refinePage(opts: RefineOptions): Promise<RefineResult>;

package/dist/refine/refine.js

@@ -0,0 +1,75 @@
+"use strict";
+// Refine one page: fetch -> extract -> (unchanged? stop) -> fill the prompt ->
+// model -> check -> retry once with the issues -> result.
+// Nothing is stored here; the runner decides (refine/run.ts).
+//
+// NODE ONLY (extract uses linkedom).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refinePage = refinePage;
+const extract_1 = require("./extract");
+const check_1 = require("./check");
+const model_1 = require("./model");
+const prompts_1 = require("./prompts");
+async function refinePage(opts) {
+    const result = {
+        status: "error",
+        url: opts.url,
+        input: null,
+        doc: null,
+        issues: [],
+        attempts: 0,
+        tokens: null,
+        generatedAt: null,
+        usage: { inputTokens: 0, outputTokens: 0 },
+        error: null,
+    };
+    try {
+        const html = opts.html ?? (await fetchPage(opts.url, opts.fetch ?? fetch));
+        const input = await (0, extract_1.extractInput)(html, { url: opts.url });
+        result.input = input;
+        if (opts.previousHash && opts.previousHash === input.sourceHash) {
+            result.status = "unchanged";
+            return result;
+        }
+        const generatedAt = (opts.now ?? (() => new Date()))().toISOString().replace(/\.\d{3}Z$/, "Z");
+        result.generatedAt = generatedAt;
+        const filled = (0, prompts_1.fillPrompt)(opts.prompt, input, { generatedAt, siteName: opts.siteName });
+        const maxAttempts = 1 + Math.max(0, opts.retries ?? 1);
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            result.attempts = attempt;
+            const user = attempt === 1 ? filled.user : `${filled.user}\n\n${retryNote(result.issues)}`;
+            const reply = await opts.model({ system: filled.system, user });
+            result.usage.inputTokens += reply.inputTokens ?? 0;
+            result.usage.outputTokens += reply.outputTokens ?? 0;
+            const doc = (0, model_1.cleanReply)(reply.text);
+            const check = (0, check_1.checkDoc)(doc, input, opts.prompt.settings, opts);
+            result.doc = doc;
+            result.issues = check.issues;
+            result.tokens = check.tokens;
+            if (check.ok) {
+                result.status = "ok";
+                return result;
+            }
+        }
+        result.status = "rejected";
+        return result;
+    }
+    catch (err) {
+        result.status = "error";
+        result.error = err?.message ?? String(err);
+        return result;
+    }
+}
+function retryNote(issues) {
+    const list = issues.map((i) => `- ${i.kind}: ${i.detail}`).join("\n");
+    return `<check_failed>\nYour previous document failed the automatic check:\n${list}\nRemove anything that is not in the input and fix the rest. Output the corrected document only.\n</check_failed>`;
+}
+async function fetchPage(url, f) {
+    const res = await f(url, {
+        headers: { accept: "text/html", "user-agent": "agent-ready-refine/0.1" },
+        redirect: "follow",
+    });
+    if (!res.ok)
+        throw new Error(`page fetch failed: HTTP ${res.status}`);
+    return res.text();
+}

package/dist/refine/remote.d.ts

@@ -0,0 +1,57 @@
+export declare const PACKAGE_VERSION = "0.3.0";
+export declare const DEFAULT_REFINE_ENDPOINT = "https://relvehq.com/api/agent-ready/v1/refine";
+export declare const REFINE_MODELS: readonly ["gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini"];
+export declare const USER_AGENT = "agent-ready/0.3.0 (+https://relvehq.com/agent-ready)";
+export type RemoteStatus = "ok" | "unchanged" | "rejected" | "error" | "skipped";
+export interface RemoteItem {
+    path: string;
+    status: RemoteStatus;
+    /** Error code from the contract (e.g. "openai_auth", "too_little_text"), or a local one ("page_fetch", "network", "timeout", "bad_response"). */
+    code?: string;
+    message?: string;
+    /** Check messages on "rejected". */
+    issues?: string[];
+    tokens?: number;
+    kind?: string;
+    model?: string;
+    saved: boolean;
+}
+export interface RemoteReport {
+    items: RemoteItem[];
+    counts: Record<RemoteStatus, number>;
+    tokens: number;
+    /** The error code that stopped the run early, or null. */
+    stopped: string | null;
+    dir: string;
+}
+export interface RemoteOptions {
+    /** Public origin, e.g. "https://your-site.com". */
+    site: string;
+    paths: string[];
+    /** The caller's OpenAI key. Sent in X-OpenAI-Key, nothing else. */
+    apiKey: string;
+    /** Output folder. Default ".agent-ready/md". */
+    outDir?: string;
+    endpoint?: string;
+    model?: string;
+    siteName?: string;
+    /** Ignore saved fingerprints. */
+    force?: boolean;
+    /** Pages at a time. Default 2. */
+    concurrency?: number;
+    fetch?: typeof fetch;
+    /** Relve API timeout. Default 90 s. */
+    timeoutMs?: number;
+    /** Page fetch timeout. Default 30 s. */
+    pageTimeoutMs?: number;
+    /** Wait before retrying a 502/504. Default 2 s. */
+    retryDelayMs?: number;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+    onResult?: (item: RemoteItem) => void;
+}
+/** The saved JSON's fingerprint, else one built from a local run's sourceHash, else null. */
+export declare function savedFingerprint(outDir: string, path: string): Promise<string | null>;
+export declare function refineRemote(opts: RemoteOptions): Promise<RemoteReport>;
+/** What a stop code means, for the CLI. */
+export declare function stopMessage(code: string): string;

package/dist/refine/remote.js

@@ -0,0 +1,238 @@
+"use strict";
+// Refine through the Relve API, with the caller's own OpenAI key (BYOK).
+// changes/agent-ready-byok-refine/contract.md is the wire format.
+//
+//   await refineRemote({ site, paths, apiKey, outDir })
+//
+// For each page: fetch its HTML here, read the saved fingerprint from
+// `<out>/<path>.json`, POST { url, html, siteName?, model?, previousFingerprint? }
+// to the endpoint with the key in `X-OpenAI-Key`, and save `ok` results as
+// `<out>/<path>.md` + `<out>/<path>.json` through fileStore, so the files are
+// served exactly like the ones local refine writes. Relve's prompt runs on
+// Relve's server; it never reaches this machine. The key is sent with each
+// call and is never written, logged or put in an error message here.
+//
+// NODE ONLY (fileStore, node:fs).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_AGENT = exports.REFINE_MODELS = exports.DEFAULT_REFINE_ENDPOINT = exports.PACKAGE_VERSION = void 0;
+exports.savedFingerprint = savedFingerprint;
+exports.refineRemote = refineRemote;
+exports.stopMessage = stopMessage;
+const file_store_1 = require("./file-store");
+exports.PACKAGE_VERSION = "0.3.0";
+exports.DEFAULT_REFINE_ENDPOINT = "https://relvehq.com/api/agent-ready/v1/refine";
+exports.REFINE_MODELS = ["gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini"];
+exports.USER_AGENT = `agent-ready/${exports.PACKAGE_VERSION} (+https://relvehq.com/agent-ready)`;
+/** Errors that mean every later call would fail the same way: the run stops. */
+const FATAL = new Set(["openai_auth", "openai_quota", "missing_key"]);
+/** The saved JSON's fingerprint, else one built from a local run's sourceHash, else null. */
+async function savedFingerprint(outDir, path) {
+    try {
+        const { readFile } = await Promise.resolve().then(() => __importStar(require("node:fs/promises")));
+        const meta = JSON.parse(await readFile(metaFile(outDir, path), "utf8"));
+        if (typeof meta.fingerprint === "string" && meta.fingerprint)
+            return meta.fingerprint;
+        if (typeof meta.sourceHash === "string" && meta.sourceHash)
+            return meta.sourceHash.startsWith("sha256:") ? meta.sourceHash : `sha256:${meta.sourceHash}`;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `<out>/<path>.json`, the same name fileStore uses. */
+function metaFile(outDir, path) {
+    const clean = path.replace(/^\/+|\/+$/g, "");
+    return `${outDir.replace(/[\\/]+$/, "")}/${clean || "index"}.json`;
+}
+async function refineRemote(opts) {
+    const site = opts.site.replace(/\/+$/, "");
+    const dir = opts.outDir ?? ".agent-ready/md";
+    const store = (0, file_store_1.fileStore)(dir);
+    const f = opts.fetch ?? fetch;
+    const endpoint = opts.endpoint ?? exports.DEFAULT_REFINE_ENDPOINT;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? (() => new Date());
+    const items = opts.paths.map((path) => ({ path, status: "skipped", saved: false }));
+    let next = 0;
+    let stopped = null;
+    const one = async (path) => {
+        const url = site + path;
+        let html;
+        try {
+            html = await fetchPage(f, url, opts.pageTimeoutMs ?? 30000);
+        }
+        catch (err) {
+            return { path, status: "error", code: "page_fetch", message: err.message, saved: false };
+        }
+        const previousFingerprint = opts.force ? null : await savedFingerprint(dir, path);
+        const body = JSON.stringify({
+            url,
+            html,
+            ...(opts.siteName ? { siteName: opts.siteName } : {}),
+            ...(opts.model ? { model: opts.model } : {}),
+            ...(previousFingerprint ? { previousFingerprint } : {}),
+        });
+        let reply = null;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            reply = await post(f, endpoint, opts.apiKey, body, opts.timeoutMs ?? 90000);
+            if (attempt > 0)
+                break;
+            if (reply.httpStatus === 429 && reply.json?.error === "rate_limited") {
+                const after = Number(reply.json.retryAfter ?? reply.retryAfterHeader ?? 10);
+                await sleep(Math.min(Number.isFinite(after) && after >= 0 ? after : 10, 60) * 1000);
+                continue;
+            }
+            if (reply.httpStatus === 502 || reply.httpStatus === 504) {
+                await sleep(opts.retryDelayMs ?? 2000);
+                continue;
+            }
+            break;
+        }
+        const r = reply;
+        if (r.local)
+            return { path, status: "error", code: r.local.code, message: r.local.message, saved: false };
+        const j = r.json ?? {};
+        if (r.httpStatus === 200 && j.status === "ok" && typeof j.markdown === "string" && typeof j.fingerprint === "string") {
+            const stamp = now().toISOString().replace(/\.\d{3}Z$/, "Z");
+            const tokens = Number(j.tokens) || 0;
+            const doc = {
+                path,
+                url,
+                markdown: j.markdown,
+                // sourceHash keeps local refine's freshness check working on these files.
+                sourceHash: j.fingerprint.replace(/^sha256:/, ""),
+                promptId: String(j.prompt ?? "page-v1"),
+                generatedAt: stamp,
+                tokens,
+                fingerprint: j.fingerprint,
+                model: j.model ?? opts.model ?? null,
+                prompt: j.prompt ?? null,
+                kind: j.kind ?? null,
+                refinedAt: stamp,
+                source: "relve-api",
+            };
+            try {
+                await store.save(doc);
+            }
+            catch (err) {
+                return { path, status: "error", code: "write", message: err.message, saved: false };
+            }
+            return { path, status: "ok", tokens, kind: j.kind ?? undefined, model: j.model ?? undefined, saved: true };
+        }
+        if (r.httpStatus === 200 && j.status === "unchanged")
+            return { path, status: "unchanged", saved: false };
+        if (j.status === "rejected") {
+            return { path, status: "rejected", code: "rejected", issues: Array.isArray(j.issues) ? j.issues.map(String) : [], saved: false };
+        }
+        const code = typeof j.error === "string" ? j.error : r.httpStatus === 200 ? "bad_response" : `http_${r.httpStatus}`;
+        return { path, status: "error", code, message: typeof j.message === "string" ? j.message : undefined, saved: false };
+    };
+    const worker = async () => {
+        while (!stopped && next < opts.paths.length) {
+            const i = next++;
+            const item = await one(opts.paths[i]);
+            items[i] = item;
+            if (item.status === "error" && item.code && FATAL.has(item.code))
+                stopped = item.code;
+            opts.onResult?.(item);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(opts.concurrency ?? 2, opts.paths.length || 1)) }, worker));
+    const counts = { ok: 0, unchanged: 0, rejected: 0, error: 0, skipped: 0 };
+    let tokens = 0;
+    for (const it of items) {
+        counts[it.status]++;
+        tokens += it.tokens ?? 0;
+    }
+    return { items, counts, tokens, stopped, dir: store.dir };
+}
+/** What a stop code means, for the CLI. */
+function stopMessage(code) {
+    if (code === "openai_auth")
+        return "OpenAI rejected the key in OPENAI_API_KEY. Check it at https://platform.openai.com/api-keys and run again.";
+    if (code === "openai_quota")
+        return "Your OpenAI account is out of quota or has no billing set up. Check https://platform.openai.com/settings/organization/billing and run again.";
+    if (code === "missing_key")
+        return "The Relve API got no key. Set OPENAI_API_KEY and run again.";
+    return code;
+}
+async function post(f, endpoint, apiKey, body, timeoutMs) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+        const res = await f(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json", "x-openai-key": apiKey, "user-agent": exports.USER_AGENT },
+            body,
+            signal: ctl.signal,
+        });
+        const text = await res.text();
+        let json = null;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            return { httpStatus: res.status, json: null, retryAfterHeader: null, local: { code: res.ok ? "bad_response" : `http_${res.status}`, message: "the Relve API did not answer with JSON" } };
+        }
+        return { httpStatus: res.status, json, retryAfterHeader: res.headers.get("retry-after") };
+    }
+    catch (err) {
+        const aborted = err?.name === "AbortError" || ctl.signal.aborted;
+        return {
+            httpStatus: 0,
+            json: null,
+            retryAfterHeader: null,
+            local: aborted ? { code: "timeout", message: `no answer from the Relve API in ${Math.round(timeoutMs / 1000)} s` } : { code: "network", message: err?.message ?? "request failed" },
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function fetchPage(f, url, timeoutMs) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+        const res = await f(url, { headers: { accept: "text/html", "user-agent": exports.USER_AGENT }, redirect: "follow", signal: ctl.signal });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return await res.text();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}