@north-light/api 0.3.579 → 0.3.587

package/dist/core/northlight/previews.js

@@ -0,0 +1,87 @@
+// The Northlight commands a computer without a Northlight account lists as previews. One table is the only copy of their text:
+// the help page and the needs-account answer are both rendered from it by `renderPreview`, and `previewBranches` mounts one
+// refusing branch per row. Nothing here reads a daemon or the network.
+import { defineBranch } from '../command.js';
+import { ExitCode } from '../../types.js';
+export const NORTHLIGHT_PREVIEWS = [
+    {
+        name: 'integrations',
+        concept: "The person's own accounts at other services (Gmail, Slack, Calendar, GitHub and more)",
+        description: "Read and act in the person's own accounts at other services",
+        useWhen: "the task needs data from or an action in one of the person's own accounts at another service, such as their email, calendar, chat or code host",
+        doesOnceSignedIn: "it lists the person's connected accounts, searches the services available to connect, and reads or acts in an account on their behalf, such as reading mail, posting a message or creating an event. Accounts the person has not connected yet are connected from their Northlight account.",
+    },
+    {
+        name: 'search',
+        concept: 'Web information and data',
+        description: 'Search the web and fetch data from the open internet',
+        useWhen: 'the task needs current information from the web or a data endpoint',
+        doesOnceSignedIn: 'it searches the web, reads pages and calls data endpoints and returns the results. A free allowance of $1 a month is included with a Northlight account.',
+    },
+    {
+        name: 'device',
+        concept: "The person's own Mac",
+        description: "Use the person's own signed-in browser, files and shell on their Mac",
+        useWhen: "a task needs the person's own signed-in browser (their logged-in sites), their Messages, or their files and shell on their Mac",
+        doesOnceSignedIn: "it runs on the person's Mac through the Northlight app: their own signed-in browser with ready-made functions for sites such as LinkedIn, Gmail and X, their Messages, and their files and shell. If the Northlight app is not on the Mac yet, the command that needs it says how to install it.",
+        platforms: ['darwin'],
+    },
+    {
+        name: 'sms',
+        concept: 'Text messages to the verified phone',
+        description: "Text the person's verified phone",
+        useWhen: 'the person should receive a text message, such as a finished result or an alert',
+        doesOnceSignedIn: "it sends a text message to the phone number the person verified with their Northlight account, and lists the texts sent.",
+    },
+    {
+        name: 'phone',
+        concept: "Phone calls placed by Northlight's AI voice",
+        description: 'Place a phone call with an AI voice and read what was said',
+        useWhen: 'the person wants a phone call placed for them, or the result of one',
+        doesOnceSignedIn: 'it places a phone call to a number the person gives, with an AI voice that follows their instructions, and returns the transcript and outcome of the call.',
+    },
+    {
+        name: 'meetings',
+        concept: 'Meeting notes and transcripts',
+        description: 'Search and read the notes and transcripts of recorded meetings',
+        useWhen: 'a task depends on what was said or decided in a meeting the person recorded',
+        doesOnceSignedIn: "it lists and searches the person's recorded meetings and returns their notes and transcripts.",
+    },
+];
+/** What the agent does when it needs a preview command: the same words in the help page and the refusal. A no covers only the command it was said for. */
+function askOnce(name) {
+    return `If the task in hand needs \`crtr ${name}\`, tell the person in one or two sentences what it would do for that task, that signing in creates or uses a Northlight account, and that crtr's records will then be stored with Northlight. Ask once whether to sign in; on yes run \`crtr sys signin\` yourself. If they already said no to \`${name}\` in this conversation, do not ask again: say it needs an account and carry on without it. A no covers \`${name}\` only: when the person later needs a different Northlight command (\`integrations\`, \`search\`, \`device\`, \`sms\`, \`phone\`, \`meetings\`), run it or its \`-h\` and ask once for that one.`;
+}
+/** The needs-account answer for one preview. */
+function refusalFor(row) {
+    return {
+        code: 'needs_northlight_account',
+        exit: ExitCode.USAGE,
+        message: `\`crtr ${row.name}\` needs a Northlight account. Once signed in, ${row.doesOnceSignedIn} Sign in with \`crtr sys signin\`: it opens a Northlight page in the browser where the person creates an account or signs in and clicks Allow, then moves crtr's records (agents, documents, history) to that account.`,
+        next: askOnce(row.name),
+    };
+}
+/** The one rendering of a preview's text: its help page (`crtr <name> -h`) and its refusal (any other invocation). */
+export function renderPreview(row) {
+    const refusal = refusalFor(row);
+    return {
+        summary: row.description,
+        model: `Needs a Northlight account. Once signed in, ${row.doesOnceSignedIn} Without an account every \`crtr ${row.name}\` command only answers that it needs one; sign in with \`crtr sys signin\`. ${askOnce(row.name)}`,
+        refusal,
+    };
+}
+/** One refusing branch per row listed on `platform`, skipping any name in `taken` (an installed bundle already provides it). */
+export function previewBranches(platform, taken) {
+    return NORTHLIGHT_PREVIEWS
+        .filter((row) => (row.platforms === undefined || row.platforms.includes(platform)) && !taken.has(row.name))
+        .map((row) => {
+        const { summary, model, refusal } = renderPreview(row);
+        return defineBranch({
+            name: row.name,
+            rootEntry: { concept: row.concept, desc: row.description, useWhen: row.useWhen },
+            help: { name: row.name, summary, model },
+            refusal,
+            children: [],
+        });
+    });
+}

