@reticlehq/server 3.5.0 → 3.6.0

package/dist/features/harness/platform/local-apps.d.ts

@@ -0,0 +1,94 @@
+import { type LinkCapability, type LinkNotice } from '@reticlehq/core';
+import { type DriveCandidate } from './remote-drive.js';
+/** How often apps are reported. The platform counts an app live for two and a half of these. */
+export declare const LOCAL_APPS_REPORT_MS = 10000;
+/** How long a drive waits for an app it opened to connect before it is refused. */
+export declare const APP_OPEN_WAIT_MS = 20000;
+export interface Platform {
+    url: string;
+    apiKey: string;
+}
+export interface Machine {
+    id: string;
+    name: string;
+}
+/** One connected tab, as far as reporting and picking go. */
+export interface AppTab extends DriveCandidate {
+    title?: string;
+    projectId?: string;
+    adapters: string[];
+    runtime?: string;
+}
+export interface ReportedApp {
+    key: string;
+    name: string;
+    url: string;
+    title?: string;
+    stack: string[];
+}
+/** This machine: a stable id that is not its home path, and the name a person knows it by. */
+export declare const machineOf: (hostname: string, home: string) => Machine;
+/**
+ * One project checkout on one machine. Its port is not part of it. The tab's projectId is: a daemon
+ * that cannot map a project to its checkout files every such project under one shared directory.
+ */
+export declare const appKeyOf: (machineId: string, projectDir: string, projectId: string | undefined) => string;
+/** What a refused open is told. */
+export declare const NOT_AN_APP_ADDRESS = "Reticle only opens a web address on this machine or one of the apps already open here.";
+/**
+ * Whether the daemon may open an address the platform named: a web page on this machine, or one on
+ * an origin a connected tab already has. Never a file, and never anywhere else on the network.
+ */
+export declare function mayOpen(url: string, openUrls: readonly string[]): boolean;
+/** A project id as a name: the SDK stamps `<package>-<8 hex>`, and the hash means nothing to a person. */
+export declare const nameFromProjectId: (projectId: string) => string;
+/**
+ * The apps to report, grouped by the platform credential each one's project is linked with. The
+ * linked credential is reported even with no app open: it is how the chat knows the machine is there
+ * to open one. A tab whose project is not linked is left out: no chat can drive it.
+ */
+export declare function appsByPlatform(tabs: readonly AppTab[], linked: Platform | undefined, machineId: string, describe: (tab: AppTab) => Promise<{
+    platform?: Platform;
+    dir: string;
+    name: string;
+}>): Promise<{
+    platform: Platform;
+    apps: ReportedApp[];
+}[]>;
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface AppReportDeps {
+    machine: Machine;
+    version: string;
+    /** What this daemon can do for the platform: it offers a person only what is here. */
+    capabilities: readonly LinkCapability[];
+    apps: () => Promise<{
+        platform: Platform;
+        apps: ReportedApp[];
+    }[]>;
+    /** Open an app so it connects: one somebody asked to bring back. A throw is logged, never fatal. */
+    open: (url: string) => Promise<void>;
+    /** A drive is waiting for the project this credential is for. */
+    drivePending: (platform: Platform) => void;
+    /**
+     * Something the platform wants the person told ("update Reticle"), for the project this credential
+     * is for. Called once per notice for the daemon's life, however often the platform repeats it.
+     */
+    notify?: (notice: LinkNotice, platform: Platform) => void;
+    fetch?: FetchLike;
+    intervalMs?: number;
+    log?: (line: string) => void;
+}
+export interface AppReports {
+    tick: () => Promise<void>;
+    stop: () => void;
+}
+export declare function startAppReports(deps: AppReportDeps): AppReports;
+/**
+ * The tab a drive the chat attached to one app uses: a tab of that app and no other, even on the
+ * same port. None open: open the app, and wait for it to connect. Null when it never does.
+ */
+export declare function pickAppTab(app: {
+    key: string;
+    url: string | null;
+}, goal: string, tabs: () => readonly AppTab[], keyOf: (sessionId: string) => string | undefined, open: (url: string) => Promise<void>, waitMs?: number): Promise<string | null>;
+export {};

package/dist/features/harness/platform/local-apps.js

