@pmndrs/pine 0.0.0-stage → 0.1.0

package/src/tui/theme.d.ts

@@ -0,0 +1,32 @@
+import { type EditorTheme, Markdown, type MarkdownTheme, type SelectListTheme } from "@earendil-works/pi-tui";
+/** Plain 16/256-colour styling, so the UI follows the terminal's own palette. */
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    italic: (s: string) => string;
+    underline: (s: string) => string;
+    inverse: (s: string) => string;
+    strike: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    magenta: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+    accent: (s: string) => string;
+    bgPanel: (s: string) => string;
+    bgUser: (s: string) => string;
+    bgAccent: (s: string) => string;
+};
+export declare const selectTheme: SelectListTheme;
+export declare const editorTheme: EditorTheme;
+export declare const markdownTheme: MarkdownTheme;
+export declare const SPINNER: string[];
+/** Markdown from an agent or a tool, drawn: headings, lists, tables, quotes, and code in colour. */
+export declare class Answer extends Markdown {
+    private from?;
+    private drawn;
+    constructor(text: string);
+    render(width: number): string[];
+}

package/src/tui/theme.js

@@ -0,0 +1,128 @@
+import { Markdown, visibleWidth } from "@earendil-works/pi-tui";
+import { highlightCode } from "./highlight.js";
+const on = !process.env.NO_COLOR;
+const sgr = (open, close) => (s) => (on ? `\x1b[${open}m${s}\x1b[${close}m` : s);
+/** Plain 16/256-colour styling, so the UI follows the terminal's own palette. */
+export const c = {
+    bold: sgr("1", "22"),
+    dim: sgr("2", "22"),
+    italic: sgr("3", "23"),
+    underline: sgr("4", "24"),
+    inverse: sgr("7", "27"),
+    strike: sgr("9", "29"),
+    red: sgr("31", "39"),
+    green: sgr("32", "39"),
+    yellow: sgr("33", "39"),
+    blue: sgr("34", "39"),
+    magenta: sgr("35", "39"),
+    cyan: sgr("36", "39"),
+    gray: sgr("90", "39"),
+    accent: sgr("38;5;114", "39"),
+    bgPanel: sgr("48;5;236", "49"),
+    bgUser: sgr("48;5;237", "49"),
+    bgAccent: sgr("48;5;114;30", "49;39"),
+};
+export const selectTheme = {
+    selectedPrefix: c.accent,
+    selectedText: (s) => c.bold(c.accent(s)),
+    description: c.gray,
+    scrollInfo: c.gray,
+    noMatch: c.gray,
+};
+export const editorTheme = { borderColor: c.gray, selectList: selectTheme };
+/** Marks a line that only held a code block's backticks. A private-use character: no text contains it. */
+const FENCE = "\uE000";
+export const markdownTheme = {
+    // From the third level on, the library puts the "###" in front as a piece of its own. It is markup, so it is left out.
+    heading: (s) => (/^(?:\x1b\[[0-9;]*m)*#{3,6} (?:\x1b\[[0-9;]*m)*$/.test(s) ? "" : c.bold(c.accent(s))),
+    link: c.cyan,
+    linkUrl: c.gray,
+    code: c.yellow,
+    codeBlock: (s) => s,
+    // A code block is a bar down its left side with its language above it. The lines of backticks
+    // around it are markup, not content: the opening one becomes the language, the others are
+    // marked here and left out by Answer below.
+    codeBlockBorder: (s) => {
+        const lang = s.replace(/^[`~]+/, "").trim();
+        return lang ? c.gray(lang) : FENCE;
+    },
+    codeBlockIndent: c.gray("│ "),
+    highlightCode,
+    quote: c.italic,
+    quoteBorder: c.gray,
+    hr: c.gray,
+    listBullet: c.accent,
+    bold: c.bold,
+    italic: c.italic,
+    strikethrough: c.strike,
+    underline: c.underline,
+};
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Markdown from an agent or a tool, drawn: headings, lists, tables, quotes, and code in colour. */
+export class Answer extends Markdown {
+    from;
+    drawn = [];
+    constructor(text) {
+        super(text, 1, 0, markdownTheme);
+    }
+    render(width) {
+        const lines = super.render(width);
+        if (lines !== this.from) {
+            this.from = lines;
+            this.drawn = lines.some((l) => l.includes(FENCE)) ? lines.filter((l) => !l.includes(FENCE)) : lines;
+        }
+        return this.drawn;
+    }
+}
+// Two things the library's tables leave out, added where it wraps a cell's text to its column:
+// a <br>, which models write for a line break inside a cell, becomes that break; and a column
+// that the table's second line aligns to the right ("---:") or centres (":---:") is set that way.
+const proto = Markdown.prototype;
+const wrapCell = proto.wrapCellText;
+const drawTable = proto.renderTable;
+const inline = proto.renderInlineTokens;
+const BR = /\s*<br\s*\/?>\s*/i;
+if (wrapCell && drawTable && inline) {
+    const own = Answer.prototype;
+    own.renderTable = function (token, ...rest) {
+        // The library first reads every cell once to size the columns, then once more, cell after
+        // cell and row by row, to draw them. Counting says which of the two it is doing, and which
+        // column a cell is in.
+        const cells = (token?.header?.length ?? 0) + (token?.rows ?? []).reduce((n, row) => n + row.length, 0);
+        this.table = { align: Array.isArray(token?.align) ? token.align : [], columns: token?.header?.length || 1, cell: 0, sizing: cells, depth: 0 };
+        try {
+            return drawTable.call(this, token, ...rest);
+        }
+        finally {
+            this.table = undefined;
+        }
+    };
+    own.renderInlineTokens = function (...args) {
+        const table = this.table;
+        if (!table)
+            return inline.apply(this, args);
+        table.depth++;
+        let text;
+        try {
+            text = inline.apply(this, args);
+        }
+        finally {
+            table.depth--;
+        }
+        if (table.depth > 0 || table.sizing <= 0)
+            return text;
+        table.sizing--;
+        // A cell with line breaks is as wide as its longest line, not as all of them in a row.
+        return BR.test(text) ? text.split(BR).reduce((a, b) => (visibleWidth(b) > visibleWidth(a) ? b : a)) : text;
+    };
+    own.wrapCellText = function (text, width, stylePrefix) {
+        const lines = text.split(BR).flatMap((part) => wrapCell.call(this, part, width, stylePrefix));
+        const side = this.table ? this.table.align[this.table.cell++ % this.table.columns] : undefined;
+        if (side !== "right" && side !== "center")
+            return lines;
+        return lines.map((line) => {
+            const free = Math.max(0, width - visibleWidth(line));
+            return " ".repeat(side === "right" ? free : Math.floor(free / 2)) + line;
+        });
+    };
+}

package/src/types.d.ts

@@ -0,0 +1,124 @@
+/** Where a handler's answer should go: an event on `topic` whose payload is `payload` plus `text`. */
+export interface ReplyTarget {
+    topic: string;
+    payload?: Record<string, unknown>;
+}
+export interface PineEvent {
+    /** Row id in the event log; 0 for events published with `persist: false`. */
+    id: number;
+    ts: number;
+    topic: string;
+    /** Who published it: "source:<name>", "router", "timer", "http", or "agent:<id>". */
+    source: string;
+    payload: unknown;
+    /** Id of the event that led to this one. */
+    cause?: number;
+    /** How many agent or router steps separate this event from an outside trigger. */
+    hops: number;
+    reply?: ReplyTarget;
+    /**
+     * "owner": the content was written by a person the configuration names as owner (an
+     * allow-listed chat user, the authenticated control API, a schedule). Everything else is
+     * "untrusted": data that may try to give instructions.
+     */
+    trust: Trust;
+}
+export type Trust = "owner" | "untrusted";
+export interface PublishOptions {
+    source?: string;
+    cause?: PineEvent | null;
+    reply?: ReplyTarget;
+    /** false keeps the event out of the log (telemetry, progress). Subscribers still get it. */
+    persist?: boolean;
+    /** Set when the publisher is acting for an agent or a route, so loops can be cut. */
+    hop?: boolean;
+    /** Default "untrusted". */
+    trust?: Trust;
+}
+export type TaskStatus = "pending" | "running" | "done" | "failed" | "cancelled";
+export type TaskKind = "event" | "prompt" | "delegate" | "subagent" | "notify";
+export interface ImageRef {
+    /** Absolute file path, or base64 data when `data` is set. */
+    path?: string;
+    data?: string;
+    mimeType: string;
+}
+export interface TaskMeta {
+    images?: ImageRef[];
+    /** Deliver the result to this agent session as a new message when the task ends. */
+    notify?: {
+        agent: string;
+        session: string;
+    };
+    /** Agents above this task in the delegation chain, outermost first. */
+    chain?: string[];
+    /** The task at the top of this task's delegation tree (its own id for a top-level task). */
+    root?: number;
+    /** Child sessions of a sub-agent get no delegation tools and an optional narrower tool list. */
+    leaf?: boolean;
+    tools?: string[];
+    label?: string;
+    /** Trust of whatever started this task. Children inherit the weaker of theirs and their parent's. */
+    trust?: Trust;
+    /** The session that created this task had already seen outside content. */
+    tainted?: string;
+    /** `input` is what the model server had to read anew; `cached` is what it took from its prompt cache. */
+    stats?: {
+        input: number;
+        output: number;
+        cached?: number;
+        turns: number;
+        tools: string[];
+        ms: number;
+        context?: ContextUse;
+    };
+}
+/** How full a session's context window is. `percent` is missing right after a compaction. */
+export interface ContextUse {
+    tokens?: number;
+    window: number;
+    percent?: number;
+}
+export interface Task {
+    id: number;
+    agent: string;
+    /** Session key. Ephemeral sessions use "_t<id>". */
+    session: string;
+    kind: TaskKind;
+    prompt: string;
+    status: TaskStatus;
+    priority: number;
+    created: number;
+    started?: number;
+    finished?: number;
+    result?: string;
+    error?: string;
+    event?: number;
+    hops: number;
+    parent?: number;
+    depth: number;
+    reply?: ReplyTarget;
+    meta: TaskMeta;
+}
+/** One step of a task as its session recorded it: what it was given, what it wrote, what it called. */
+export interface TranscriptEntry {
+    kind: "user" | "text" | "thinking" | "tool";
+    text?: string;
+    tool?: string;
+    subject?: string;
+    /** For a tool call: missing while it runs. */
+    ok?: boolean;
+    /** Pictures the tool returned, by the id the control API serves them under (GET /media/tool/<id>). */
+    images?: string[];
+    ms?: number;
+    result?: string;
+}
+export interface TaskResult {
+    id: number;
+    agent: string;
+    status: TaskStatus;
+    text: string;
+    error?: string;
+    /** Set when the run handled outside content; the reason names the first source. */
+    tainted?: string;
+}

package/src/types.js

@@ -0,0 +1 @@
+export {};

package/src/update.d.ts

@@ -0,0 +1,25 @@
+/**
+ * How this copy of pine got here.
+ * checkout: a git clone, which runs the sources directly. It is updated with git.
+ * global:   installed with "npm install -g". It is updated with npm.
+ * local:    a dependency inside some project's node_modules. That project decides its version.
+ */
+export type InstallKind = "checkout" | "global" | "local";
+export declare function installKind(root: string, globalRoot?: string): InstallKind;
+/** Whether version a is higher than version b ("1.10.0" is higher than "1.9.3"). */
+export declare function newer(a: string, b: string): boolean;
+export declare function installed(root?: string): {
+    name: string;
+    version: string;
+    kind: InstallKind;
+    root: string;
+};
+/**
+ * Update pine, or with `check` only say whether there is something newer. Returns the exit code.
+ * `browser` fetches the browser build of the version that is on disk afterwards.
+ */
+export declare function update(opts: {
+    check: boolean;
+    out: (line: string) => void;
+    browser: boolean;
+}): Promise<number>;

package/src/update.js

@@ -0,0 +1,110 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { PINE_ROOT } from "./config.js";
+const real = (p) => {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+};
+export function installKind(root, globalRoot) {
+    if (fs.existsSync(path.join(root, ".git")) && fs.existsSync(path.join(root, "src", "cli.ts")))
+        return "checkout";
+    if (globalRoot && (real(root) + path.sep).startsWith(real(globalRoot) + path.sep))
+        return "global";
+    return "local";
+}
+/** Whether version a is higher than version b ("1.10.0" is higher than "1.9.3"). */
+export function newer(a, b) {
+    const parse = (v) => v.split("-")[0].split(".").map((n) => Number(n) || 0);
+    const [x, y] = [parse(a), parse(b)];
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    return false;
+}
+export function installed(root = PINE_ROOT) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    const globalRoot = capture("npm", ["root", "-g"]);
+    return { name: pkg.name, version: pkg.version, kind: installKind(root, globalRoot), root };
+}
+function capture(cmd, args, cwd) {
+    const r = spawnSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return r.status === 0 ? r.stdout.trim() : undefined;
+}
+const show = (cmd, args, cwd) => spawnSync(cmd, args, { cwd, stdio: "inherit" }).status ?? 1;
+const RESTART = "A pine that is running keeps the old version until it is restarted: quit the terminal UI and open it again, or restart the daemon.";
+/**
+ * Update pine, or with `check` only say whether there is something newer. Returns the exit code.
+ * `browser` fetches the browser build of the version that is on disk afterwards.
+ */
+export async function update(opts) {
+    const { out } = opts;
+    const me = installed();
+    if (me.kind === "checkout") {
+        const branch = capture("git", ["rev-parse", "--abbrev-ref", "HEAD"], me.root) ?? "?";
+        if (!capture("git", ["rev-parse", "--abbrev-ref", "@{u}"], me.root)) {
+            out(`This is a checkout in ${me.root}, and its branch ${branch} does not follow one on a server, so there is nothing to update from. Set that up with git, or pull by hand.`);
+            return 1;
+        }
+        if (spawnSync("git", ["fetch", "--quiet"], { cwd: me.root, stdio: "inherit" }).status !== 0) {
+            out("Could not reach the repository this checkout follows.");
+            return 1;
+        }
+        const behind = Number(capture("git", ["rev-list", "--count", "HEAD..@{u}"], me.root) ?? 0);
+        if (!behind) {
+            out(`pine ${me.version} (checkout in ${me.root}, branch ${branch}) is up to date.`);
+            return 0;
+        }
+        if (opts.check) {
+            out(`${behind} new commit${behind === 1 ? "" : "s"} for this checkout (${me.root}, branch ${branch}). Run "pine update" to get ${behind === 1 ? "it" : "them"}.`);
+            return 0;
+        }
+        out(`Getting ${behind} new commit${behind === 1 ? "" : "s"} ...`);
+        // Only ever a fast-forward: your own commits and changes are never rewritten or thrown away.
+        if (show("git", ["pull", "--ff-only"], me.root) !== 0) {
+            out("git could not simply move this checkout forward (you have commits or changes of your own in the way). Nothing was changed; sort it out with git and run pine update again.");
+            return 1;
+        }
+        out("Installing what the new version depends on ...");
+        if (show("npm", ["install", "--no-audit", "--no-fund"], me.root) !== 0)
+            return 1;
+    }
+    else {
+        const latest = capture("npm", ["view", me.name, "version"]);
+        if (!latest) {
+            out(`Could not ask npm for the latest version of ${me.name}. You may be offline.`);
+            return 1;
+        }
+        if (!newer(latest, me.version)) {
+            out(`pine ${me.version} is the latest version.`);
+            return 0;
+        }
+        if (me.kind === "local") {
+            out(`pine ${latest} is available (this is ${me.version}). This copy is a dependency of the project it is installed in (${me.root}); update it there:\n\n  npm install ${me.name}@latest`);
+            return opts.check ? 0 : 1;
+        }
+        if (opts.check) {
+            out(`pine ${latest} is available (this is ${me.version}). Run "pine update" to install it.`);
+            return 0;
+        }
+        out(`Updating pine ${me.version} to ${latest} ...`);
+        if (show("npm", ["install", "-g", `${me.name}@latest`, "--no-audit", "--no-fund"]) !== 0) {
+            out(`npm could not install the new version. Run it yourself to see why:\n\n  npm install -g ${me.name}@latest`);
+            return 1;
+        }
+    }
+    // The browser build has to match the new version, so the new version's own installer fetches it.
+    if (opts.browser) {
+        out("Making sure the browser the web tools drive matches ...");
+        const status = show(process.execPath, [path.join(me.root, "bin", "pine.js"), "browser-install"]);
+        if (status !== 0)
+            out(`The browser could not be fetched (exit ${status}). Run "pine browser-install" when you are online.`);
+    }
+    const now = installed(me.root);
+    out(`\npine is now ${now.version}. ${RESTART}`);
+    return 0;
+}

package/src/util.d.ts

@@ -0,0 +1,32 @@
+export declare const sleep: (ms: number) => Promise<void>;
+export declare function expandHome(p: string): string;
+/** Resolve a config path: `~` expands, relative paths are relative to `base`. */
+export declare function resolvePath(p: string, base: string): string;
+/** MQTT-style topic match: `+` is one level, a trailing `#` is the rest (including nothing). */
+export declare function topicMatches(pattern: string, topic: string): boolean;
+export declare const matchesAny: (patterns: readonly string[], topic: string) => boolean;
+export declare function getPath(obj: unknown, dotted: string): unknown;
+/** Replace `{{a.b}}` with values from `ctx`. Objects render as JSON, missing values as "". */
+export declare function render(template: string, ctx: unknown): string;
+/** Render every string inside a JSON-like value. A string that is exactly one `{{path}}` keeps the value's type. */
+export declare function renderDeep(value: unknown, ctx: unknown): unknown;
+/**
+ * Declarative filter. Keys are dotted paths into `ctx`; a plain value means equality, an object
+ * may use eq, ne, in, gt, gte, lt, lte, exists, contains, regex. All keys must match.
+ */
+export declare function matchWhen(when: Record<string, unknown> | undefined, ctx: unknown): boolean;
+/** "90s", "15m", "2h", "1d" or a number of milliseconds. */
+export declare function parseDuration(v: string | number): number;
+/** A string that is safe as one path component: no dots, no separators, never empty. */
+export declare const safeName: (s: string) => string;
+export declare const truncate: (s: string, n: number) => string;
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+export interface Logger {
+    debug(msg: string, extra?: unknown): void;
+    info(msg: string, extra?: unknown): void;
+    warn(msg: string, extra?: unknown): void;
+    error(msg: string, extra?: unknown): void;
+    child(scope: string): Logger;
+}
+export declare function createLogger(level?: LogLevel, scope?: string, sink?: (line: string) => void): Logger;
+export declare const errText: (e: unknown) => string;

package/src/util.js

@@ -0,0 +1,116 @@
+import os from "node:os";
+import path from "node:path";
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function expandHome(p) {
+    return p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p;
+}
+/** Resolve a config path: `~` expands, relative paths are relative to `base`. */
+export function resolvePath(p, base) {
+    const e = expandHome(p);
+    return path.isAbsolute(e) ? e : path.resolve(base, e);
+}
+/** MQTT-style topic match: `+` is one level, a trailing `#` is the rest (including nothing). */
+export function topicMatches(pattern, topic) {
+    if (pattern === "#" || pattern === topic)
+        return true;
+    const p = pattern.split("/");
+    const t = topic.split("/");
+    for (let i = 0; i < p.length; i++) {
+        if (p[i] === "#")
+            return i === p.length - 1;
+        if (i >= t.length)
+            return false;
+        if (p[i] !== "+" && p[i] !== t[i])
+            return false;
+    }
+    return p.length === t.length;
+}
+export const matchesAny = (patterns, topic) => patterns.some((p) => topicMatches(p, topic));
+export function getPath(obj, dotted) {
+    let cur = obj;
+    for (const key of dotted.split(".")) {
+        if (cur == null)
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+const asText = (v) => (v == null ? "" : typeof v === "string" ? v : JSON.stringify(v));
+/** Replace `{{a.b}}` with values from `ctx`. Objects render as JSON, missing values as "". */
+export function render(template, ctx) {
+    return template.replace(/\{\{\s*([\w.$/-]+)\s*\}\}/g, (_m, p) => asText(getPath(ctx, p)));
+}
+/** Render every string inside a JSON-like value. A string that is exactly one `{{path}}` keeps the value's type. */
+export function renderDeep(value, ctx) {
+    if (typeof value === "string") {
+        const whole = value.match(/^\{\{\s*([\w.$/-]+)\s*\}\}$/);
+        return whole ? getPath(ctx, whole[1]) : render(value, ctx);
+    }
+    if (Array.isArray(value))
+        return value.map((v) => renderDeep(v, ctx));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderDeep(v, ctx)]));
+    return value;
+}
+/**
+ * Declarative filter. Keys are dotted paths into `ctx`; a plain value means equality, an object
+ * may use eq, ne, in, gt, gte, lt, lte, exists, contains, regex. All keys must match.
+ */
+export function matchWhen(when, ctx) {
+    if (!when)
+        return true;
+    for (const [key, cond] of Object.entries(when)) {
+        const v = getPath(ctx, key);
+        if (cond === null || typeof cond !== "object" || Array.isArray(cond)) {
+            if (JSON.stringify(v) !== JSON.stringify(cond))
+                return false;
+            continue;
+        }
+        const c = cond;
+        if ("eq" in c && JSON.stringify(v) !== JSON.stringify(c.eq))
+            return false;
+        if ("ne" in c && JSON.stringify(v) === JSON.stringify(c.ne))
+            return false;
+        if ("in" in c && !(Array.isArray(c.in) && c.in.some((x) => JSON.stringify(x) === JSON.stringify(v))))
+            return false;
+        if ("gt" in c && !(v > c.gt))
+            return false;
+        if ("gte" in c && !(v >= c.gte))
+            return false;
+        if ("lt" in c && !(v < c.lt))
+            return false;
+        if ("lte" in c && !(v <= c.lte))
+            return false;
+        if ("exists" in c && (v !== undefined && v !== null) !== Boolean(c.exists))
+            return false;
+        if ("contains" in c && !(typeof v === "string" || Array.isArray(v) ? v.includes(c.contains) : false))
+            return false;
+        if ("regex" in c && !(typeof v === "string" && new RegExp(c.regex, c.flags ?? "").test(v)))
+            return false;
+    }
+    return true;
+}
+/** "90s", "15m", "2h", "1d" or a number of milliseconds. */
+export function parseDuration(v) {
+    if (typeof v === "number")
+        return v;
+    const m = v.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/);
+    if (!m)
+        throw new Error(`invalid duration: ${v}`);
+    return Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] ?? "ms"];
+}
+/** A string that is safe as one path component: no dots, no separators, never empty. */
+export const safeName = (s) => s.replace(/[^A-Za-z0-9_-]+/g, "_").slice(0, 80) || "_";
+export const truncate = (s, n) => (s.length > n ? `${s.slice(0, n)}… [${s.length - n} more chars]` : s);
+const LEVELS = ["debug", "info", "warn", "error", "silent"];
+export function createLogger(level = "info", scope = "pine", sink = (l) => process.stderr.write(`${l}\n`)) {
+    const min = LEVELS.indexOf(level);
+    const emit = (lvl) => (msg, extra) => {
+        if (LEVELS.indexOf(lvl) < min)
+            return;
+        const tail = extra === undefined ? "" : ` ${extra instanceof Error ? (extra.stack ?? extra.message) : typeof extra === "string" ? extra : JSON.stringify(extra)}`;
+        sink(`${new Date().toISOString()} ${lvl.toUpperCase().padEnd(5)} [${scope}] ${msg}${tail}`);
+    };
+    return { debug: emit("debug"), info: emit("info"), warn: emit("warn"), error: emit("error"), child: (s) => createLogger(level, `${scope}:${s}`, sink) };
+}
+export const errText = (e) => (e instanceof Error ? e.message : String(e));

package/src/watching.d.ts

@@ -0,0 +1,20 @@
+export declare const clip: (s: string, n?: number) => string;
+/** A value as an event carries it: text and large structures cut to a sensible length. */
+export declare function shown(value: unknown): unknown;
+/**
+ * A value as a status line may say it. A status line is read by agents without the mark that
+ * outside content gets, so it only repeats what cannot carry a sentence: a number, an amount, one word.
+ */
+export declare function harmless(value: unknown): string;
+/** A regular expression an agent or owner wrote, or an error that says what is wrong with it. */
+export declare function pattern(source: string): RegExp;
+/** What a pattern finds in a text: its first group if it has one, else the whole match. Nothing found is null. */
+export declare function found(re: RegExp, text: string): string | null;
+/** The lines that are new and the lines that are gone between two texts, a handful of each. */
+export declare function lineDiff(before: string, now: string): {
+    added: string[];
+    removed: string[];
+    more?: number;
+};
+/** What a reader of a web page sees, line by line: no scripts, no styles, no markup. */
+export declare function pageText(html: string): string;

package/src/watching.js

@@ -0,0 +1,68 @@
+// What the source types that look at something again and again (http, command) have in common:
+// picking the part that counts out of what they got, and saying what changed in it.
+const LINES = 30;
+const LINE = 300;
+const VALUE = 4000;
+export const clip = (s, n = VALUE) => (s.length > n ? `${s.slice(0, n)}…` : s);
+/** A value as an event carries it: text and large structures cut to a sensible length. */
+export function shown(value) {
+    if (typeof value === "string")
+        return clip(value);
+    const json = JSON.stringify(value) ?? "null";
+    return json.length > VALUE ? clip(json) : value;
+}
+/**
+ * A value as a status line may say it. A status line is read by agents without the mark that
+ * outside content gets, so it only repeats what cannot carry a sentence: a number, an amount, one word.
+ */
+export function harmless(value) {
+    if (value === null || value === undefined)
+        return "nothing";
+    const s = typeof value === "string" ? value : JSON.stringify(value);
+    return /^[\d.,:%€$£+\- ]{1,24}$/.test(s) || /^[\w.-]{1,32}$/.test(s) ? s : `a value of ${s.length} characters`;
+}
+/** A regular expression an agent or owner wrote, or an error that says what is wrong with it. */
+export function pattern(source) {
+    try {
+        return new RegExp(source, "m");
+    }
+    catch (e) {
+        throw new Error(`"match" is not a regular expression: ${e instanceof Error ? e.message : e}`);
+    }
+}
+/** What a pattern finds in a text: its first group if it has one, else the whole match. Nothing found is null. */
+export function found(re, text) {
+    const m = re.exec(text);
+    return m ? clip((m[1] ?? m[0]).trim()) : null;
+}
+/** The lines that are new and the lines that are gone between two texts, a handful of each. */
+export function lineDiff(before, now) {
+    const lines = (s) => s.split("\n").map((l) => l.trim()).filter(Boolean);
+    const a = lines(before);
+    const b = lines(now);
+    const had = new Set(a);
+    const has = new Set(b);
+    const added = b.filter((l) => !had.has(l));
+    const removed = a.filter((l) => !has.has(l));
+    const more = Math.max(0, added.length - LINES) + Math.max(0, removed.length - LINES);
+    return { added: added.slice(0, LINES).map((l) => clip(l, LINE)), removed: removed.slice(0, LINES).map((l) => clip(l, LINE)), ...(more ? { more } : {}) };
+}
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", euro: "€", pound: "£", copy: "©", ndash: "–", mdash: "—", hellip: "…" };
+/** What a reader of a web page sees, line by line: no scripts, no styles, no markup. */
+export function pageText(html) {
+    return html
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/<(script|style|noscript|template|svg|head)\b[\s\S]*?<\/\1\s*>/gi, "")
+        .replace(/<(br|hr)\b[^>]*>|<\/(p|div|li|tr|h[1-6]|section|article|table|ul|ol|dd|dt|header|footer|main|nav|blockquote|pre|title)\s*>/gi, "\n")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (all, name) => {
+        if (name[0] !== "#")
+            return ENTITIES[name.toLowerCase()] ?? all;
+        const code = name[1].toLowerCase() === "x" ? Number.parseInt(name.slice(2), 16) : Number.parseInt(name.slice(1), 10);
+        return Number.isFinite(code) && code > 0 && code < 0x110000 ? String.fromCodePoint(code) : all;
+    })
+        .split("\n")
+        .map((l) => l.replace(/\s+/g, " ").trim())
+        .filter(Boolean)
+        .join("\n");
+}