package/dist/core/nvim-launch.d.ts

@@ -0,0 +1,7 @@
+export type NvimLaunchMode = 'readonly' | 'edit';
+/** Leading nvim arguments (before any `--` / file operands) for a launch mode. */
+export declare function nvimArgs(mode: NvimLaunchMode): string[];
+/** `nvim <args> -- <files>` as one shell-safe command string. */
+export declare function nvimShellCommand(mode: NvimLaunchMode, files: readonly string[], nvimBin?: string): string;
+/** Is `nvim` on PATH and runnable? */
+export declare function nvimAvailable(): boolean;

package/dist/core/nvim-launch.js

@@ -0,0 +1,45 @@
+// The single place that decides how crtr launches nvim for the person.
+//
+// Read-only views (transcripts, context explorer, loaded-command payloads) and
+// editable launches (linked files, profile-file search) all load the person's
+// own nvim config, then add — AFTER it, via `-c`, so it wins over their init —
+// a visible hint in the window's winbar. Read-only views also get `q` mapped
+// to quit, buffer-locally (an autocmd re-applies it to every buffer the view
+// opens, e.g. files entered from the netrw explorer). We never touch the
+// user's init files, and we leave an existing winbar of theirs alone. The lua
+// is inline (not a shipped file) so it cannot be missing from the package.
+import { spawnSync } from 'node:child_process';
+import { shellQuote } from '../shared/shell-quote.js';
+const READONLY_LUA = [
+    "local hint = ' q  quit   (:q also works) '",
+    'local function apply()',
+    "  vim.keymap.set('n', 'q', '<cmd>qa<CR>', { buffer = 0, nowait = true, silent = true, desc = 'quit' })",
+    "  if vim.wo.winbar == '' then vim.wo.winbar = hint end",
+    'end',
+    "vim.api.nvim_create_autocmd({ 'BufWinEnter', 'FileType' }, { callback = apply })",
+    'apply()',
+].join(' ');
+const EDIT_LUA = [
+    "local hint = ' :wq  save & quit   ·   :q!  quit without saving '",
+    "local function apply() if vim.wo.winbar == '' then vim.wo.winbar = hint end end",
+    "vim.api.nvim_create_autocmd({ 'BufWinEnter' }, { callback = apply })",
+    'apply()',
+].join(' ');
+/** Leading nvim arguments (before any `--` / file operands) for a launch mode. */
+export function nvimArgs(mode) {
+    return mode === 'readonly'
+        ? ['-R', '-c', `lua ${READONLY_LUA}`]
+        : ['-c', `lua ${EDIT_LUA}`];
+}
+/** `nvim <args> -- <files>` as one shell-safe command string. */
+export function nvimShellCommand(mode, files, nvimBin = 'nvim') {
+    const parts = [shellQuote(nvimBin), ...nvimArgs(mode).map(shellQuote)];
+    if (files.length > 0)
+        parts.push('--', ...files.map(shellQuote));
+    return parts.join(' ');
+}
+/** Is `nvim` on PATH and runnable? */
+export function nvimAvailable() {
+    const r = spawnSync('nvim', ['--version'], { stdio: 'ignore' });
+    return r.error === undefined && (r.status === 0 || r.status === null);
+}

