@contraagent/api 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @contraagent/api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed client for the contraagent monitor's HTTP API: types generated from the
+monitor's OpenAPI document, a REST client, the two live feeds, and a store that
+folds a run's feed into one typed state. No UI: `@contraagent/ui` draws it.
+
+The types are generated from the monitor's pydantic models via OpenAPI, so a
+field the server removes fails your type check, not your page.
+
+A `::code` line quotes a file of the package; the [documentation site](https://t-tani.github.io/contraagent/) shows the quoted lines in place. The same declarations, with their comments, are in `dist/**/*.d.ts`.
+
+## Getting it
+
+The package is not in the npm registry; install it from a checkout of the
+repository. Every monitor also serves the client, the feeds and the store as
+exports of its `/app.js` (`@contraagent/ui`'s documentation).
+
+## Use it from a checkout
+
+In the repository's `web/` (Node 22, pnpm through `corepack enable`):
+
+```
+pnpm install && pnpm tarballs
+```
+
+`pnpm tarballs` builds the packages and writes one `.tgz` file for each to
+`web/tarballs/`. Then, in your project, with npm or pnpm:
+
+```
+npm install <checkout>/web/tarballs/contraagent-api-*.tgz
+pnpm add <checkout>/web/tarballs/contraagent-api-*.tgz
+```
+
+## Types
+
+Every response and feed message has a type, with readable aliases:
+`JournalRow`, `RunSummary`, `Plan`, `Outputs`, `TaskDetail`, `StreamPage`,
+`TranscriptEvent`, and so on. Fields the server may leave out are optional.
+Closed vocabularies are unions: `Stop` (how an attempt ended, `JournalRow['stop']`),
+`TaskState`, `ContractStatus`.
+
+The live feeds are discriminated unions on the SSE event name, so a `switch` on
+`msg.event` narrows `msg.data`:
+
+::code{file="src/run-state.ts" from="export function reduceRun" to="// --- selectors"}
+
+## The client
+
+`createMonitorClient({ baseUrl })` has one typed method per JSON endpoint
+(`src/client.ts`); each throws `ApiError` when it gets no JSON answer: its
+`failure` is `network`, `status` or `not-json` (such as an HTML page from a
+server without the API), with the `url`, `status` and media `type`.
+
+## The live feeds
+
+- `openRunFeed(run, panels, handlers)`: the run, live. On every (re)connect the
+  server replays the whole journal and then sends `ready`; every message after
+  `ready` is new.
+- `openStreamFeed(run, key, handlers)`: one transcript, tailed: the tail page
+  first, then only what is new.
+
+Each returns a function that closes it.
+
+## An export
+
+An export (`contraagent monitor export`) is the monitor's views of some runs,
+written as files and read with no server. `createExportClient(url)` is a client of
+its `data/` directory: the same methods as the server's client, each read from its
+file. `openExportFeed(client)` is the run feed for it: it plays a run's files once
+and ends with `ready`. Give both to `MonitorStore` (`client` and `openRunFeed`) to
+read an export as a server is read.
+
+## The store
+
+`MonitorStore` keeps the run list fresh, opens the selected run's feed, folds
+its messages into one `RunState`, and tells subscribers. It knows nothing of
+any UI framework: a Lit controller, a React hook or plain code subscribe alike.
+Its snapshot's `error` is the `ApiError` of the last request for the title or
+the run list that got no answer, and
+`runsLoaded` says the run list has been answered.
+The reducer behind it, `reduceRun(state, actions)`, is pure: use it with your
+own state management if you prefer. `@contraagent/ui`'s documentation shows
+the store feeding its elements.
+
+## Tasks and their outcomes
+
+A task is one task key. `deriveRun(journal, plan)` gives what every view counts
+and lists about the run's tasks, computed once per state (the same `journal` and
+`plan` objects give the same result):
+
+- `outcomes` and `rows`: every task of the run, the plan joined with the
+  journal, with its outcome (`done`, `recovered`, `partial`, `failed`,
+  `not_started`, `running`, `waiting`, `skipped`; `partial`: ok, its output a
+  placeholder, neither done nor failed);
+- `counts`: tasks by outcome, `doneTotal` (done and recovered: "N of M tasks
+  done") and `finished` (done, recovered, partial and skipped);
+- `problems`: failed tasks with the tasks they stopped, tasks not started for a
+  reason of their own, and recovered tasks;
+- `kinds` and `tries`.
+
+`latestTask(rows)` is the task a page opens by default. A refusal before launch
+(`invalid_input`) is not a try: a task refused and then done is `done`, not
+`recovered`.

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+import type { Hosts, Info, JournalPage, JsonObject, RunSummary, StreamPage, TaskDefinition, TaskDetail, Trends, TrendsQuery } from './types.js';
+/**
+ * Why a request got no JSON answer: `network`, no response (a network error, a
+ * refused connection, or a cross-origin response the browser blocked);
+ * `status`, a status outside 2xx; `not-json`, a body that is not JSON (empty,
+ * or the HTML page a development server answers every path with).
+ */
+export type ApiFailure = 'network' | 'status' | 'not-json';
+/**
+ * A request to the monitor's API that got no JSON answer. Its message states
+ * the URL, the failure, the status and the media type
+ * ("No JSON answer from http://host/api/runs: not-json 200 text/html");
+ * `@contraagent/ui` words it for the reader.
+ */
+export declare class ApiError extends Error {
+    /** The URL requested. */
+    readonly url: string;
+    readonly failure: ApiFailure;
+    /** The response's status; 0 with no response. */
+    readonly status: number;
+    /** The response's media type, such as `text/html`; '' when it states none. */
+    readonly type: string;
+    constructor(
+    /** The URL requested. */
+    url: string, failure: ApiFailure, 
+    /** The response's status; 0 with no response. */
+    status?: number, 
+    /** The response's media type, such as `text/html`; '' when it states none. */
+    type?: string);
+}
+export interface ClientOptions {
+    /** Where the monitor is served; '' (the default) is the page's own origin. */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+/** Typed calls for every JSON endpoint of the monitor. Each throws `ApiError` when it gets no JSON answer. */
+export interface MonitorClient {
+    readonly baseUrl: string;
+    info(): Promise<Info>;
+    runs(): Promise<RunSummary[]>;
+    /** The hosts behind the runs (a hub: `Info.hosts`). */
+    hosts(): Promise<Hosts>;
+    journal(run: string, since?: number): Promise<JournalPage>;
+    definitions(run: string): Promise<TaskDefinition[]>;
+    task(run: string, key: string): Promise<TaskDetail>;
+    stream(run: string, key: string, since?: number): Promise<StreamPage>;
+    panel(run: string, name: string): Promise<JsonObject>;
+    /** What the runs of a period add up to. */
+    trends(query?: TrendsQuery): Promise<Trends>;
+    /** A trend panel's body over the runs of a period (`Panel(scope="trends")`). */
+    trendsPanel(name: string, query?: TrendsQuery): Promise<JsonObject>;
+}
+export declare function createMonitorClient(options?: ClientOptions): MonitorClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,KAAK,EACL,IAAI,EACJ,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,UAAU,EACV,MAAM,EACN,WAAW,EAEZ,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAE/B,yBAAyB;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,OAAO,EAAE,UAAU;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,MAAM;IACf,8EAA8E;IAC9E,QAAQ,CAAC,IAAI;;IANb,yBAAyB;IAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,UAAU;IAC5B,iDAAiD;IACxC,MAAM,SAAI;IACnB,8EAA8E;IACrE,IAAI,SAAK;CAKrB;AAED,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,8GAA8G;AAC9G,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC9B,uDAAuD;IACvD,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACpD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtD,2CAA2C;IAC3C,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,gFAAgF;IAChF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACrE;AAWD,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,aAAkB,GAAG,aAAa,CAyC9E"}

package/dist/client.js

@@ -0,0 +1,68 @@
+/**
+ * A request to the monitor's API that got no JSON answer. Its message states
+ * the URL, the failure, the status and the media type
+ * ("No JSON answer from http://host/api/runs: not-json 200 text/html");
+ * `@contraagent/ui` words it for the reader.
+ */
+export class ApiError extends Error {
+    constructor(
+    /** The URL requested. */
+    url, failure, 
+    /** The response's status; 0 with no response. */
+    status = 0, 
+    /** The response's media type, such as `text/html`; '' when it states none. */
+    type = '') {
+        super(`No JSON answer from ${url}: ${failure} ${status} ${type}`.trim());
+        this.url = url;
+        this.failure = failure;
+        this.status = status;
+        this.type = type;
+        this.name = 'ApiError';
+    }
+}
+export function createMonitorClient(options = {}) {
+    const baseUrl = (options.baseUrl ?? '').replace(/\/$/, '');
+    const origin = (baseUrl || globalThis.location?.origin || '').replace(/\/$/, '');
+    const fetch = options.fetch ?? globalThis.fetch;
+    /** The JSON answer of GET `endpoint`; `ApiError` when there is none. */
+    async function get(endpoint, params) {
+        const { path = {}, query = {} } = (params ?? {});
+        const url = origin + endpoint.replace(/\{(\w+)\}/g, (part, name) => (name in path ? encodeURIComponent(path[name]) : part));
+        const search = Object.entries(query)
+            .filter(([, v]) => v !== undefined && v !== null)
+            .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+            .join('&');
+        const target = search ? `${url}?${search}` : url;
+        let response;
+        try {
+            response = await fetch(new Request(target));
+        }
+        catch {
+            throw new ApiError(target, 'network');
+        }
+        const { status, ok } = response;
+        const type = (response.headers.get('Content-Type') ?? '').split(';')[0].trim().toLowerCase();
+        try {
+            if (ok)
+                return (await response.json());
+        }
+        catch {
+            // An empty body, an HTML page, or text that is not JSON.
+        }
+        throw new ApiError(target, ok ? 'not-json' : 'status', status, type);
+    }
+    return {
+        baseUrl,
+        info: () => get('/api/info'),
+        runs: () => get('/api/runs'),
+        hosts: () => get('/api/hosts'),
+        journal: (run, since = 0) => get('/api/runs/{run}/journal', { path: { run }, query: { since } }),
+        definitions: (run) => get('/api/runs/{run}/definitions', { path: { run } }),
+        task: (run, key) => get('/api/runs/{run}/task/{key}', { path: { run, key } }),
+        stream: (run, key, since = 0) => get('/api/runs/{run}/stream/{key}', { path: { run, key }, query: { since } }),
+        panel: (run, name) => get('/api/runs/{run}/panels/{name}', { path: { run, name } }),
+        trends: (query = {}) => get('/api/trends', { query: { ...query } }),
+        trendsPanel: (name, query = {}) => get('/api/trends/panels/{name}', { path: { name }, query: { ...query } }),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/derive.d.ts

@@ -0,0 +1,81 @@
+import type { Outcome, Problems, TaskOutcome, TaskRow } from './outcomes.js';
+import type { HostSummary, JournalRow, Plan, RunSummary } from './types.js';
+export interface RunCounts extends Record<Outcome, number> {
+    total: number;
+    /** done + recovered: "N of M tasks done" in every view. */
+    doneTotal: number;
+    /** done + recovered + partial + skipped: nothing is left to do. */
+    finished: number;
+}
+/** Tries (journal rows that ran) and rows of tasks that never started (a refusal, a skip). */
+export interface TryCounts {
+    tries: number;
+    notStarted: number;
+}
+export interface RunDerived {
+    /** Every task of the run, by key: the plan joined with the journal. */
+    outcomes: ReadonlyMap<string, TaskOutcome>;
+    /** The same tasks as rows, in plan order. */
+    rows: readonly TaskRow[];
+    counts: RunCounts;
+    problems: Problems;
+    /** The tasks' kinds, sorted. */
+    kinds: readonly string[];
+    tries: TryCounts;
+}
+/**
+ * What the views show about a run's tasks. Without a plan, the tasks are the
+ * journal's only. The same `journal` and `plan` objects give the same result object.
+ */
+export declare function deriveRun(journal: readonly JournalRow[], plan?: Plan | null | undefined): RunDerived;
+/** Tries (journal rows that ran) and rows of tasks that never started: the one way the UI counts them. */
+export declare function tryCounts(journal: readonly JournalRow[]): TryCounts;
+export interface Progress {
+    total: number;
+    /** Plan state `done`: done and done after retrying. */
+    done: number;
+    /** Plan state `partial`: ok, the output a placeholder. */
+    partial: number;
+    skipped: number;
+    /** Finished (done, partial and skipped) out of all, in percent. */
+    pct: number;
+}
+/** How far a run is, from the plan's groups. */
+export declare function progress(plan: Plan): Progress;
+/** How a run's tasks ended, from the plan: for a run that is over, in place of a progress bar. */
+export declare function result(plan: Plan): {
+    done: number;
+    partial: number;
+    skipped: number;
+    failed: number;
+    notStarted: number;
+    left: number;
+};
+/** How long a run took, wall clock: from its start to its last activity (null when unknown). */
+export declare function elapsedS(r: Pick<RunSummary, 'started_at' | 'last_ts'> | undefined): number | null;
+/**
+ * A run's process, as every view names it: `running`; `unresponsive`, its host
+ * last reported it alive and has stopped reporting (a hub only), so whether it
+ * still runs is not known; or `stopped`.
+ */
+export type RunActivity = 'running' | 'unresponsive' | 'stopped';
+/** What a run's process is doing, from the run list and (when its feed is open) the feed's `procs.alive`. */
+export declare function runActivity(summary: Pick<RunSummary, 'running' | 'unresponsive'> | undefined, alive?: boolean): RunActivity;
+/** The host that drives a run, from the host list. */
+export declare const hostOf: (hosts: readonly HostSummary[] | undefined, summary: Pick<RunSummary, "host_id"> | undefined) => HostSummary | undefined;
+/** A run's name without its host: a hub names a run `<run_id>@<host_id>`; any other name as it is. */
+export declare function runIdOf(r: Pick<RunSummary, 'run' | 'host_id'>): string;
+/** One host's runs. */
+export interface HostGroup {
+    hostId: string;
+    /** The host as the host list has it; undefined for a host the list does not have yet. */
+    host: HostSummary | undefined;
+    runs: RunSummary[];
+}
+/**
+ * Runs by host, in the host list's order (then the host ids it does not have,
+ * sorted): in each, the running runs, then those whose host stopped reporting,
+ * then the rest, each in the order given (the run list's: most recent first).
+ */
+export declare function hostGroups(runs: readonly RunSummary[], hosts?: readonly HostSummary[]): HostGroup[];
+//# sourceMappingURL=derive.d.ts.map

package/dist/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"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"}

package/dist/derive.js

@@ -0,0 +1,89 @@
+// Everything the views count and list about a run's tasks, derived once per
+// state change: the outcomes, the rows, the counts and the problems. Every view
+// reads `deriveRun(journal, plan)`, so "N of M tasks done" and every cause read
+// the same on every screen. Pure; memoized on the identity of its inputs.
+import { isLaunched, outcomeCounts, problems, taskOutcomes, taskRows } from './outcomes.js';
+const NO_PLAN = { nodes: [], groups: [] };
+/** Run state replaces the journal and the plan arrays on every change (`reduceRun`), so their identity is the key. */
+const memo = new WeakMap();
+/**
+ * What the views show about a run's tasks. Without a plan, the tasks are the
+ * journal's only. The same `journal` and `plan` objects give the same result object.
+ */
+export function deriveRun(journal, plan = NO_PLAN) {
+    const p = plan ?? NO_PLAN;
+    let byPlan = memo.get(journal);
+    if (!byPlan)
+        memo.set(journal, (byPlan = new WeakMap()));
+    let d = byPlan.get(p);
+    if (!d)
+        byPlan.set(p, (d = derive(journal, p)));
+    return d;
+}
+function derive(journal, plan) {
+    const outcomes = taskOutcomes(journal, plan);
+    const c = outcomeCounts(outcomes);
+    return {
+        outcomes,
+        rows: taskRows(outcomes, plan),
+        counts: { ...c, doneTotal: c.done + c.recovered, finished: c.done + c.recovered + c.partial + c.skipped },
+        problems: problems(outcomes),
+        kinds: [...new Set([...outcomes.values()].map((t) => t.kind))].sort(),
+        tries: tryCounts(journal),
+    };
+}
+/** Tries (journal rows that ran) and rows of tasks that never started: the one way the UI counts them. */
+export function tryCounts(journal) {
+    const tries = journal.filter(isLaunched).length;
+    return { tries, notStarted: journal.length - tries };
+}
+/** How far a run is, from the plan's groups. */
+export function progress(plan) {
+    const total = plan.groups.reduce((a, g) => a + g.total, 0);
+    const done = plan.groups.reduce((a, g) => a + g.done, 0);
+    const partial = plan.groups.reduce((a, g) => a + (g.partial ?? 0), 0);
+    const skipped = plan.groups.reduce((a, g) => a + g.skipped, 0);
+    return { total, done, partial, skipped, pct: Math.round((100 * (done + partial + skipped)) / Math.max(1, total)) };
+}
+/** How a run's tasks ended, from the plan: for a run that is over, in place of a progress bar. */
+export function result(plan) {
+    const count = (...states) => plan.nodes.filter((n) => states.includes(n.state)).length;
+    return { done: count('done'), partial: count('partial'), skipped: count('skipped'), failed: count('failed'), notStarted: count('blocked'), left: count('pending', 'running') };
+}
+/** How long a run took, wall clock: from its start to its last activity (null when unknown). */
+export function elapsedS(r) {
+    const a = Date.parse(r?.started_at ?? '');
+    const b = Date.parse(r?.last_ts ?? '');
+    return Number.isNaN(a) || Number.isNaN(b) ? null : Math.max(0, (b - a) / 1000);
+}
+/** What a run's process is doing, from the run list and (when its feed is open) the feed's `procs.alive`. */
+export function runActivity(summary, alive = false) {
+    if (alive || summary?.running)
+        return 'running';
+    return summary?.unresponsive ? 'unresponsive' : 'stopped';
+}
+/** The host that drives a run, from the host list. */
+export const hostOf = (hosts, summary) => summary?.host_id ? hosts?.find((h) => h.host_id === summary.host_id) : undefined;
+/** A run's name without its host: a hub names a run `<run_id>@<host_id>`; any other name as it is. */
+export function runIdOf(r) {
+    const n = r.run.length - (r.host_id?.length ?? 0) - 1;
+    return r.host_id && n > 0 && r.run.endsWith(`@${r.host_id}`) ? r.run.slice(0, n) : r.run;
+}
+const ACTIVITY_ORDER = ['running', 'unresponsive', 'stopped'];
+/**
+ * Runs by host, in the host list's order (then the host ids it does not have,
+ * sorted): in each, the running runs, then those whose host stopped reporting,
+ * then the rest, each in the order given (the run list's: most recent first).
+ */
+export function hostGroups(runs, hosts = []) {
+    const ids = [...new Set(runs.map((r) => r.host_id ?? ''))];
+    const known = hosts.map((h) => h.host_id);
+    const rank = (r) => ACTIVITY_ORDER.indexOf(runActivity(r));
+    return [...known.filter((id) => ids.includes(id)), ...ids.filter((id) => !known.includes(id)).sort()].map((hostId) => ({
+        hostId,
+        host: hosts.find((h) => h.host_id === hostId),
+        // A stable sort: equal runs keep the order given.
+        runs: runs.filter((r) => (r.host_id ?? '') === hostId).sort((a, b) => rank(a) - rank(b)),
+    }));
+}
+//# sourceMappingURL=derive.js.map

package/dist/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"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"}

package/dist/export.d.ts

@@ -0,0 +1,36 @@
+import { type MonitorClient } from './client.js';
+import type { FeedHandlers, Unsubscribe } from './feed.js';
+import type { RunFeedMessage } from './types.js';
+/** A client of an export: the monitor's client, and the files the server sends over its feed instead. */
+export interface ExportClient extends MonitorClient {
+    /** A file of the export, `data/<path>` (cached): the endpoints' answers, and `plan`, `outputs`, `cursor`. */
+    file<T>(path: string): Promise<T>;
+}
+export interface ExportClientOptions {
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The name task `key`'s files take in a run directory and in an export, without a
+ * suffix: `key` with every character but a letter, a digit, `-`, `_` and `.` turned
+ * into `_`, as are a leading `.` and each `..` (Python's `file_name`, `runs/layout.py`).
+ */
+export declare function taskFileName(key: string): string;
+/**
+ * A `MonitorClient` over an export at `baseUrl` (its `data/`, relative to the page or
+ * absolute). An endpoint is a file: `info.json`, `runs.json`, `runs/<run>/journal.json`,
+ * `runs/<run>/tasks/<file>.json` (`taskFileName`) ... A task's file leaves out its rows and its
+ * definition, which the run's journal and definitions hold: the client puts them back.
+ * A view the export does not hold (a transcript, the hosts) answers `ApiError` 404.
+ * An endpoint of no run is a file under `data/` (`trends.json`, `trends/panels/<name>.json`):
+ * a new endpoint is one method here, `file<T>('<its file>')`, beside its entry in the
+ * Python `VIEWS` (`contraagent/monitor/views.py`) or `SITE_FILES` (`contraagent/monitor/export.py`).
+ */
+export declare function createExportClient(baseUrl: string, options?: ExportClientOptions): ExportClient;
+/** A run feed opener, as `openRunFeed` is: what `MonitorStore` opens a run's feed with. */
+export type RunFeedOpener = (run: string, panels: readonly string[], on: FeedHandlers<RunFeedMessage>) => Unsubscribe;
+/**
+ * The run feed of an export: the run's journal rows, plan, outputs, cursor and panels,
+ * each once, then `ready`; nothing after. A file it cannot read stops it with `error`.
+ */
+export declare function openExportFeed(client: ExportClient): RunFeedOpener;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,KAAK,EAOV,cAAc,EAKf,MAAM,YAAY,CAAC;AAEpB,yGAAyG;AACzG,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,6GAA6G;IAC7G,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,YAAY,CA+DnG;AAKD,2FAA2F;AAC3F,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,YAAY,CAAC,cAAc,CAAC,KAAK,WAAW,CAAC;AAEtH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,CA6BlE"}

package/dist/export.js

@@ -0,0 +1,130 @@
+// An export (`contraagent monitor export`): the monitor's views of some runs,
+// written as files and read with no server. The client maps each endpoint to its
+// file; the feed replays a run's files once and ends with `ready`.
+import { ApiError } from './client.js';
+const seg = encodeURIComponent;
+/**
+ * The name task `key`'s files take in a run directory and in an export, without a
+ * suffix: `key` with every character but a letter, a digit, `-`, `_` and `.` turned
+ * into `_`, as are a leading `.` and each `..` (Python's `file_name`, `runs/layout.py`).
+ */
+export function taskFileName(key) {
+    const name = Array.from(key, (ch) => (/^[\p{L}\p{N}._-]$/u.test(ch) ? ch : '_'))
+        .join('')
+        .replace(/\.\.+/g, (m) => '_'.repeat(m.length));
+    return name.startsWith('.') ? `_${name.slice(1)}` : name || '_';
+}
+/**
+ * A `MonitorClient` over an export at `baseUrl` (its `data/`, relative to the page or
+ * absolute). An endpoint is a file: `info.json`, `runs.json`, `runs/<run>/journal.json`,
+ * `runs/<run>/tasks/<file>.json` (`taskFileName`) ... A task's file leaves out its rows and its
+ * definition, which the run's journal and definitions hold: the client puts them back.
+ * A view the export does not hold (a transcript, the hosts) answers `ApiError` 404.
+ * An endpoint of no run is a file under `data/` (`trends.json`, `trends/panels/<name>.json`):
+ * a new endpoint is one method here, `file<T>('<its file>')`, beside its entry in the
+ * Python `VIEWS` (`contraagent/monitor/views.py`) or `SITE_FILES` (`contraagent/monitor/export.py`).
+ */
+export function createExportClient(baseUrl, options = {}) {
+    const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    const fetch = options.fetch ?? globalThis.fetch;
+    const cache = new Map();
+    function file(path) {
+        let p = cache.get(path);
+        if (!p) {
+            p = load(base + path);
+            // A failed read is tried again next time.
+            p.catch(() => cache.delete(path));
+            cache.set(path, p);
+        }
+        return p;
+    }
+    async function load(url) {
+        let response;
+        try {
+            response = await fetch(new Request(url));
+        }
+        catch {
+            throw new ApiError(url, 'network');
+        }
+        const type = (response.headers.get('Content-Type') ?? '').split(';')[0].trim().toLowerCase();
+        if (!response.ok)
+            throw new ApiError(url, 'status', response.status, type);
+        try {
+            return (await response.json());
+        }
+        catch {
+            throw new ApiError(url, 'not-json', response.status, type);
+        }
+    }
+    const run = (r, path) => `runs/${seg(r)}/${path}`;
+    const absent = (path) => Promise.reject(new ApiError(base + path, 'status', 404));
+    return {
+        baseUrl: base.replace(/\/$/, ''),
+        file,
+        info: () => file('info.json'),
+        runs: () => file('runs.json'),
+        hosts: () => absent('hosts.json'),
+        async journal(r, since = 0) {
+            const page = await file(run(r, 'journal.json'));
+            return since > 0 ? { entries: page.entries.slice(since), total: page.total } : page;
+        },
+        definitions: (r) => file(run(r, 'definitions.json')),
+        async task(r, key) {
+            const [detail, journal, definitions, plan] = await Promise.all([
+                file(run(r, `tasks/${seg(taskFileName(key))}.json`)),
+                file(run(r, 'journal.json')),
+                file(run(r, 'definitions.json')),
+                file(run(r, 'plan.json')),
+            ]);
+            const rows = journal.entries.filter((e) => e.key === key);
+            const kind = rows.at(-1)?.kind ?? plan.nodes.find((n) => n.key === key)?.kind;
+            return { ...detail, rows, definition: definitions.find((d) => d.kind === kind) ?? null };
+        },
+        stream: (r, key) => absent(run(r, `streams/${seg(taskFileName(key))}.json`)),
+        panel: (r, name) => file(run(r, `panels/${seg(name)}.json`)),
+        // An export holds one period's trends (`Info.export`): a query for another is answered with it.
+        trends: () => file('trends.json'),
+        trendsPanel: (name) => file(`trends/panels/${seg(name)}.json`),
+    };
+}
+/** A cursor file: `{}` when the run keeps no cursor. */
+const isCursor = (c) => Object.keys(c).length > 0;
+/**
+ * The run feed of an export: the run's journal rows, plan, outputs, cursor and panels,
+ * each once, then `ready`; nothing after. A file it cannot read stops it with `error`.
+ */
+export function openExportFeed(client) {
+    return (r, panels, on) => {
+        let closed = false;
+        void (async () => {
+            try {
+                const [journal, plan, outputs, cursor, bodies] = await Promise.all([
+                    client.journal(r),
+                    client.file(`runs/${seg(r)}/plan.json`),
+                    client.file(`runs/${seg(r)}/outputs.json`),
+                    client.file(`runs/${seg(r)}/cursor.json`),
+                    Promise.all(panels.map((p) => client.panel(r, p).catch((e) => ({ error: String(e) })))),
+                ]);
+                if (closed)
+                    return;
+                on.open?.();
+                const send = (m) => !closed && on.message(m);
+                for (const row of journal.entries)
+                    send({ event: 'journal', data: row });
+                send({ event: 'plan', data: plan });
+                send({ event: 'outputs', data: outputs });
+                send({ event: 'cursor', data: isCursor(cursor) ? cursor : null });
+                panels.forEach((p, i) => send({ event: `panel:${p}`, data: bodies[i] ?? {} }));
+                send({ event: 'ready', data: { journal: journal.total } });
+            }
+            catch {
+                if (!closed)
+                    on.error?.();
+            }
+        })();
+        return () => {
+            closed = true;
+        };
+    };
+}
+//# sourceMappingURL=export.js.map

package/dist/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"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"}