@ailoud/providers 1.0.0-dev.1

package/dist/llm/anthropic.d.ts

@@ -0,0 +1,36 @@
+import type { Summarizer } from '@ailoud/core';
+export interface AnthropicOptions {
+    readonly baseUrl: string;
+    readonly model: string;
+    readonly contextTokens: number;
+    readonly maxOutputTokens: number;
+    readonly apiKey: string;
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Pulls the text out of a messages response.
+ *
+ * The content is a list of blocks, not a string, because a reply can contain
+ * more than prose. Only text blocks are joined; anything else is skipped
+ * rather than stringified, which would put "[object Object]" in a summary.
+ */
+export declare function extractAnthropicText(body: unknown): string;
+/**
+ * Claude, through Anthropic's own API.
+ *
+ * A separate adapter rather than a base-url swap on the OpenAI one, because
+ * the two APIs are not the same shape: a different path, `x-api-key` instead
+ * of a bearer token, a required version header, and a reply whose text lives
+ * in a list of content blocks rather than in `choices[0].message.content`.
+ * Pretending otherwise would have produced an adapter that looked generic and
+ * worked for exactly one vendor.
+ */
+export declare class AnthropicSummarizer implements Summarizer {
+    private readonly options;
+    readonly name = "anthropic";
+    get model(): string;
+    private readonly fetchImpl;
+    constructor(options: AnthropicOptions);
+    get contextTokens(): number;
+    complete(prompt: string): Promise<string>;
+}

package/dist/llm/anthropic.js

@@ -0,0 +1,92 @@
+import { EnvironmentError, FailureError } from '@ailoud/core';
+/** As for the OpenAI adapter: a hosted call that has not returned in five minutes is not going to. */
+const REQUEST_TIMEOUT_MS = 5 * 60_000;
+/**
+ * The API version header Anthropic requires on every request.
+ *
+ * Pinned, not omitted and not tracking the newest: the header is how Anthropic
+ * keeps a client working when the API changes, and leaving it out or moving it
+ * automatically would trade that guarantee away for nothing.
+ */
+const API_VERSION = '2023-06-01';
+/**
+ * Pulls the text out of a messages response.
+ *
+ * The content is a list of blocks, not a string, because a reply can contain
+ * more than prose. Only text blocks are joined; anything else is skipped
+ * rather than stringified, which would put "[object Object]" in a summary.
+ */
+export function extractAnthropicText(body) {
+    const blocks = body.content;
+    const text = (blocks ?? [])
+        .filter((block) => block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('')
+        .trim();
+    if (text === '') {
+        throw new FailureError('Claude returned no text. The response contained no text blocks in content[].');
+    }
+    return text;
+}
+/**
+ * Claude, through Anthropic's own API.
+ *
+ * A separate adapter rather than a base-url swap on the OpenAI one, because
+ * the two APIs are not the same shape: a different path, `x-api-key` instead
+ * of a bearer token, a required version header, and a reply whose text lives
+ * in a list of content blocks rather than in `choices[0].message.content`.
+ * Pretending otherwise would have produced an adapter that looked generic and
+ * worked for exactly one vendor.
+ */
+export class AnthropicSummarizer {
+    options;
+    name = 'anthropic';
+    get model() {
+        return this.options.model;
+    }
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    get contextTokens() {
+        return this.options.contextTokens;
+    }
+    async complete(prompt) {
+        const url = `${this.options.baseUrl.replace(/\/+$/, '')}/messages`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: {
+                    'content-type': 'application/json',
+                    'x-api-key': this.options.apiKey,
+                    'anthropic-version': API_VERSION,
+                },
+                body: JSON.stringify({
+                    model: this.options.model,
+                    max_tokens: this.options.maxOutputTokens,
+                    messages: [{ role: 'user', content: prompt }],
+                }),
+            });
+        }
+        catch (error) {
+            throw new EnvironmentError(controller.signal.aborted
+                ? `${this.options.baseUrl} did not answer within ${REQUEST_TIMEOUT_MS / 60_000} minutes.`
+                : `could not reach ${this.options.baseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            // The body distinguishes a bad key from an exhausted quota from an
+            // unknown model name, and the user needs to know which.
+            const detail = await response.text().catch(() => '');
+            throw new FailureError(`Anthropic returned HTTP ${response.status}${detail === '' ? '' : `: ${detail.slice(0, 400)}`}`);
+        }
+        return extractAnthropicText(await response.json());
+    }
+}

package/dist/llm/claudeCli.d.ts

@@ -0,0 +1,32 @@
+import type { Summarizer } from '@ailoud/core';
+import { run as defaultRunner } from '../process/run.js';
+export interface ClaudeCliOptions {
+    readonly binary: string;
+    /** A Claude Code alias such as "sonnet" or "opus", or a full model id. */
+    readonly model: string;
+    readonly contextTokens: number;
+    readonly runner?: typeof defaultRunner;
+}
+/**
+ * Claude through the Claude Code CLI, billed to the user's subscription.
+ *
+ * The reason this exists alongside the API adapter: a Claude subscription is
+ * not an API key, and someone who pays for one should not have to pay twice to
+ * summarise their own recordings. The CLI is already authenticated, so ailoud
+ * borrows that rather than asking for a second credential.
+ *
+ * `--print` makes it answer and exit instead of opening a session. Tools are
+ * switched off explicitly with an empty allow-list: this is a text completion,
+ * and an agent that could read files or run commands while summarising a
+ * transcript would be a much larger thing than the job asks for -- and would
+ * do it in whatever directory ailoud happened to be run from.
+ */
+export declare class ClaudeCliSummarizer implements Summarizer {
+    private readonly options;
+    readonly name = "claude-cli";
+    get model(): string;
+    private readonly runner;
+    constructor(options: ClaudeCliOptions);
+    get contextTokens(): number;
+    complete(prompt: string): Promise<string>;
+}

package/dist/llm/claudeCli.js

@@ -0,0 +1,63 @@
+import { FailureError } from '@ailoud/core';
+import { run as defaultRunner } from '../process/run.js';
+/**
+ * A hosted model reached through a local process. Longer than the direct API
+ * adapters allow, because this one also pays for process startup and the
+ * CLI's own session setup, but far short of the local model's hour.
+ */
+const COMPLETE_TIMEOUT_MS = 10 * 60_000;
+/**
+ * Claude through the Claude Code CLI, billed to the user's subscription.
+ *
+ * The reason this exists alongside the API adapter: a Claude subscription is
+ * not an API key, and someone who pays for one should not have to pay twice to
+ * summarise their own recordings. The CLI is already authenticated, so ailoud
+ * borrows that rather than asking for a second credential.
+ *
+ * `--print` makes it answer and exit instead of opening a session. Tools are
+ * switched off explicitly with an empty allow-list: this is a text completion,
+ * and an agent that could read files or run commands while summarising a
+ * transcript would be a much larger thing than the job asks for -- and would
+ * do it in whatever directory ailoud happened to be run from.
+ */
+export class ClaudeCliSummarizer {
+    options;
+    name = 'claude-cli';
+    get model() {
+        return this.options.model;
+    }
+    runner;
+    constructor(options) {
+        this.options = options;
+        this.runner = options.runner ?? defaultRunner;
+    }
+    get contextTokens() {
+        return this.options.contextTokens;
+    }
+    async complete(prompt) {
+        const result = await this.runner(this.options.binary, [
+            '--print',
+            '--model',
+            this.options.model,
+            // No tools. Summarising is a completion; an agent with file and shell
+            // access is not what was asked for, and the transcript is not a task
+            // for it to act on.
+            '--allowed-tools',
+            '',
+        ], 
+        // On stdin rather than as an argument. A transcript of any length passes
+        // ARG_MAX -- about a megabyte on macOS, less once the environment is
+        // counted -- and the spawn then fails with E2BIG, which is not something
+        // the user can fix.
+        { timeoutMs: COMPLETE_TIMEOUT_MS, stdin: prompt });
+        if (result.code !== 0) {
+            throw new FailureError(`${this.options.binary} failed: ${result.stderr.trim() || `exit ${result.code}`}. ` +
+                'If it is not signed in, run it once on its own first.');
+        }
+        const text = result.stdout.trim();
+        if (text === '') {
+            throw new FailureError(`${this.options.binary} returned nothing. Check that it is signed in by running it alone.`);
+        }
+        return text;
+    }
+}

package/dist/llm/llamaCpp.d.ts

@@ -0,0 +1,38 @@
+import type { Summarizer } from '@ailoud/core';
+import { run as defaultRunner } from '../process/run.js';
+export interface LlamaCppOptions {
+    readonly binary: string;
+    readonly modelPath: string;
+    readonly contextTokens: number;
+    /** Hard cap on the answer, so a model that starts looping cannot run forever. */
+    readonly maxOutputTokens: number;
+    readonly threads?: number;
+    readonly runner?: typeof defaultRunner;
+}
+/**
+ * Strips llama.cpp's own output from around the answer.
+ *
+ * With `-no-cnv --single-turn` the completion is what lands on stdout, but
+ * some builds echo the prompt back before it. Trimming rather than parsing:
+ * the output is prose, not a format, and a parser would be one more thing to
+ * break on the next release.
+ */
+export declare function cleanCompletion(stdout: string, prompt: string): string;
+/**
+ * A local model, run the way whisper.cpp is: one binary, one GGUF file,
+ * spawned per request.
+ *
+ * Per request rather than a resident server. It costs a model load each time
+ * -- seconds for a 3B -- but a CLI that leaves a daemon running is a CLI that
+ * then has to manage one, and nobody summarises in a tight loop.
+ */
+export declare class LlamaCppSummarizer implements Summarizer {
+    private readonly options;
+    readonly name = "llama.cpp";
+    get model(): string;
+    private readonly runner;
+    constructor(options: LlamaCppOptions);
+    get contextTokens(): number;
+    complete(prompt: string): Promise<string>;
+    private completeFrom;
+}

package/dist/llm/llamaCpp.js

@@ -0,0 +1,90 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { FailureError } from '@ailoud/core';
+import { run as defaultRunner } from '../process/run.js';
+/**
+ * Generation can legitimately take a long time on a laptop CPU: a few
+ * thousand tokens from a 3B model is minutes, not seconds, and summarising a
+ * long meeting is exactly that. A tighter bound would kill work that was
+ * going to succeed.
+ */
+const COMPLETE_TIMEOUT_MS = 60 * 60_000;
+/**
+ * Strips llama.cpp's own output from around the answer.
+ *
+ * With `-no-cnv --single-turn` the completion is what lands on stdout, but
+ * some builds echo the prompt back before it. Trimming rather than parsing:
+ * the output is prose, not a format, and a parser would be one more thing to
+ * break on the next release.
+ */
+export function cleanCompletion(stdout, prompt) {
+    let text = stdout;
+    const echoed = text.indexOf(prompt);
+    if (echoed !== -1)
+        text = text.slice(echoed + prompt.length);
+    return text.trim();
+}
+/**
+ * A local model, run the way whisper.cpp is: one binary, one GGUF file,
+ * spawned per request.
+ *
+ * Per request rather than a resident server. It costs a model load each time
+ * -- seconds for a 3B -- but a CLI that leaves a daemon running is a CLI that
+ * then has to manage one, and nobody summarises in a tight loop.
+ */
+export class LlamaCppSummarizer {
+    options;
+    name = 'llama.cpp';
+    get model() {
+        return basename(this.options.modelPath);
+    }
+    runner;
+    constructor(options) {
+        this.options = options;
+        this.runner = options.runner ?? defaultRunner;
+    }
+    get contextTokens() {
+        return this.options.contextTokens;
+    }
+    async complete(prompt) {
+        const dir = await mkdtemp(join(tmpdir(), 'ailoud-llm-'));
+        const promptPath = join(dir, 'prompt.txt');
+        try {
+            return await this.completeFrom(prompt, promptPath);
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    }
+    async completeFrom(prompt, promptPath) {
+        await writeFile(promptPath, prompt, 'utf8');
+        const result = await this.runner(this.options.binary, [
+            '-m',
+            this.options.modelPath,
+            '-c',
+            String(this.options.contextTokens),
+            '-n',
+            String(this.options.maxOutputTokens),
+            // A completion, not a chat session: anything interactive would sit
+            // waiting for input that is never coming.
+            '-no-cnv',
+            '--single-turn',
+            ...(this.options.threads === undefined ? [] : ['-t', String(this.options.threads)]),
+            // -f rather than -p: a prompt carrying a transcript does not fit in an
+            // argument. ARG_MAX is about a megabyte on macOS, less once the
+            // environment is counted, and the spawn then fails with E2BIG -- a
+            // failure the user can do nothing about.
+            '-f',
+            promptPath,
+        ], { timeoutMs: COMPLETE_TIMEOUT_MS });
+        if (result.code !== 0) {
+            throw new FailureError(`${this.name} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+        }
+        const text = cleanCompletion(result.stdout, prompt);
+        if (text === '') {
+            throw new FailureError(`${this.name} returned nothing. The transcript may be too large for the configured context.`);
+        }
+        return text;
+    }
+}