@@ -0,0 +1,204 @@
+/**
+ * The apps this machine has connected, told to the platform so its chat can list them by name.
+ *
+ * The chat used to ask for a `localhost` address, and an address names nothing: two projects on
+ * `localhost:3000` are one address, and one project restarted on another port is two. So an app here
+ * is a project checkout on a machine, keyed by a hash of both, and its address is only where it was
+ * last open. Neither the project's path nor the home directory leaves the machine, only their hash.
+ *
+ * Every few seconds, with or without an app open, each linked project's credential reports its apps.
+ * The answer can name apps somebody asked to bring back (opened here, headless) and say a drive is
+ * waiting, which is how a daemon with nothing open hears about one without polling every few seconds.
+ */
+import { createHash } from 'node:crypto';
+import { LinkPath, PLATFORM_LINK_VERSION, RETICLE_URL_PARAM, parseLinkNotices, } from '@reticlehq/core';
+import { pickDriveSession } from './remote-drive.js';
+/** How often apps are reported. The platform counts an app live for two and a half of these. */
+export const LOCAL_APPS_REPORT_MS = 10_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+/** How long a drive waits for an app it opened to connect before it is refused. */
+export const APP_OPEN_WAIT_MS = 20_000;
+const APP_OPEN_POLL_MS = 250;
+const KEY_LENGTH = 16;
+/** The shell a plain browser tab reports: not worth a word on a card that says what it is built with. */
+const WEB_RUNTIME = 'web';
+const hash = (text) => createHash('sha256').update(text).digest('hex').slice(0, KEY_LENGTH);
+/** This machine: a stable id that is not its home path, and the name a person knows it by. */
+export const machineOf = (hostname, home) => ({
+    id: hash(`${hostname}\u0000${home}`),
+    name: hostname.replace(/\.local$/i, ''),
+});
+/**
+ * One project checkout on one machine. Its port is not part of it. The tab's projectId is: a daemon
+ * that cannot map a project to its checkout files every such project under one shared directory.
+ */
+export const appKeyOf = (machineId, projectDir, projectId) => hash(`${machineId}\u0000${projectDir}\u0000${projectId ?? ''}`);
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** What a refused open is told. */
+export const NOT_AN_APP_ADDRESS = 'Reticle only opens a web address on this machine or one of the apps already open here.';
+/**
+ * Whether the daemon may open an address the platform named: a web page on this machine, or one on
+ * an origin a connected tab already has. Never a file, and never anywhere else on the network.
+ */
+export function mayOpen(url, openUrls) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if ('http:' !== target.protocol && 'https:' !== target.protocol)
+        return false;
+    if (LOOPBACK_HOSTS.has(target.hostname) || target.hostname.endsWith('.localhost'))
+        return true;
+    return openUrls.some((open) => {
+        try {
+            return new URL(open).origin === target.origin;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** A project id as a name: the SDK stamps `<package>-<8 hex>`, and the hash means nothing to a person. */
+export const nameFromProjectId = (projectId) => projectId.replace(/-[0-9a-f]{8}$/, '');
+const RETICLE_MARKS = new Set(Object.values(RETICLE_URL_PARAM));
+/** The address as the app knows it: the params Reticle put on it to adopt a tab are not the app's. */
+const withoutMarks = (raw) => {
+    try {
+        const url = new URL(raw);
+        for (const mark of [...url.searchParams.keys()])
+            if (RETICLE_MARKS.has(mark))
+                url.searchParams.delete(mark);
+        return url.href;
+    }
+    catch {
+        return raw;
+    }
+};
+/**
+ * The apps to report, grouped by the platform credential each one's project is linked with. The
+ * linked credential is reported even with no app open: it is how the chat knows the machine is there
+ * to open one. A tab whose project is not linked is left out: no chat can drive it.
+ */
+export async function appsByPlatform(tabs, linked, machineId, describe) {
+    const groups = new Map();
+    const group = (platform) => {
+        const id = `${platform.url}\u0000${platform.apiKey}`;
+        const found = groups.get(id) ?? { platform, apps: new Map() };
+        groups.set(id, found);
+        return found;
+    };
+    if (undefined !== linked)
+        group(linked);
+    // A visible tab speaks for its project over a hidden one.
+    const ordered = [...tabs].sort((a, b) => Number(a.hidden) - Number(b.hidden));
+    for (const tab of ordered) {
+        const about = await describe(tab).catch(() => undefined);
+        if (undefined === about?.platform)
+            continue;
+        const key = appKeyOf(machineId, about.dir, tab.projectId);
+        const apps = group(about.platform).apps;
+        if (apps.has(key))
+            continue;
+        const stack = [
+            ...new Set([...tab.adapters, ...(tab.runtime === undefined ? [] : [tab.runtime])]),
+        ].filter((part) => WEB_RUNTIME !== part);
+        apps.set(key, {
+            key,
+            name: about.name,
+            url: withoutMarks(tab.url),
+            ...(tab.title === undefined ? {} : { title: tab.title }),
+            stack,
+        });
+    }
+    return [...groups.values()].map(({ platform, apps }) => ({ platform, apps: [...apps.values()] }));
+}
+export function startAppReports(deps) {
+    const doFetch = deps.fetch ?? ((url, init) => fetch(url, init));
+    let busy = false;
+    /** Notices already shown, by what they say: the platform repeats them on every report. */
+    const told = new Set();
+    const tick = async () => {
+        if (busy)
+            return;
+        busy = true;
+        try {
+            for (const { platform, apps } of await deps.apps()) {
+                try {
+                    const res = await doFetch(`${platform.url}${LinkPath.APPS}`, {
+                        method: 'POST',
+                        headers: {
+                            'content-type': 'application/json',
+                            authorization: `Bearer ${platform.apiKey}`,
+                        },
+                        body: JSON.stringify({
+                            machine: deps.machine,
+                            reticleVersion: deps.version,
+                            protocol: PLATFORM_LINK_VERSION,
+                            capabilities: deps.capabilities,
+                            apps,
+                        }),
+                        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                    });
+                    if (!res.ok)
+                        continue;
+                    const answer = (await res.json());
+                    for (const notice of parseLinkNotices(answer.notices)) {
+                        const key = `${platform.apiKey}\u0000${notice.text}`;
+                        if (told.has(key))
+                            continue;
+                        told.add(key);
+                        deps.notify?.(notice, platform);
+                    }
+                    const open = new Set(apps.map((app) => app.key));
+                    for (const wake of Array.isArray(answer.wake) ? answer.wake : []) {
+                        const { key, url } = (wake ?? {});
+                        if ('string' !== typeof key || 'string' !== typeof url || open.has(key))
+                            continue;
+                        open.add(key);
+                        deps.log?.(`reticle: opening ${url}, asked for from the platform chat`);
+                        await deps.open(url).catch((error) => {
+                            deps.log?.(`reticle: could not open ${url}: ${String(error)}`);
+                        });
+                    }
+                    if (true === answer.pendingDrive)
+                        deps.drivePending(platform);
+                }
+                catch {
+                    // Offline, or the platform is down: the next report tries again.
+                }
+            }
+        }
+        catch {
+            // The credentials could not be read: nothing to report this time.
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const timer = setInterval(() => void tick(), deps.intervalMs ?? LOCAL_APPS_REPORT_MS);
+    timer.unref();
+    return { tick, stop: () => clearInterval(timer) };
+}
+/**
+ * The tab a drive the chat attached to one app uses: a tab of that app and no other, even on the
+ * same port. None open: open the app, and wait for it to connect. Null when it never does.
+ */
+export async function pickAppTab(app, goal, tabs, keyOf, open, waitMs = APP_OPEN_WAIT_MS) {
+    const ofApp = () => tabs().filter((tab) => keyOf(tab.sessionId) === app.key);
+    const now = pickDriveSession(ofApp(), goal);
+    if (now !== undefined)
+        return now;
+    if (null === app.url)
+        return null;
+    await open(app.url).catch(() => undefined);
+    for (let waited = 0; waited <= waitMs; waited += APP_OPEN_POLL_MS) {
+        const opened = pickDriveSession(ofApp(), goal);
+        if (opened !== undefined)
+            return opened;
+        await new Promise((resolve) => setTimeout(resolve, APP_OPEN_POLL_MS));
+    }
+    return null;
+}

package/dist/features/harness/platform/remote-drive.d.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 { PresenterTone, type DriveApplied, type DriveSpec, type SpecIgnored } from '@reticlehq/core';
+/** The app the chat attached a drive to: `local-apps.ts`'s key, and where it was last open. */
+export interface AttachedApp {
+    key: string;
+    url: string | null;
+}
+/**
+ * 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 declare const REMOTE_DRIVE_POLL_MS = 3000;
+/**
+ * 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 declare const REMOTE_DRIVE_FRAME_MS = 1000;
+/** The same JPEG quality the platform's own checks film at: about 40 KB a picture. */
+export declare const REMOTE_DRIVE_JPEG_QUALITY = 50;
+/** What the driven tab's HUD says once a chat-requested drive is over. */
+export declare const REMOTE_DRIVE_ENDED: {
+    readonly PROVED: "Harness drive finished: proved";
+    readonly 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 declare function endDrivenTab(tab: {
+    autoEnd(text: string, tone: PresenterTone): void;
+} | undefined, outcome: RemoteDriveOutcome): void;
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface RemoteDriveOutcome {
+    ok: boolean;
+    summary: string;
+    /** The verdict on the goal (see `driveVerdict`), so the platform keeps the drive as a check. */
+    verdict?: DriveVerdict;
+    /** The address the drive was on, for the check the platform keeps. */
+    url?: string;
+    /** The runs this drive syncs as, so the platform shows the drive once. */
+    runIds?: readonly string[];
+    /**
+     * Whether any picture of the drive reached the platform. False for a drive in the person's own
+     * tab, which only the SDK reaches and no camera does, so the chat can say why there is no video.
+     * Set by `startRemoteDrives`, never by the drive.
+     */
+    filmed?: boolean;
+}
+export type DriveVerdict = 'yes' | 'no' | 'unknown';
+export interface RemoteDriveDeps {
+    /** The environment with this machine's linked credential in it, resolved on every ask. */
+    env: () => Promise<Record<string, string | undefined>>;
+    /** Whether an app is connected to drive. */
+    connected: () => boolean;
+    /**
+     * The tab to drive for `goal`, or undefined to let the drive choose. One tab, picked once and used
+     * for the whole drive and its pictures: with two tabs open, a drive that names none is refused on
+     * every call ("multiple sessions connected"), and the pictures would be of whichever tab was asked.
+     * Null: no connected tab belongs to the project `apiKey` is for, so the drive is refused.
+     * `app`: the app the chat attached the drive to, when it named one; only its tabs may be driven.
+     */
+    pick?: (goal: string, apiKey: string, app?: AttachedApp) => Promise<string | null | undefined> | string | undefined;
+    /**
+     * Make ready the tab a drive with a spec runs in: the person's own (as `pick` would choose it) or
+     * one opened for it, headless or in a window, with the HUD as the spec asks. Answers what it applied
+     * and what it could not. A null `sessionId` refuses the drive, as a null from `pick` does.
+     * Absent: `pick` chooses, and the spec's other fields are reported as unavailable.
+     */
+    prepare?: (drive: {
+        goal: string;
+        apiKey: string;
+        app?: AttachedApp;
+        spec: DriveSpec;
+    }) => Promise<{
+        sessionId: string | null | undefined;
+        applied: DriveApplied;
+        ignored: SpecIgnored[];
+        /** Why the drive cannot run, said to the person instead of the no-tab refusal. */
+        refusal?: string;
+    }>;
+    /**
+     * Reticle's tools on the driven tab, for a drive the platform orchestrates. Absent: a platform
+     * drive is refused, and this daemon does not report the tool-session capability.
+     */
+    session?: (sessionId: string | undefined) => {
+        /** What it can run, as the model is shown each tool: sent once, on the first ask. */
+        tools?: readonly {
+            name: string;
+            description: string;
+            inputSchema: Record<string, unknown>;
+        }[];
+        invoke: (tool: string, args: Record<string, unknown>) => Promise<unknown>;
+    };
+    /** The clock for how long each session call took. */
+    now?: () => number;
+    /** How a session ask waits before it is sent again. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Drive the app toward `goal`, in `sessionId`. A throw is reported as a failed drive, in its own words. */
+    drive: (goal: string, sessionId: string | undefined) => Promise<RemoteDriveOutcome>;
+    /**
+     * What the driven tab shows now, as a JPEG, or undefined when it cannot be captured (a tab this
+     * daemon did not launch). Absent: the drive runs with no picture, and the chat shows its steps.
+     */
+    frame?: (sessionId: string | undefined) => Promise<Uint8Array | undefined>;
+    frameIntervalMs?: number;
+    /**
+     * Called once the drive is over, however it ended, so the driven tab's HUD stops reading
+     * "planning next action". Nothing else tells it: the drive has no agent to end its session.
+     */
+    settle?: (sessionId: string | undefined, outcome: RemoteDriveOutcome) => void;
+    fetch?: FetchLike;
+    intervalMs?: number;
+    /** A line for the daemon log. */
+    log?: (line: string) => void;
+}
+export interface RemoteDrives {
+    /**
+     * One ask, now. Resolves once any drive it took has been reported. With `platform`, ask with that
+     * credential whether or not an app is connected: the platform said a drive is waiting for it.
+     */
+    tick: (platform?: {
+        url: string;
+        apiKey: string;
+    }) => Promise<void>;
+    stop: () => void;
+}
+export declare function startRemoteDrives(deps: RemoteDriveDeps): RemoteDrives;
+/** 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 declare 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 declare function pickOwnDriveSession(tabs: readonly DriveCandidate[], goal: string, apiKey: string, keyOf: (sessionId: string) => Promise<string | undefined>): Promise<string | null>;
+export interface DriveCandidate {
+    sessionId: string;
+    url: string;
+    lastSeenMs: number;
+    hidden: boolean;
+}
+/**
+ * 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 declare function pickDriveSession(tabs: readonly DriveCandidate[], goal: string): string | undefined;
+/**
+ * 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 declare function driveVerdict(out: {
+    goalMet?: boolean;
+    proved: boolean;
+    error?: string;
+    goals?: readonly {
+        verified: string;
+    }[];
+    /** How the drive's checks came out. `proved` only says one RAN; this says what each answered. */
+    checks?: {
+        held: number;
+        failed: number;
+        undecided: number;
+    };
+}): DriveVerdict;
+export {};