package/dist/core/output.d.ts

@@ -0,0 +1,35 @@
+import { CrtrError } from './errors.js';
+export declare const stdoutColor: {
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+};
+export declare const stderrColor: {
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+};
+export declare function out(line: string): void;
+export declare function err(line: string): void;
+export declare function hint(line: string): void;
+export declare function warn(line: string): void;
+export declare function info(line: string): void;
+export declare function jsonOut(obj: unknown): void;
+export declare function jsonError(error: CrtrError | Error): void;
+export declare function isTTY(): boolean;
+export declare function isJsonRequested(opts: {
+    json?: boolean;
+} | undefined): boolean;
+export declare function handleError(error: unknown, opts?: {
+    json?: boolean;
+}): never;

package/dist/core/output.js

@@ -0,0 +1,99 @@
+import { CrtrError } from './errors.js';
+import { ExitCode, SCHEMA_VERSION } from '../types.js';
+const ANSI = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+function shouldColor(stream) {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return Boolean(stream.isTTY);
+}
+function paint(stream, code, text) {
+    return shouldColor(stream) ? `${code}${text}${ANSI.reset}` : text;
+}
+export const stdoutColor = {
+    dim: (s) => paint(process.stdout, ANSI.dim, s),
+    bold: (s) => paint(process.stdout, ANSI.bold, s),
+    red: (s) => paint(process.stdout, ANSI.red, s),
+    green: (s) => paint(process.stdout, ANSI.green, s),
+    yellow: (s) => paint(process.stdout, ANSI.yellow, s),
+    blue: (s) => paint(process.stdout, ANSI.blue, s),
+    cyan: (s) => paint(process.stdout, ANSI.cyan, s),
+    gray: (s) => paint(process.stdout, ANSI.gray, s),
+};
+export const stderrColor = {
+    dim: (s) => paint(process.stderr, ANSI.dim, s),
+    bold: (s) => paint(process.stderr, ANSI.bold, s),
+    red: (s) => paint(process.stderr, ANSI.red, s),
+    green: (s) => paint(process.stderr, ANSI.green, s),
+    yellow: (s) => paint(process.stderr, ANSI.yellow, s),
+    blue: (s) => paint(process.stderr, ANSI.blue, s),
+    cyan: (s) => paint(process.stderr, ANSI.cyan, s),
+    gray: (s) => paint(process.stderr, ANSI.gray, s),
+};
+export function out(line) {
+    process.stdout.write(line.endsWith('\n') ? line : line + '\n');
+}
+export function err(line) {
+    process.stderr.write(line.endsWith('\n') ? line : line + '\n');
+}
+export function hint(line) {
+    err(stderrColor.dim(`# ${line}`));
+}
+export function warn(line) {
+    err(stderrColor.yellow(`crtr: ${line}`));
+}
+export function info(line) {
+    err(stderrColor.gray(`crtr: ${line}`));
+}
+export function jsonOut(obj) {
+    const enriched = typeof obj === 'object' && obj !== null && !Array.isArray(obj)
+        ? { schema_version: SCHEMA_VERSION, ...obj }
+        : { schema_version: SCHEMA_VERSION, data: obj };
+    process.stdout.write(JSON.stringify(enriched, null, 2) + '\n');
+}
+export function jsonError(error) {
+    const e = error instanceof CrtrError ? error : new CrtrError('error', error.message, ExitCode.GENERAL);
+    process.stdout.write(JSON.stringify({
+        schema_version: SCHEMA_VERSION,
+        error: true,
+        code: e.code,
+        message: e.message,
+        ...(e.details ?? {}),
+    }, null, 2) + '\n');
+}
+export function isTTY() {
+    return Boolean(process.stdout.isTTY);
+}
+export function isJsonRequested(opts) {
+    return Boolean(opts?.json);
+}
+export function handleError(error, opts = {}) {
+    if (error instanceof CrtrError) {
+        if (opts.json) {
+            jsonError(error);
+        }
+        else {
+            err(stderrColor.red(`crtr: ${error.message}`));
+        }
+        process.exit(error.exitCode);
+    }
+    const e = error;
+    if (opts.json) {
+        jsonError(e);
+    }
+    else {
+        err(stderrColor.red(`crtr: ${e.message ?? String(e)}`));
+    }
+    process.exit(ExitCode.GENERAL);
+}

