@reticlehq/server 3.5.0 → 3.6.0

package/dist/features/harness/platform/remote-drive.js

@@ -0,0 +1,365 @@
+/**
+ * A drive somebody asked for in the platform's chat, run here, on their own machine.
+ *
+ * The platform cannot open `localhost`, and it never tries: the chat files the drive on the platform,
+ * and this daemon — which already calls out to the platform for every Harness turn — asks whether one
+ * is waiting for its project, drives the app it has connected, and reports how it ended. Every call
+ * goes OUT from this machine, so nothing listens for the platform and no port is opened.
+ *
+ * It only asks while an app is connected. A drive taken with nothing to drive would fail for a reason
+ * the person can fix in ten seconds (open the app), and leaving it unclaimed lets the chat tell them
+ * exactly that. One drive at a time: a second request waits for the first to finish.
+ */
+import { DriveMode, DriveTarget, LinkPath, PLATFORM_LINK_VERSION, PresenterTone, TOOL_SESSION_LIMITS, parseDriveSpec, parseToolSessionReply, sessionAskRetryable, } from '@reticlehq/core';
+import { serverOptionsFromEnv } from './server-driver.js';
+/**
+ * How often to ask while an app is connected.
+ *
+ * ponytail: a poll, one small GET per interval per connected daemon; a long-poll or a stream on the
+ * platform side is the upgrade if the chat's wait for a claim ever needs to be shorter than this.
+ */
+export const REMOTE_DRIVE_POLL_MS = 3_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * How often the live picture is taken while a chat-requested drive runs. About one a second is what
+ * reads as video in the chat without turning a minute's drive into megabytes.
+ */
+export const REMOTE_DRIVE_FRAME_MS = 1_000;
+/** The same JPEG quality the platform's own checks film at: about 40 KB a picture. */
+export const REMOTE_DRIVE_JPEG_QUALITY = 50;
+/** What the driven tab's HUD says once a chat-requested drive is over. */
+export const REMOTE_DRIVE_ENDED = {
+    PROVED: 'Harness drive finished: proved',
+    NOT_PROVED: 'Harness drive finished: not proved',
+};
+/**
+ * End the driven tab's session once its drive is over, so its HUD stops counting "planning next
+ * action" for an agent that is not there. Auto-ended, not ended: the next agent or drive revives it.
+ */
+export function endDrivenTab(tab, outcome) {
+    tab?.autoEnd(outcome.ok ? REMOTE_DRIVE_ENDED.PROVED : REMOTE_DRIVE_ENDED.NOT_PROVED, outcome.ok ? PresenterTone.CALM : PresenterTone.WARN);
+}
+export function startRemoteDrives(deps) {
+    const doFetch = deps.fetch ?? ((url, init) => fetch(url, init));
+    let busy = false;
+    let stopped = false;
+    const tick = async (told) => {
+        if (busy || stopped || (undefined === told && !deps.connected()))
+            return;
+        const platform = told ?? serverOptionsFromEnv(await deps.env());
+        if (platform === undefined)
+            return;
+        const headers = {
+            'content-type': 'application/json',
+            authorization: `Bearer ${platform.apiKey}`,
+        };
+        busy = true;
+        try {
+            const res = await doFetch(`${platform.url}${LinkPath.NEXT_DRIVE}`, {
+                method: 'GET',
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return;
+            const drive = (await res.json()).drive;
+            if (null === drive || undefined === drive)
+                return;
+            if ('string' !== typeof drive.id || 'string' !== typeof drive.goal)
+                return;
+            deps.log?.(`reticle: driving a request from the platform chat: ${drive.goal}`);
+            const driveId = drive.id;
+            const driveUrl = `${platform.url}${LinkPath.driveResult(driveId)}`;
+            const app = 'string' === typeof drive.appKey
+                ? { key: drive.appKey, url: 'string' === typeof drive.appUrl ? drive.appUrl : null }
+                : undefined;
+            // Read field by field: a spec from a newer platform still drives, minus what is unknown here.
+            const parsed = parseDriveSpec(drive.spec);
+            const prepared = deps.prepare === undefined
+                ? {
+                    sessionId: await deps.pick?.(drive.goal, platform.apiKey, app),
+                    applied: { target: DriveTarget.TAB, mode: DriveMode.LOCAL },
+                    ignored: [],
+                }
+                : await deps.prepare({
+                    goal: drive.goal,
+                    apiKey: platform.apiKey,
+                    ...(app === undefined ? {} : { app }),
+                    spec: parsed.spec,
+                });
+            const ignored = [...parsed.ignored, ...prepared.ignored];
+            const picked = prepared.sessionId;
+            if (null === picked) {
+                await doFetch(driveUrl, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        ok: false,
+                        summary: ('refusal' in prepared ? prepared.refusal : undefined) ?? NO_OWN_TAB,
+                        verdict: 'unknown',
+                        filmed: false,
+                        applied: prepared.applied,
+                        ignored,
+                    }),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                return;
+            }
+            const sessionId = picked;
+            const frame = deps.frame;
+            // Only when the person asked to watch: a picture of their app leaves this machine for it.
+            const filming = false === drive.record || frame === undefined
+                ? undefined
+                : film(() => frame(sessionId), deps.frameIntervalMs ?? REMOTE_DRIVE_FRAME_MS, (jpeg) => doFetch(`${platform.url}${LinkPath.driveFrames(driveId)}`, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({ jpeg }),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                }));
+            // The platform decides every step; this daemon only runs the tools it is told to.
+            const session = deps.session;
+            if (DriveMode.PLATFORM === prepared.applied.mode && session !== undefined) {
+                try {
+                    const tools = session(sessionId);
+                    await runToolSession((body) => doFetch(`${platform.url}${LinkPath.driveSession(driveId)}`, {
+                        method: 'POST',
+                        headers,
+                        body: JSON.stringify(body),
+                        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                    }), tools, {
+                        applied: prepared.applied,
+                        ignored,
+                        ...(tools.tools === undefined ? {} : { tools: tools.tools }),
+                    }, deps.now ?? (() => Date.now()), deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))));
+                }
+                finally {
+                    await filming?.stop();
+                    deps.settle?.(sessionId, { ok: true, summary: '' });
+                }
+                return;
+            }
+            let outcome;
+            let framesSent = 0;
+            try {
+                outcome = await deps.drive(drive.goal, sessionId);
+            }
+            catch (error) {
+                outcome = { ok: false, summary: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                framesSent = (await filming?.stop()) ?? 0;
+            }
+            deps.settle?.(sessionId, outcome);
+            await doFetch(driveUrl, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    ...outcome,
+                    filmed: 0 < framesSent,
+                    applied: prepared.applied,
+                    ignored,
+                }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch {
+            // Offline, or the platform is down: the next tick asks again. The local daemon never fails for it.
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const timer = setInterval(() => void tick(), deps.intervalMs ?? REMOTE_DRIVE_POLL_MS);
+    timer.unref();
+    return {
+        tick,
+        stop: () => {
+            stopped = true;
+            clearInterval(timer);
+        },
+    };
+}
+/**
+ * A drive the platform orchestrates: post what the last calls did, run the next batch, until the
+ * platform says the drive is over, stops answering, or the drive reaches its call budget. Every call
+ * is answered, failed ones included: the platform decides what a failure means.
+ */
+async function runToolSession(post, tools, first, now, sleep) {
+    let results = [];
+    let made = 0;
+    // Numbered, so an ask sent again after a failure is the SAME ask: the platform answers it once.
+    for (let ask = 0;; ask += 1) {
+        const body = {
+            protocol: PLATFORM_LINK_VERSION,
+            ask,
+            results,
+            ...(0 === ask ? first : {}),
+        };
+        const res = await askWithRetries(() => post(body), sleep);
+        // Refused, or still failing after every retry: stop. The platform ends a drive that stops asking.
+        if (res === undefined || !res.ok)
+            return;
+        const reply = parseToolSessionReply(await res.json());
+        if (reply.done)
+            return;
+        results = [];
+        for (const call of reply.calls) {
+            if (made >= TOOL_SESSION_LIMITS.MAX_CALLS)
+                return;
+            made += 1;
+            const at = now();
+            try {
+                const result = await tools.invoke(call.tool, call.args);
+                results.push({ seq: call.seq, ok: true, result, ms: now() - at });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                results.push({ seq: call.seq, ok: false, error: message, ms: now() - at });
+            }
+        }
+    }
+}
+/**
+ * One ask, sent again while the network or the platform fails it (a dropped connection, a 5xx, a
+ * 429), waiting longer each time. A refusal is the platform's answer and is returned as it is.
+ * Undefined when every attempt failed to get any answer at all.
+ */
+async function askWithRetries(send, sleep) {
+    for (let attempt = 0;; attempt += 1) {
+        let res;
+        try {
+            res = await send();
+        }
+        catch {
+            res = undefined;
+        }
+        if (res !== undefined && !sessionAskRetryable(res.status))
+            return res;
+        if (attempt >= TOOL_SESSION_LIMITS.RETRIES)
+            return res;
+        await sleep(TOOL_SESSION_LIMITS.RETRY_BASE_MS * 2 ** attempt);
+    }
+}
+/**
+ * Take a picture every `everyMs` and send it, until stopped. One capture at a time, and a picture
+ * identical to the last one sent is skipped: a page standing still is not worth a request a second.
+ * A failed capture or send is skipped too, never fatal: the drive matters, the picture of it less.
+ * `stop` answers how many pictures were sent.
+ */
+function film(frame, everyMs, send) {
+    let last;
+    let sent = 0;
+    let busy;
+    const shoot = async () => {
+        try {
+            const shot = await frame();
+            if (shot === undefined)
+                return;
+            const jpeg = Buffer.from(shot).toString('base64');
+            if (jpeg === last)
+                return;
+            last = jpeg;
+            // Counted only once the platform took it: a refused picture is not a filmed drive.
+            if ((await send(jpeg)).ok)
+                sent += 1;
+        }
+        catch {
+            // The next tick tries again.
+        }
+    };
+    const timer = setInterval(() => {
+        if (busy === undefined)
+            busy = shoot().finally(() => (busy = undefined));
+    }, everyMs);
+    timer.unref();
+    return {
+        stop: async () => {
+            clearInterval(timer);
+            await busy;
+            return sent;
+        },
+    };
+}
+/** What a connected tab says about itself, as far as picking one goes. */
+/** The refusal a drive gets when every connected tab belongs to some other project. */
+export const NO_OWN_TAB = "No tab of this project is connected to Reticle on this machine, and a request is never run in another project's app. Open this project's app, then ask again.";
+/**
+ * `pickDriveSession` over the tabs of the project `apiKey` is for, or null when there are none. One
+ * daemon serves every project on the machine but polls with ONE credential, so without this a
+ * request made in project A drove project B's tab and sent pictures of it to A's chat.
+ */
+export async function pickOwnDriveSession(tabs, goal, apiKey, keyOf) {
+    const own = [];
+    for (const tab of tabs) {
+        const key = await keyOf(tab.sessionId).catch(() => undefined);
+        if (key === apiKey)
+            own.push(tab);
+    }
+    return pickDriveSession(own, goal) ?? null;
+}
+/** The address of an http(s) URL, `host:port`, for matching a tab to the app a request names. */
+const hostOf = (url) => {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return undefined;
+    }
+};
+const URLS_IN_TEXT = /https?:\/\/[^\s"'<>,]+/gi;
+/**
+ * The tab a chat-requested drive should use: one whose address the request names, then a visible
+ * one over a hidden (throttled) one, then the one heard from most recently.
+ */
+export function pickDriveSession(tabs, goal) {
+    const named = new Set((goal.match(URLS_IN_TEXT) ?? []).flatMap((url) => hostOf(url) ?? []));
+    const rank = (tab) => [
+        named.has(hostOf(tab.url) ?? '') ? 0 : 1,
+        tab.hidden ? 1 : 0,
+        tab.lastSeenMs,
+    ];
+    const better = (a, b) => {
+        for (let i = 0; i < a.length; i += 1) {
+            const x = a[i] ?? 0;
+            const y = b[i] ?? 0;
+            if (x !== y)
+                return x < y;
+        }
+        return false;
+    };
+    let best;
+    for (const tab of tabs)
+        if (best === undefined || better(rank(tab), rank(best)))
+            best = tab;
+    return best?.sessionId;
+}
+/**
+ * The verdict on a drive's goal: the platform's judgement of the goal when it made one, else the
+ * goals the harness checked itself. A drive that broke, proved nothing, or whose goal nobody judged
+ * is `unknown`: "it ran and nothing threw" is not "the goal was reached".
+ */
+export function driveVerdict(out) {
+    if (out.error !== undefined)
+        return 'unknown';
+    // A goal judged unmet, or a check that came back "no", is a failed drive whatever else held.
+    if (false === out.goalMet)
+        return 'no';
+    if (0 < (out.checks?.failed ?? 0))
+        return 'no';
+    // The quoted texts are looked for on the page the drive ENDED on. None there refutes the goal;
+    // some missing does not, because a goal that quotes where it starts ("from "Count is 0" to
+    // "Count is 1"") loses that text by working. Then the goal's own judgement decides, as below.
+    const goals = out.goals ?? [];
+    if (0 < goals.length && goals.every((g) => 'no' === g.verified))
+        return 'no';
+    if (0 < goals.length && !goals.some((g) => 'yes' === g.verified))
+        return 'unknown';
+    // A yes needs a check that held behind it: the model saying the goal was met is not evidence.
+    if (!out.proved || 0 === (out.checks?.held ?? 0))
+        return 'unknown';
+    if (true === out.goalMet)
+        return 'yes';
+    if (0 < goals.length && goals.every((g) => 'yes' === g.verified))
+        return 'yes';
+    return 'unknown';
+}

package/dist/features/harness/platform/script.d.ts

@@ -0,0 +1,48 @@
+import { ScriptStatus, type FlowFile, type FlowStep, type PlanView } from '@reticlehq/core';
+import { type DriveScript } from '@reticlehq/core/artifacts';
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface ScriptAsk {
+    about: string;
+    flows: readonly FlowFile[];
+    replay: readonly string[];
+    goals: readonly string[];
+    gaps: readonly string[];
+    rules: readonly string[];
+    /** Personas the project already drove; the platform proposes new ones only when there are none. */
+    personas?: readonly {
+        name: string;
+        journey: string;
+    }[];
+}
+/**
+ * The personas earlier drives used, read from their flows' intents (`Name: journey`). Proposed
+ * afresh on every run, they were different people each time, so each run's flows had new names
+ * and the old ones were never replayed or updated.
+ */
+export declare function personasIn(flows: readonly FlowFile[]): {
+    name: string;
+    journey: string;
+}[];
+/** Equal for two steps that drive the same control the same way; the values never leave. */
+export declare function stepHash(step: FlowStep): string;
+export declare function proposeScript(platform: {
+    url: string;
+    apiKey: string;
+}, ask: ScriptAsk, doFetch?: FetchLike): Promise<{
+    script: DriveScript;
+    planId?: string;
+} | undefined>;
+/** One journey's outcome, as the platform keeps it beside the plan. */
+export interface JourneyResult {
+    id: string;
+    title: string;
+    status: ScriptStatus;
+}
+/** How each journey of a run plan went, once each. */
+export declare function journeyResults(view: PlanView): JourneyResult[];
+/** Tell the platform how its plan went. A failure costs the next plan its memory, never this run. */
+export declare function reportPlanResults(platform: {
+    url: string;
+    apiKey: string;
+}, planId: string, results: readonly JourneyResult[], doFetch?: FetchLike): Promise<boolean>;
+export {};

package/dist/features/harness/platform/script.js

@@ -0,0 +1,128 @@
+/**
+ * The drive plan, asked of the platform.
+ *
+ * The platform plans the whole drive: it proposes the personas, orders the saved flows, finds the
+ * shared starts to branch from and writes the product's rules into each open journey. What it is
+ * sent is what the project already knows, and each saved step goes as a short hash, never its values,
+ * which is all a plan needs to tell two steps apart.
+ *
+ * The answer is not trusted: it must parse as a drive script and pass the same checks a local plan
+ * does, or it is dropped and the daemon plans locally.
+ *
+ * The platform keeps every plan under an id, and is told afterwards how each journey went: that is
+ * what the next plan learns from (what failed is driven first).
+ */
+import { createHash } from 'node:crypto';
+import { ScriptStatus, StepEffect, } from '@reticlehq/core';
+import { DriveScriptSchema, checkScript } from '@reticlehq/core/artifacts';
+const SCRIPTS_PATH = '/v1/harness/scripts';
+const RESULTS_PATH = '/results';
+const TIMEOUT_MS = 90_000;
+/** Characters of a step hash: enough to tell a flow's steps apart, too few to carry anything. */
+const STEP_HASH_CHARS = 12;
+/** How long a persona's name may be, read back out of a flow's intent. */
+const MAX_PERSONA_NAME = 80;
+const MAX_PERSONAS = 5;
+/**
+ * The personas earlier drives used, read from their flows' intents (`Name: journey`). Proposed
+ * afresh on every run, they were different people each time, so each run's flows had new names
+ * and the old ones were never replayed or updated.
+ */
+export function personasIn(flows) {
+    const seen = new Map();
+    for (const flow of flows) {
+        // The first line only: an older drive saved the product's rules below the journey.
+        const intent = (flow.intent ?? '').split('\n')[0] ?? '';
+        const at = intent.indexOf(':');
+        if (at <= 0 || MAX_PERSONA_NAME < at)
+            continue;
+        const name = intent.slice(0, at).trim();
+        const journey = intent.slice(at + 1).trim();
+        if (0 < name.length && 0 < journey.length && !seen.has(name))
+            seen.set(name, journey);
+    }
+    return [...seen].slice(0, MAX_PERSONAS).map(([name, journey]) => ({ name, journey }));
+}
+/** Equal for two steps that drive the same control the same way; the values never leave. */
+export function stepHash(step) {
+    return createHash('sha256')
+        .update(JSON.stringify([step.tool, step.anchor, step.action, step.args, step.steps, step.invoke]))
+        .digest('hex')
+        .slice(0, STEP_HASH_CHARS);
+}
+export async function proposeScript(platform, ask, doFetch = (url, init) => fetch(url, init)) {
+    try {
+        const res = await doFetch(`${platform.url}${SCRIPTS_PATH}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${platform.apiKey}` },
+            body: JSON.stringify({
+                about: ask.about,
+                flows: ask.flows.map((flow) => ({
+                    name: flow.name,
+                    ...(flow.intent === undefined ? {} : { intent: flow.intent }),
+                    needs: flow.needs ?? [],
+                    steps: flow.steps.map(stepHash),
+                    commits: flow.steps.flatMap((step, i) => (StepEffect.COMMITS === step.effect ? [i] : [])),
+                    // How much it proves: a journey whose flows assert nothing is driven again, not replayed.
+                    checks: flow.steps.filter((step) => step.expect !== undefined || true === step.steps?.some((s) => s.expect !== undefined)).length,
+                })),
+                replay: ask.replay,
+                goals: ask.goals,
+                gaps: ask.gaps,
+                rules: ask.rules,
+                ...(ask.personas === undefined || 0 === ask.personas.length
+                    ? {}
+                    : { personas: ask.personas }),
+            }),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        const parsed = DriveScriptSchema.safeParse(body.script);
+        if (!parsed.success || 0 < checkScript(parsed.data).length)
+            return undefined;
+        return {
+            script: parsed.data,
+            ...('string' === typeof body.planId ? { planId: body.planId } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Worst first: a journey that ran in two lanes reports the worse of the two. */
+const SEVERITY = [
+    ScriptStatus.FAILED,
+    ScriptStatus.BLOCKED,
+    ScriptStatus.RUNNING,
+    ScriptStatus.PENDING,
+    ScriptStatus.NOT_TAKEN,
+    ScriptStatus.PASSED,
+];
+/** How each journey of a run plan went, once each. */
+export function journeyResults(view) {
+    const byId = new Map();
+    for (const lane of view.lanes)
+        for (const card of lane.journeys) {
+            const seen = byId.get(card.id);
+            if (seen === undefined || SEVERITY.indexOf(card.status) < SEVERITY.indexOf(seen.status))
+                byId.set(card.id, { id: card.id, title: card.title, status: card.status });
+        }
+    return [...byId.values()];
+}
+/** Tell the platform how its plan went. A failure costs the next plan its memory, never this run. */
+export async function reportPlanResults(platform, planId, results, doFetch = (url, init) => fetch(url, init)) {
+    try {
+        const res = await doFetch(`${platform.url}${SCRIPTS_PATH}/${encodeURIComponent(planId)}${RESULTS_PATH}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${platform.apiKey}` },
+            body: JSON.stringify({ results }),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/features/harness/platform/server-driver.d.ts

@@ -0,0 +1,41 @@
+import { type ModelDriver } from '../harness.js';
+export declare const SERVER_DRIVER_NAME = "server";
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface ServerDriverOptions {
+    url: string;
+    apiKey: string;
+    persona?: string;
+    /** The goal a drive with no persona is for: the platform names its flows after it. */
+    journey?: string;
+    /** journey | brute-force | stress | madman | security. The platform defaults to journey. */
+    mode?: string;
+    /** What `.reticle` already knows, as text: saved journeys and open intents. */
+    plan?: string;
+    /** The same plan, structured, for the platform's Jev engine. */
+    planSteps?: readonly {
+        kind: string;
+        target: string;
+        why: string;
+    }[];
+    /** The signal names the app declares, so the engine can claim one by name. */
+    vocabulary?: readonly string[];
+    /** Where secret field values live. Only their NAMES go to the platform. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    maxSteps?: number;
+    fetch?: FetchLike;
+}
+/** The platform's url and this project's key, when the machine is linked. */
+export declare function serverOptionsFromEnv(env: Record<string, string | undefined>): {
+    url: string;
+    apiKey: string;
+} | undefined;
+export declare class ServerHarnessError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function serverDriver(options: ServerDriverOptions): ModelDriver;
+/** The secret fields this machine can fill, by name only. */
+export declare function secretNames(env: Record<string, string | undefined>): string[];
+/** The call's arguments with every secret placeholder replaced by its value from this machine. */
+export declare function withSecrets(args: Record<string, unknown>, env: Record<string, string | undefined>): Record<string, unknown>;
+export {};