package/dist/llm/models.d.ts

@@ -0,0 +1,23 @@
+/** One model a provider says it will accept. */
+export interface ModelOption {
+    readonly id: string;
+    /** What to show in the picker: the vendor's display name where it gives one, else the id. */
+    readonly label: string;
+}
+export declare function isChatModel(id: string): boolean;
+/**
+ * The chat models an OpenAI-compatible endpoint will accept.
+ *
+ * Sorted newest-looking first only as far as the response allows: `created` is
+ * a unix timestamp on OpenAI's own API, and absent on most compatible servers,
+ * where the order is left as the server gave it.
+ */
+export declare function listOpenAiModels(baseUrl: string, apiKey: string | undefined, fetchImpl?: typeof fetch): Promise<readonly ModelOption[]>;
+/**
+ * The models Anthropic's API will accept, newest first.
+ *
+ * Paginated with `after_id` rather than taking the first page: the response
+ * carries `has_more`, and stopping at page one would quietly hide models from
+ * the picker with nothing on screen to say so.
+ */
+export declare function listAnthropicModels(baseUrl: string, apiKey: string, fetchImpl?: typeof fetch): Promise<readonly ModelOption[]>;

package/dist/llm/models.js

@@ -0,0 +1,97 @@
+import { EnvironmentError, FailureError } from '@ailoud/core';
+/** As elsewhere in this directory: a hosted call that has not answered in a minute is not going to. */
+const REQUEST_TIMEOUT_MS = 60_000;
+/** Anthropic pages its model list. Bounded so a misbehaving `has_more` cannot loop forever. */
+const MAX_PAGES = 10;
+/**
+ * Model ids that are not chat models.
+ *
+ * OpenAI's `/v1/models` is a catalogue of everything on the account --
+ * embeddings, speech, images, moderation -- with nothing in the response that
+ * distinguishes them, so the filtering has to happen on the id. A denylist of
+ * substrings rather than an allowlist of prefixes: a new `gpt-` chat model
+ * should appear in the picker the day it ships, which an allowlist would
+ * delay until someone remembered to widen it.
+ */
+const NOT_CHAT = [
+    'embedding',
+    'tts',
+    'whisper',
+    'dall-e',
+    'moderation',
+    'transcribe',
+    'image',
+    'realtime',
+    'audio',
+    'stt',
+];
+export function isChatModel(id) {
+    const lower = id.toLowerCase();
+    return !NOT_CHAT.some((marker) => lower.includes(marker));
+}
+async function getJson(url, headers, fetchImpl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetchImpl(url, { headers, signal: controller.signal });
+    }
+    catch (error) {
+        throw new EnvironmentError(controller.signal.aborted
+            ? `${url} did not answer within ${REQUEST_TIMEOUT_MS / 1000} seconds.`
+            : `could not reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        const detail = await response.text().catch(() => '');
+        throw new FailureError(`${url} returned HTTP ${response.status}${detail === '' ? '' : `: ${detail.slice(0, 300)}`}`);
+    }
+    return (await response.json());
+}
+/**
+ * The chat models an OpenAI-compatible endpoint will accept.
+ *
+ * Sorted newest-looking first only as far as the response allows: `created` is
+ * a unix timestamp on OpenAI's own API, and absent on most compatible servers,
+ * where the order is left as the server gave it.
+ */
+export async function listOpenAiModels(baseUrl, apiKey, fetchImpl = fetch) {
+    const url = `${baseUrl.replace(/\/+$/, '')}/models`;
+    const body = (await getJson(url, apiKey === undefined ? {} : { authorization: `Bearer ${apiKey}` }, fetchImpl));
+    const entries = (body.data ?? []).filter((entry) => typeof entry.id === 'string');
+    return entries
+        .filter((entry) => isChatModel(entry.id))
+        .sort((a, b) => (b.created ?? 0) - (a.created ?? 0))
+        .map((entry) => ({ id: entry.id, label: entry.id }));
+}
+/**
+ * The models Anthropic's API will accept, newest first.
+ *
+ * Paginated with `after_id` rather than taking the first page: the response
+ * carries `has_more`, and stopping at page one would quietly hide models from
+ * the picker with nothing on screen to say so.
+ */
+export async function listAnthropicModels(baseUrl, apiKey, fetchImpl = fetch) {
+    const root = `${baseUrl.replace(/\/+$/, '')}/models`;
+    const headers = { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' };
+    const collected = [];
+    let after;
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+        const url = `${root}?limit=100${after === undefined ? '' : `&after_id=${after}`}`;
+        const body = (await getJson(url, headers, fetchImpl));
+        for (const entry of body.data ?? []) {
+            if (typeof entry.id !== 'string')
+                continue;
+            collected.push({
+                id: entry.id,
+                label: typeof entry.display_name === 'string' ? entry.display_name : entry.id,
+            });
+        }
+        if (body.has_more !== true || typeof body.last_id !== 'string')
+            break;
+        after = body.last_id;
+    }
+    return collected;
+}

package/dist/llm/openAiCompatible.d.ts

@@ -0,0 +1,35 @@
+import type { Summarizer } from '@ailoud/core';
+export interface OpenAiCompatibleOptions {
+    /** Base URL up to but not including `/chat/completions`. */
+    readonly baseUrl: string;
+    readonly model: string;
+    readonly contextTokens: number;
+    readonly maxOutputTokens: number;
+    /** Absent means the endpoint needs no key, which a local server usually does not. */
+    readonly apiKey?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+/** The one field of the response this needs, and what to say when it is missing. */
+export declare function extractCompletion(body: unknown): string;
+/**
+ * Any endpoint speaking OpenAI's chat-completions shape.
+ *
+ * One adapter rather than one per vendor, because that shape is what almost
+ * everything speaks: OpenAI itself, most hosted alternatives, and -- usefully
+ * -- local servers like llama.cpp's own `llama-server`, Ollama and LM Studio.
+ * Someone who wants a bigger local model than spawning a process per request
+ * can bear points this at their own server and needs no new code here.
+ *
+ * The key is never read from the config file. It comes from the environment,
+ * because a config file is a thing people paste into issues and commit by
+ * accident, and a leaked key is not a mistake ailoud should make easy.
+ */
+export declare class OpenAiCompatibleSummarizer implements Summarizer {
+    private readonly options;
+    readonly name = "openai-compatible";
+    get model(): string;
+    private readonly fetchImpl;
+    constructor(options: OpenAiCompatibleOptions);
+    get contextTokens(): number;
+    complete(prompt: string): Promise<string>;
+}

package/dist/llm/openAiCompatible.js

@@ -0,0 +1,84 @@
+import { EnvironmentError, FailureError } from '@ailoud/core';
+/**
+ * A hosted model does not get the hour a local one does. If a request has not
+ * come back in five minutes it is not coming back, and a CLI hanging on a
+ * network call is worse than one that says so.
+ */
+const REQUEST_TIMEOUT_MS = 5 * 60_000;
+/** The one field of the response this needs, and what to say when it is missing. */
+export function extractCompletion(body) {
+    const choices = body.choices;
+    const content = choices?.[0]?.message?.content;
+    if (typeof content !== 'string' || content.trim() === '') {
+        throw new FailureError('the model returned no text. The response did not contain choices[0].message.content.');
+    }
+    return content.trim();
+}
+/**
+ * Any endpoint speaking OpenAI's chat-completions shape.
+ *
+ * One adapter rather than one per vendor, because that shape is what almost
+ * everything speaks: OpenAI itself, most hosted alternatives, and -- usefully
+ * -- local servers like llama.cpp's own `llama-server`, Ollama and LM Studio.
+ * Someone who wants a bigger local model than spawning a process per request
+ * can bear points this at their own server and needs no new code here.
+ *
+ * The key is never read from the config file. It comes from the environment,
+ * because a config file is a thing people paste into issues and commit by
+ * accident, and a leaked key is not a mistake ailoud should make easy.
+ */
+export class OpenAiCompatibleSummarizer {
+    options;
+    name = 'openai-compatible';
+    get model() {
+        return this.options.model;
+    }
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    get contextTokens() {
+        return this.options.contextTokens;
+    }
+    async complete(prompt) {
+        const url = `${this.options.baseUrl.replace(/\/+$/, '')}/chat/completions`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: {
+                    'content-type': 'application/json',
+                    ...(this.options.apiKey === undefined
+                        ? {}
+                        : { authorization: `Bearer ${this.options.apiKey}` }),
+                },
+                body: JSON.stringify({
+                    model: this.options.model,
+                    max_tokens: this.options.maxOutputTokens,
+                    messages: [{ role: 'user', content: prompt }],
+                }),
+            });
+        }
+        catch (error) {
+            // An aborted request and an unreachable host both land here, and the
+            // difference matters to whoever has to fix it.
+            throw new EnvironmentError(controller.signal.aborted
+                ? `${this.options.baseUrl} did not answer within ${REQUEST_TIMEOUT_MS / 60_000} minutes.`
+                : `could not reach ${this.options.baseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            // The body usually says which of key, quota or model name is wrong,
+            // and swallowing it would leave the user guessing between them.
+            const detail = await response.text().catch(() => '');
+            throw new FailureError(`${this.options.baseUrl} returned HTTP ${response.status}${detail === '' ? '' : `: ${detail.slice(0, 400)}`}`);
+        }
+        return extractCompletion(await response.json());
+    }
+}