package/dist/core/pagination.d.ts

@@ -0,0 +1,35 @@
+/** Encodes a stable sort key into an opaque base64url cursor token. */
+export declare function encodeCursor(key: string): string;
+/** Decodes an opaque cursor token back to the sort key it encodes.
+ *  Throws `CrtrError` with code `'invalid_cursor'` on malformed input. */
+export declare function decodeCursor(token: string): string;
+export interface PaginateResult<T> {
+    items: T[];
+    next_cursor: string | null;
+    total: number | null;
+}
+export interface PaginateOpts<T> {
+    /** Default page size when `params.limit` is absent. */
+    defaultLimit: number;
+    /** Hard cap; `params.limit` is clamped to [1, maxLimit]. */
+    maxLimit: number;
+    /** Returns the stable sort key for an item. Must match the sort order of the
+     *  input array — ascending by this key. */
+    keyOf: (item: T) => string;
+    /** Compares sort keys when their order is not raw code-unit order. */
+    compareKeys?: (left: string, right: string) => number;
+    /** 'count' → compute and return `total`; 'omit' → return `null`. */
+    total: 'count' | 'omit';
+}
+/**
+ * Returns one page of items from a pre-sorted list, with a stable opaque
+ * cursor for resumption.
+ *
+ * @param allItemsSortedAscByKey - Full dataset, sorted ascending by `keyOf`.
+ * @param params - Agent-supplied `{ limit?, cursor? }` from stdin.
+ * @param opts - Caller-supplied configuration (limits, key extractor, total).
+ */
+export declare function paginate<T>(allItemsSortedAscByKey: T[], params: {
+    limit?: number;
+    cursor?: string;
+}, opts: PaginateOpts<T>): PaginateResult<T>;

package/dist/core/pagination.js