package/dist/process/pager.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Output longer than this goes through a pager, when there is a terminal to
+ * page on. Below it, paging would put a full-screen program in front of
+ * something that already fitted.
+ */
+export declare const PAGER_LINE_THRESHOLD = 30;
+/**
+ * Whether this output should be paged at all.
+ *
+ * Never when stdout is not a terminal. A redirect or a pipe wants the bytes,
+ * and handing them to `less` would either hang waiting for a keypress nobody
+ * can give or write escape sequences into a file. This is the same
+ * distinction `show` already draws between the frame and the payload.
+ *
+ * Also never when PAGER is set to the empty string, which is the
+ * conventional way to say "do not page".
+ */
+export declare function shouldPage(text: string, isTTY: boolean, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Shows `text` in the user's pager, resolving when they leave it.
+ *
+ * Uses the system pager rather than scrolling in-process. Up, down, page
+ * keys, search, and quitting on `q` all arrive already implemented and
+ * already behaving the way the user's other tools do -- git, man and less
+ * itself -- which is what "native" means here. A hand-rolled scroller would
+ * be a worse version of `less` that nobody had configured.
+ *
+ * Defaults to `less -R`: -R lets colour through rather than printing escape
+ * sequences literally. LESS is set only if the user has not, so their own
+ * configuration keeps winning.
+ *
+ * Falls back to writing the text out plainly if the pager cannot be started
+ * at all -- a machine without `less` should still be able to read a
+ * transcript.
+ */
+export declare function page(text: string, write: (chunk: string) => void, env?: NodeJS.ProcessEnv): Promise<void>;