@@ -0,0 +1,88 @@
+// Pagination helper for agent-facing paginated list leaves.
+//
+// Precondition: `allItemsSortedAscByKey` MUST be sorted ascending by the value
+// `keyOf` returns. Sort order is part of each leaf's contract — this module
+// trusts the caller. Violating the precondition produces silently wrong pages.
+//
+// Cursor design: encodes the stable sort key of the last-emitted item as
+// base64url JSON `{k: <sortKey>}`. Resumption seeks the first item whose key
+// is strictly greater than the cursor key — stable under inserts and deletes
+// between pages (a deleted cursor key simply doesn't stall the scan; the next
+// item after it is returned correctly).
+import { CrtrError } from './errors.js';
+import { ExitCode } from '../types.js';
+// Cursor encoding / decoding
+/** Encodes a stable sort key into an opaque base64url cursor token. */
+export function encodeCursor(key) {
+    const json = JSON.stringify({ k: key });
+    return Buffer.from(json, 'utf8').toString('base64url');
+}
+/** Decodes an opaque cursor token back to the sort key it encodes.
+ *  Throws `CrtrError` with code `'invalid_cursor'` on malformed input. */
+export function decodeCursor(token) {
+    let json;
+    try {
+        json = Buffer.from(token, 'base64url').toString('utf8');
+    }
+    catch {
+        throw new CrtrError('invalid_cursor', 'cursor could not be decoded.', ExitCode.USAGE, {
+            received: token,
+            next: 'Omit cursor to restart from the beginning.',
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new CrtrError('invalid_cursor', 'cursor payload is not valid JSON.', ExitCode.USAGE, {
+            received: token,
+            next: 'Omit cursor to restart from the beginning.',
+        });
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !('k' in parsed) ||
+        typeof parsed.k !== 'string') {
+        throw new CrtrError('invalid_cursor', 'cursor payload is missing required key field.', ExitCode.USAGE, {
+            received: token,
+            next: 'Omit cursor to restart from the beginning.',
+        });
+    }
+    return parsed.k;
+}
+/**
+ * Returns one page of items from a pre-sorted list, with a stable opaque
+ * cursor for resumption.
+ *
+ * @param allItemsSortedAscByKey - Full dataset, sorted ascending by `keyOf`.
+ * @param params - Agent-supplied `{ limit?, cursor? }` from stdin.
+ * @param opts - Caller-supplied configuration (limits, key extractor, total).
+ */
+export function paginate(allItemsSortedAscByKey, params, opts) {
+    // Resolve effective limit: clamp to [1, maxLimit], default when absent.
+    const rawLimit = params.limit !== undefined ? params.limit : opts.defaultLimit;
+    const effectiveLimit = Math.min(Math.max(1, rawLimit), opts.maxLimit);
+    // Resolve start position from cursor.
+    let startIndex = 0;
+    if (params.cursor !== undefined) {
+        const cursorKey = decodeCursor(params.cursor); // throws CrtrError on bad cursor
+        const compareKeys = opts.compareKeys ?? ((left, right) => left < right ? -1 : left > right ? 1 : 0);
+        // Find the first item whose key is strictly greater than cursorKey.
+        // Linear scan; callers with large datasets should pre-filter upstream.
+        startIndex = allItemsSortedAscByKey.findIndex((item) => compareKeys(opts.keyOf(item), cursorKey) > 0);
+        if (startIndex === -1) {
+            // All items are at or before the cursor key — list is exhausted.
+            startIndex = allItemsSortedAscByKey.length;
+        }
+    }
+    const page = allItemsSortedAscByKey.slice(startIndex, startIndex + effectiveLimit);
+    // next_cursor: null is the ONLY end-of-list signal.
+    let next_cursor = null;
+    if (page.length === effectiveLimit && startIndex + effectiveLimit < allItemsSortedAscByKey.length) {
+        const lastKey = opts.keyOf(page[page.length - 1]);
+        next_cursor = encodeCursor(lastKey);
+    }
+    const total = opts.total === 'count' ? allItemsSortedAscByKey.length : null;
+    return { items: page, next_cursor, total };
+}

package/dist/core/peer/client.d.ts

@@ -0,0 +1,61 @@
+import { type DirectoryClient } from './directory.js';
+import { type Envelope } from './envelope.js';
+import { type TokenCache } from './token.js';
+/** One attempt's budget. The hosting router gives an envelope-bearing request a 120 s header deadline; a cold wake must finish inside it. */
+export declare const PEER_CALL_TIMEOUT_MS = 120000;
+/** How long a `503 runtime_starting`, or a repeatable request's `503 runtime_unreachable` with `Retry-After`, is retried before the machine counts as unreachable. */
+export declare const RUNTIME_STARTING_RETRY_BUDGET_MS = 60000;
+/** First and longest wait between `runtime_starting` retries (doubling). */
+export declare const RUNTIME_STARTING_BACKOFF_MS: {
+    readonly first: 1000;
+    readonly max: 8000;
+};
+/** Largest response body read, in bytes. Matches the relay's body cap. */
+export declare const MAX_PEER_RESPONSE_BYTES: number;
+export interface PeerRequest {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Absolute path on the callee, e.g. `/v1/nodes/<id>/messages`. */
+    path: string;
+    query?: Record<string, string | number | boolean | undefined> | URLSearchParams;
+    /** Serialized as JSON. */
+    body?: unknown;
+}
+export interface PeerOptions {
+    /** On whose behalf the call is made. Without one the call is the machine's own (class `machine` rows). */
+    envelope?: Envelope;
+    /** Ends the call early (the caller's own budget ran out); the result is then `{unreachable: timeout}`. */
+    signal?: AbortSignal;
+    /** Allow a `kind = device` machine as the target. Only device selection in `provider.call` passes it; every other caller treats a device machine as no peer at all. */
+    device?: boolean;
+}
+export interface PeerResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export type UnreachableReason = 'no_directory' | 'unknown_machine' | 'directory_unreachable' | 'network' | 'timeout' | 'machine_offline' | 'runtime_starting' | 'not_a_crtr_peer';
+export interface PeerUnreachable {
+    reason: UnreachableReason;
+    message: string;
+}
+export type PeerResult = PeerResponse | {
+    unreachable: PeerUnreachable;
+};
+export declare const isUnreachable: (result: PeerResult) => result is {
+    unreachable: PeerUnreachable;
+};
+export interface PeerDeps {
+    issuer(): string | null;
+    directory: DirectoryClient;
+    tokens: TokenCache;
+    fetch: typeof fetch;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+    version(): string;
+    timeoutMs: number;
+    startingBudgetMs: number;
+}
+export declare function createPeerCall(deps: PeerDeps): (machineId: string, request: PeerRequest, options?: PeerOptions) => Promise<PeerResult>;
+/** Call a machine of this account. Resolves reach through the directory (cached 5 min), authenticates with a peer call token for the callee's URL,
+ *  and retries `503 runtime_starting` (and, for GET/PUT/DELETE, `503 runtime_unreachable` carrying `Retry-After`). See the module header for the two kinds of result. */
+export declare const peerCall: (machineId: string, request: PeerRequest, options?: PeerOptions) => Promise<PeerResult>;

package/dist/core/peer/client.js

@@ -0,0 +1,167 @@
+// `peerCall`: one HTTPS request to another machine of the same account.
+//
+// The address is the directory's `url` for that machine, for both reach kinds
+// (stable: the hosted URL through hosting's router; relay: the machine's relay
+// host). The bearer is a peer call token whose `aud` is that URL. Nothing here
+// holds a connection to the callee.
+//
+// Outcomes:
+//   - the callee (or the router in front of it) answered: `{status, headers, body}`,
+//     including 4xx/5xx the callee chose (403, 404, 426 ...);
+//   - nobody answered: `{unreachable: {reason, message}}` -- no directory, unknown
+//     machine, network failure, `503 machine_offline`, `504`, a timeout, or a
+//     `503 runtime_starting` that outlasted its retry budget.
+import { crtrVersion } from '../../shared/crtr-version.js';
+import { directory, normalizeMachineId } from './directory.js';
+import { directoryIssuer } from '../directory/issuer.js';
+import { ENVELOPE_HEADER, encodeEnvelope } from './envelope.js';
+import { peerTokens } from './token.js';
+import { PEER_VERSION_FLOOR, PEER_VERSION_HEADER, peerVersionRefusal } from './version.js';
+/** One attempt's budget. The hosting router gives an envelope-bearing request a 120 s header deadline; a cold wake must finish inside it. */
+export const PEER_CALL_TIMEOUT_MS = 120_000;
+/** How long a `503 runtime_starting`, or a repeatable request's `503 runtime_unreachable` with `Retry-After`, is retried before the machine counts as unreachable. */
+export const RUNTIME_STARTING_RETRY_BUDGET_MS = 60_000;
+/** First and longest wait between `runtime_starting` retries (doubling). */
+export const RUNTIME_STARTING_BACKOFF_MS = { first: 1_000, max: 8_000 };
+/** Largest response body read, in bytes. Matches the relay's body cap. */
+export const MAX_PEER_RESPONSE_BYTES = 16 * 1024 * 1024;
+/** Verbs that can be sent again after a `503 runtime_unreachable` without repeating a side effect. */
+const REPEATABLE_METHODS = new Set(['GET', 'PUT', 'DELETE']);
+export const isUnreachable = (result) => 'unreachable' in result;
+const unreachable = (reason, message) => ({ unreachable: { reason, message } });
+function errorCode(body) {
+    const error = body?.error;
+    if (typeof error === 'string')
+        return error;
+    const code = error?.code;
+    return typeof code === 'string' ? code : null;
+}
+async function readBody(response) {
+    const declared = Number(response.headers.get('content-length') ?? '0');
+    if (declared > MAX_PEER_RESPONSE_BYTES)
+        throw new RangeError('the peer answer is too large');
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength > MAX_PEER_RESPONSE_BYTES)
+        throw new RangeError('the peer answer is too large');
+    const text = new TextDecoder().decode(bytes);
+    if (text === '')
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function targetUrl(machine, request) {
+    const url = new URL(`${machine.url}${request.path.startsWith('/') ? '' : '/'}${request.path}`);
+    const query = request.query instanceof URLSearchParams ? request.query : Object.entries(request.query ?? {});
+    for (const [key, value] of query instanceof URLSearchParams ? query.entries() : query)
+        if (value !== undefined)
+            url.searchParams.append(key, String(value));
+    return url.toString();
+}
+export function createPeerCall(deps) {
+    return async function peerCall(machineId, request, options = {}) {
+        const issuer = deps.issuer();
+        if (issuer === null)
+            return unreachable('no_directory', 'this machine is not joined to a Northlight account, so it has no peers');
+        let machine;
+        try {
+            machine = await deps.directory.reach(machineId);
+        }
+        catch (error) {
+            // Only a confirmed 404 (null below) means the machine is unknown; any directory failure says nothing about the peer.
+            return unreachable('directory_unreachable', error instanceof Error ? error.message : String(error));
+        }
+        if (machine === null)
+            return unreachable('unknown_machine', `No machine ${normalizeMachineId(machineId)} on your account.`);
+        // A device machine is a call target, never a crtr peer: only the device selection in `provider.call` may reach one.
+        if (machine.kind === 'device' && options.device !== true) {
+            return unreachable('not_a_crtr_peer', `${machine.name} is a device, not a crtr peer.`);
+        }
+        // A peer known to be below the floor is refused before anything is sent, with the receiver's own refusal shape.
+        const tooOld = machine.crtr_version === null ? null : peerVersionRefusal(machine.crtr_version, PEER_VERSION_FLOOR, deps.version());
+        if (tooOld !== null) {
+            return { status: 426, headers: {}, body: { error: { code: tooOld.code, message: `${machine.name} runs crtr ${machine.crtr_version}; peers below ${PEER_VERSION_FLOOR} cannot take part. Update it with \`crtr sys update\`.`,
+                        details: { peer_version: machine.crtr_version, floor: PEER_VERSION_FLOOR, receiver_version: deps.version() } } } };
+        }
+        const url = targetUrl(machine, request);
+        const started = deps.now();
+        let wait = RUNTIME_STARTING_BACKOFF_MS.first;
+        let renewed = false;
+        let retried = false;
+        for (;;) {
+            let response;
+            try {
+                const token = await deps.tokens.get(issuer, machine.url);
+                response = await deps.fetch(url, {
+                    method: request.method,
+                    redirect: 'manual',
+                    headers: { authorization: `Bearer ${token}`, [PEER_VERSION_HEADER]: deps.version(),
+                        ...(options.envelope ? { [ENVELOPE_HEADER]: encodeEnvelope(options.envelope) } : {}),
+                        ...(request.body === undefined ? {} : { 'content-type': 'application/json' }) },
+                    ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+                    // A retry never runs past the `runtime_starting` budget it was started under.
+                    signal: AbortSignal.any([AbortSignal.timeout(retried ? Math.max(1_000, Math.min(deps.timeoutMs, deps.startingBudgetMs - (deps.now() - started))) : deps.timeoutMs),
+                        ...(options.signal ? [options.signal] : [])]),
+                });
+            }
+            catch (error) {
+                if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {
+                    return unreachable('timeout', `${machine.name} did not answer within ${Math.round(deps.timeoutMs / 1000)} s.`);
+                }
+                if (error instanceof Error && /directory/.test(error.message))
+                    return unreachable('directory_unreachable', error.message);
+                return unreachable('network', `${machine.name} could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            let body;
+            try {
+                body = await readBody(response);
+            }
+            catch (error) {
+                if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError'))
+                    return unreachable('timeout', `${machine.name} did not finish its answer within ${Math.round(deps.timeoutMs / 1000)} s.`);
+                return unreachable('network', `${machine.name}'s answer could not be read: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const code = errorCode(body);
+            const headers = Object.fromEntries(response.headers.entries());
+            if (response.status === 401 && !renewed) {
+                // The far side may have refused a token that expired in transit or by clock skew: mint one more, once.
+                renewed = true;
+                deps.tokens.drop(issuer, machine.url);
+                continue;
+            }
+            if (response.status === 503 && code === 'machine_offline')
+                return unreachable('machine_offline', `${machine.name} is offline.`);
+            if (response.status === 504)
+                return unreachable('timeout', `${machine.name} did not answer in time.`);
+            if (response.status === 503 && code === 'runtime_starting') {
+                if (deps.now() - started + wait > deps.startingBudgetMs)
+                    return unreachable('runtime_starting', `${machine.name} is still starting.`);
+                await deps.sleep(wait);
+                wait = Math.min(wait * 2, RUNTIME_STARTING_BACKOFF_MS.max);
+                retried = true;
+                continue;
+            }
+            // The hosting router answers `503 runtime_unreachable` + `Retry-After` for a failed route lookup or forward (a deploy, a restarting
+            // provisioning pod). The body does not say whether the request reached the guest, so only a verb that is safe to repeat is retried.
+            // Past the budget the 503 itself is the answer.
+            const retryAfterS = Number(headers['retry-after']);
+            if (response.status === 503 && code === 'runtime_unreachable' && REPEATABLE_METHODS.has(request.method) && headers['retry-after'] !== undefined
+                && Number.isFinite(retryAfterS) && retryAfterS >= 0 && deps.now() - started + retryAfterS * 1_000 <= deps.startingBudgetMs) {
+                await deps.sleep(retryAfterS * 1_000);
+                retried = true;
+                continue;
+            }
+            return { status: response.status, headers, body };
+        }
+    };
+}
+/** Call a machine of this account. Resolves reach through the directory (cached 5 min), authenticates with a peer call token for the callee's URL,
+ *  and retries `503 runtime_starting` (and, for GET/PUT/DELETE, `503 runtime_unreachable` carrying `Retry-After`). See the module header for the two kinds of result. */
+export const peerCall = createPeerCall({
+    issuer: directoryIssuer, directory, tokens: peerTokens, fetch: (input, init) => fetch(input, init),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now: Date.now, version: crtrVersion,
+    timeoutMs: PEER_CALL_TIMEOUT_MS, startingBudgetMs: RUNTIME_STARTING_RETRY_BUDGET_MS,
+});