@haywoodmarx/agent-pager 0.1.0

package/dist/src/tui/production.js

@@ -0,0 +1,253 @@
+import { createElement } from "react";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isPlainObject } from "../shared/guards.js";
+import { OperatorTui } from "./app.js";
+import { TuiOperatorTcpClient } from "./client.js";
+import { startOpenTuiFactory } from "./composition.js";
+import { TuiOperatorModel } from "./model.js";
+import { messageBodyDisplayText } from "./presentation.js";
+import { defineTuiTheme } from "./theme.js";
+/** Canonical semantic palette selected by the production terminal command. */
+export const DEFAULT_OPERATOR_TUI_THEME = defineTuiTheme({
+    structure: {
+        background: "#0c0e0f",
+        selection: { background: "#6d7275", text: "#0c0e0f" },
+        dimBackdrop: "#4a5053",
+        rulesAndLabels: "#6d7275",
+        bodyText: "#c2c0b8",
+        emphasis: "#e6e4dc",
+    },
+    agents: ["#7fa8a8", "#b090c0", "#8fae7f", "#7f9ec2", "#c39a6b", "#c2857f"],
+    states: { complete: "#7fa87f", inProgress: "#c2a05f", failed: "#c25f5f", expired: "#6d7275" },
+});
+/**
+ * Start the production terminal surface from explicitly composed client and presentation ports.
+ * @param options - Model, presentation ports, and optional renderer configuration.
+ * @param start - Starts the renderer, supplying the shutdown action to the factory that builds the root element; the OpenTUI starter by default.
+ * @returns Running renderer lifecycle whose caller owns the final shutdown request.
+ */
+export function startOperatorTui(options, start = startOpenTuiFactory) {
+    return start((shutdown) => createElement(OperatorTui, {
+        ...options,
+        onShutdown: shutdown,
+    }), options.runtime);
+}
+/**
+ * Build the production model and retained-body adapter from the published operator state endpoint.
+ * @param options - Endpoint, palette, and optional clipboard, local-command, and layout ports.
+ * @returns The shell's model, palette, body reader, copy fallback and command port, without its shutdown action or action catalogue.
+ */
+export function createOperatorTuiClient({ operatorUrl, theme, clipboard = systemNativeClipboard(), localCommand = systemLocalCommand(), layout, }) {
+    const client = new TuiOperatorTcpClient(operatorUrl);
+    const model = new TuiOperatorModel({
+        snapshot: { fetch: () => client.fetch() },
+        stream: { open: (cursor, receive, unavailable) => client.open(cursor, receive, unavailable) },
+        reconnect: { reconnect: () => client.reconnect() },
+        command: {
+            execute: (command) => client.execute(command),
+        },
+        scheduler: createTimerScheduler(setTimeout, clearTimeout),
+        localCommand,
+        disposal: { dispose: () => client.dispose() },
+        ...(layout ? { layout } : {}),
+        now: () => Date.now(),
+    });
+    return {
+        model,
+        theme,
+        body: retainedOperatorBody,
+        copyFallback: { copyUnavailable: (rawCopy) => (clipboard.copy(rawCopy) ? "copied" : "unavailable") },
+        commands: { commandId: () => crypto.randomUUID(), issuedAt: () => Date.now(), observe: () => undefined },
+    };
+}
+/**
+ * Keep dragged pane widths in a file beside the operator's other local state.
+ *
+ * Every failure resolves to "no stored layout": the file is a convenience, and an operator locked out
+ * of the surface because a width could not be parsed would be worse off than one whose panes reset.
+ * @param storeDirectory - Directory the operator's local state lives in.
+ * @returns - Port reading and writing that directory's layout file.
+ */
+export function fileBackedTuiLayout(storeDirectory) {
+    const path = join(storeDirectory, "tui-layout.json");
+    return {
+        read() {
+            try {
+                const parsed = JSON.parse(readFileSync(path, "utf8"));
+                if (!isPlainObject(parsed))
+                    return null;
+                return {
+                    treeColumns: paneColumns(parsed.treeColumns),
+                    messageLogColumns: paneColumns(parsed.messageLogColumns),
+                };
+            }
+            catch {
+                return null;
+            }
+        },
+        write(layout) {
+            try {
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, JSON.stringify(layout));
+            }
+            catch {
+                return;
+            }
+        },
+    };
+}
+function paneColumns(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+/**
+ * Run a local command attached to a pseudo-terminal, streaming its raw bytes to the model.
+ *
+ * Output is captured rather than inherited: the renderer owns the terminal, so a child writing to it
+ * directly would overwrite the frame.
+ *
+ * The child is given a pseudo-terminal rather than pipes. Seeing pipes, a child reports no terminal
+ * and takes whatever silent non-interactive path it has, so an operator could never answer a question
+ * it asks.
+ * @returns - Port that spawns through the operating system.
+ */
+export function systemLocalCommand() {
+    return {
+        run(command, args, size, observe) {
+            let settled = false;
+            const settle = (event) => {
+                if (settled)
+                    return;
+                settled = true;
+                observe(event);
+            };
+            // Every byte is reported before the exit whichever of the process's end and the terminal's end of
+            // file Bun dispatches first, since the exit waits for both.
+            let exitCode = null;
+            let drained = null;
+            const finish = () => {
+                if (exitCode === null || drained === null)
+                    return;
+                if (!drained.closed)
+                    drained.close();
+                settle({ type: "exit", code: exitCode });
+            };
+            let child;
+            try {
+                // Given inline, the terminal's `exit` is the end-of-file signal `finish` waits for.
+                child = Bun.spawn([command, ...args], {
+                    terminal: {
+                        cols: size.columns,
+                        rows: size.rows,
+                        data(_terminal, chunk) {
+                            observe({ type: "output", bytes: chunk });
+                        },
+                        exit(terminal) {
+                            drained = terminal;
+                            finish();
+                        },
+                    },
+                });
+            }
+            catch (error) {
+                settle({ type: "failed", reason: error instanceof Error ? error.message : String(error) });
+                return null;
+            }
+            const pty = child.terminal;
+            if (pty === undefined) {
+                child.kill();
+                settle({ type: "failed", reason: "the command was started without a terminal" });
+                return null;
+            }
+            void child.exited.then((code) => {
+                exitCode = code;
+                finish();
+            }, (error) => {
+                pty.close();
+                settle({ type: "failed", reason: error instanceof Error ? error.message : String(error) });
+            });
+            return {
+                write(bytes) {
+                    if (!settled && !pty.closed)
+                        pty.write(bytes);
+                },
+                resize(columns, rows) {
+                    if (!settled && !pty.closed)
+                        pty.resize(columns, rows);
+                },
+                stop() {
+                    if (settled)
+                        return;
+                    const spawned = child;
+                    spawned.kill();
+                    if (!pty.closed)
+                        pty.close();
+                },
+            };
+        },
+    };
+}
+/**
+ * Build the reconnect scheduler over an explicit timer, so the delay the model asks for is observable.
+ * @param set - Arms one timer for the requested delay and returns the handle that cancels it.
+ * @param clear - Cancels a handle `set` returned, whether or not it has already fired.
+ * @returns Scheduler port whose cancellation callback clears the handle it armed.
+ */
+export function createTimerScheduler(set, clear) {
+    return {
+        schedule: (callback, delayMs) => {
+            const handle = set(callback, delayMs);
+            return () => clear(handle);
+        },
+    };
+}
+function systemNativeClipboard() {
+    return createNativeClipboardPort(process.platform, (command, arguments_, rawCopy, timeout) => {
+        const result = spawnSync(command, [...arguments_], {
+            input: rawCopy,
+            stdio: ["pipe", "ignore", "ignore"],
+            timeout,
+        });
+        return !result.error && result.status === 0;
+    });
+}
+/**
+ * Build a bounded native clipboard port from explicit platform command execution.
+ * @param platform - Operating system whose clipboard commands are tried, in order; any other copies nothing.
+ * @param run - Runs one command with the raw text on standard input, reporting success; a throw counts as failure.
+ * @returns Port that reports whether any command copied the text within its time limit.
+ */
+export function createNativeClipboardPort(platform, run) {
+    const commands = platform === "darwin"
+        ? [["pbcopy", []]]
+        : platform === "linux"
+            ? [
+                ["wl-copy", []],
+                ["xclip", ["-selection", "clipboard"]],
+            ]
+            : platform === "win32"
+                ? [["clip.exe", []]]
+                : [];
+    return {
+        copy(rawCopy) {
+            for (const [command, arguments_] of commands) {
+                try {
+                    if (run(command, arguments_, rawCopy, NATIVE_CLIPBOARD_TIMEOUT_MS))
+                        return true;
+                }
+                catch {
+                    continue;
+                }
+            }
+            return false;
+        },
+    };
+}
+const NATIVE_CLIPBOARD_TIMEOUT_MS = 500;
+const retainedOperatorBody = {
+    read: (message) => ({
+        display: messageBodyDisplayText(message.body.content),
+        rawCopy: message.body.rawCopy,
+    }),
+};

package/dist/src/tui/run-terminal.d.ts

@@ -0,0 +1,32 @@
+import { EmbeddedTerminalRenderable } from "@opentui/core";
+declare module "@opentui/react" {
+    interface OpenTUIComponents {
+        embeddedTerminal: typeof EmbeddedTerminalRenderable;
+    }
+}
+/**
+ * Render a child's terminal output as the child itself drew it.
+ *
+ * The preamble is written first, so the command sits in the terminal as though it had been typed there
+ * and the child's output follows it. The chunks are then replayed from the first byte on every mount,
+ * because the emulator's screen is derived from the whole sequence: a chunk applied to a fresh screen
+ * lands in the wrong place.
+ *
+ * Focus is what routes the operator's keys here, and it also tells the emulator to encode them for the
+ * keyboard mode the child has asked for, which no caller can know.
+ * @param properties - Command to show before anything runs, byte stream and how many chunks it has
+ * ever held, viewport size, whether the child is still taking input, whether the run is spent, and the
+ * sinks for what the emulator sends back.
+ * @returns - Embedded terminal element sized to the given viewport.
+ */
+export declare function RunTerminal({ preamble, chunks, received, columns, rows, live, dimmed, onInput, onResize, }: {
+    readonly preamble: string;
+    readonly chunks: readonly Uint8Array[];
+    readonly received: number;
+    readonly columns: number;
+    readonly rows: number;
+    readonly live: boolean;
+    readonly dimmed: boolean;
+    readonly onInput: (bytes: Uint8Array) => void;
+    readonly onResize: (columns: number, rows: number) => void;
+}): import("react").ReactNode;

package/dist/src/tui/run-terminal.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "@opentui/react/jsx-runtime";
+import { EmbeddedTerminalRenderable } from "@opentui/core";
+import { extend } from "@opentui/react";
+import { useEffect, useRef } from "react";
+import { TUI_RUN_OUTPUT_BYTE_LIMIT } from "./model.js";
+/** Opacity a finished run's terminal takes, so it reads as spent rather than still live. */
+const FINISHED_RUN_OPACITY = 0.55;
+extend({ embeddedTerminal: EmbeddedTerminalRenderable });
+/**
+ * Render a child's terminal output as the child itself drew it.
+ *
+ * The preamble is written first, so the command sits in the terminal as though it had been typed there
+ * and the child's output follows it. The chunks are then replayed from the first byte on every mount,
+ * because the emulator's screen is derived from the whole sequence: a chunk applied to a fresh screen
+ * lands in the wrong place.
+ *
+ * Focus is what routes the operator's keys here, and it also tells the emulator to encode them for the
+ * keyboard mode the child has asked for, which no caller can know.
+ * @param properties - Command to show before anything runs, byte stream and how many chunks it has
+ * ever held, viewport size, whether the child is still taking input, whether the run is spent, and the
+ * sinks for what the emulator sends back.
+ * @returns - Embedded terminal element sized to the given viewport.
+ */
+export function RunTerminal({ preamble, chunks, received, columns, rows, live, dimmed, onInput, onResize, }) {
+    const terminal = useRef(null);
+    const written = useRef(0);
+    const primed = useRef(false);
+    useEffect(() => {
+        const current = terminal.current;
+        if (!current)
+            return;
+        if (!primed.current) {
+            current.write(preamble);
+            primed.current = true;
+        }
+        // Counted from the newest end, because the oldest chunks are dropped as the buffer fills and an
+        // index from the front would address a different chunk each time that happens.
+        const pending = Math.min(received - written.current, chunks.length);
+        if (pending > 0)
+            for (const chunk of chunks.slice(chunks.length - pending))
+                current.write(chunk);
+        written.current = received;
+    }, [chunks, received, preamble]);
+    useEffect(() => {
+        const current = terminal.current;
+        if (!current)
+            return;
+        if (live)
+            current.focus();
+        else
+            current.blur();
+    }, [live]);
+    return (_jsx("embeddedTerminal", { ref: terminal, cols: columns, rows: rows, width: columns, height: rows, maxScrollback: TUI_RUN_OUTPUT_BYTE_LIMIT, opacity: dimmed ? FINISHED_RUN_OPACITY : 1, onData: onInput, onTerminalResize: onResize }));
+}

package/dist/src/tui/runtime.d.ts

@@ -0,0 +1,113 @@
+/** Signals whose default terminal action is replaced by orderly TUI shutdown. */
+export declare const DEFAULT_TUI_EXIT_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGQUIT", "SIGHUP"];
+/** A signal owned by the TUI runtime boundary. */
+export type TuiExitSignal = (typeof DEFAULT_TUI_EXIT_SIGNALS)[number];
+/** The first event that initiated terminal shutdown. */
+export type TuiExitReason = {
+    /** Identifies an operator-requested orderly exit. */
+    kind: "normal";
+    /** Process status used after renderer finalization. */
+    exitCode: number;
+} | {
+    /** Identifies shutdown requested by an operating-system signal. */
+    kind: "signal";
+    /** Signal delivered to the runtime boundary. */
+    signal: TuiExitSignal;
+    /** Process status used after renderer finalization. */
+    exitCode: number;
+} | {
+    /** Identifies a renderer frame failure. */
+    kind: "renderer-error";
+    /** Error reported by the renderer. */
+    error: unknown;
+    /** Process status used after renderer finalization. */
+    exitCode: number;
+} | {
+    /** Identifies an exception that escaped application code. */
+    kind: "uncaught-exception";
+    /** Uncaught value reported by the runtime. */
+    error: unknown;
+    /** Process status used after renderer finalization. */
+    exitCode: number;
+} | {
+    /** Identifies a rejected promise without a consumer. */
+    kind: "unhandled-rejection";
+    /** Rejection value reported by the runtime. */
+    error: unknown;
+    /** Process status used after renderer finalization. */
+    exitCode: number;
+};
+/** Renderer options controlled by the TUI lifecycle boundary. */
+export type TuiRendererLifecycleOptions = {
+    /** Prevents the renderer from bypassing application-owned Ctrl+C handling. */
+    exitOnCtrlC: false;
+    /** Prevents the renderer from installing its own signal policy. */
+    exitSignals: [];
+    /** Prevents fatal errors from replacing the production screen with a debug overlay. */
+    openConsoleOnError: false;
+    /** Runs only after the renderer has completed native finalization. */
+    onDestroy: () => void;
+};
+/** Minimal renderer surface needed by the lifecycle owner. */
+export interface TuiRendererPort {
+    /** Requests terminal cleanup; completion is reported through the configured callback. */
+    destroy(): void;
+    /** Subscribes to one renderer event. */
+    on(event: "render:error", listener: (event: {
+        error: unknown;
+    }) => void): this;
+    /** Removes one renderer event subscription. */
+    off(event: "render:error", listener: (event: {
+        error: unknown;
+    }) => void): this;
+}
+/** Process lifecycle operations used by the TUI runtime. */
+export interface TuiProcessPort {
+    /** Registers a signal listener and returns its cleanup operation. */
+    onSignal(signal: TuiExitSignal, listener: () => void): () => void;
+    /** Registers an uncaught-exception listener and returns its cleanup operation. */
+    onUncaughtException(listener: (error: unknown) => void): () => void;
+    /** Registers an unhandled-rejection listener and returns its cleanup operation. */
+    onUnhandledRejection(listener: (error: unknown) => void): () => void;
+    /** Resolves the conventional process status for one configured signal. */
+    signalExitCode(signal: TuiExitSignal): number;
+    /** Writes one operator-visible line once the terminal has been restored. */
+    report(line: string): void;
+    /** Terminates the process after renderer finalization. */
+    exit(exitCode: number): void;
+}
+/** Mounted presentation resources released before renderer destruction begins. */
+export interface MountedTuiRoot {
+    /** Releases presentation resources without owning native terminal cleanup. */
+    dispose(): void;
+}
+/** Dependencies supplied to the TUI runtime consumer. */
+export type TuiRuntimeDependencies<Renderer extends TuiRendererPort> = {
+    /** Creates the renderer with lifecycle policy supplied by the consumer. */
+    createRenderer(options: TuiRendererLifecycleOptions): Promise<Renderer>;
+    /** Mounts the presentation tree and optionally returns its cleanup operation. */
+    mount(renderer: Renderer, shutdown: (reason?: TuiExitReason) => void): MountedTuiRoot | undefined;
+    /** Installs renderer event isolation before application subscriptions or presentation mount. */
+    prepareRenderer(renderer: Renderer, reportError: (error: unknown) => void): void;
+    /** Supplies process event and termination operations. */
+    process: TuiProcessPort;
+    /** Signals owned by this runtime instance. */
+    exitSignals: readonly TuiExitSignal[];
+};
+/** A running TUI together with its single shutdown entry point. */
+export interface TuiRuntime<Renderer extends TuiRendererPort> {
+    /** Renderer owned by this runtime instance. */
+    readonly renderer: Renderer;
+    /** First shutdown reason, or undefined while the runtime is active. */
+    readonly exitReason: TuiExitReason | undefined;
+    /** Cleanup failures retained without preventing later cleanup operations. */
+    readonly cleanupErrors: readonly unknown[];
+    /** Requests idempotent renderer shutdown while retaining the first reason. */
+    shutdown(reason?: TuiExitReason): void;
+}
+/**
+ * Start a TUI from explicit renderer, process, and presentation dependencies.
+ * @param dependencies - Collaborators and signal policy owned by the composition root.
+ * @returns Running TUI whose process exit remains gated on renderer finalization.
+ */
+export declare function startTuiRuntime<Renderer extends TuiRendererPort>(dependencies: TuiRuntimeDependencies<Renderer>): Promise<TuiRuntime<Renderer>>;

package/dist/src/tui/runtime.js

@@ -0,0 +1,189 @@
+/** Signals whose default terminal action is replaced by orderly TUI shutdown. */
+export const DEFAULT_TUI_EXIT_SIGNALS = ["SIGINT", "SIGTERM", "SIGQUIT", "SIGHUP"];
+/**
+ * Start a TUI from explicit renderer, process, and presentation dependencies.
+ * @param dependencies - Collaborators and signal policy owned by the composition root.
+ * @returns Running TUI whose process exit remains gated on renderer finalization.
+ */
+export async function startTuiRuntime(dependencies) {
+    const rendererReference = {};
+    let mountedRoot;
+    let exitReason;
+    let creating = true;
+    let mounting = false;
+    let shutdownPending = false;
+    let presentationDisposed = false;
+    let destroyRequested = false;
+    let finalizationObserved = false;
+    let finalizationCompleted = false;
+    let rendererSubscriptionAttempted = false;
+    const removeProcessListeners = [];
+    const cleanupErrors = [];
+    const finalizationWasObserved = () => finalizationObserved;
+    const shutdownWasRequested = () => shutdownPending;
+    const attemptCleanup = (operation) => {
+        try {
+            operation();
+        }
+        catch (error) {
+            cleanupErrors.push(error);
+        }
+    };
+    const removeListeners = () => {
+        if (rendererSubscriptionAttempted) {
+            rendererSubscriptionAttempted = false;
+            attemptCleanup(() => {
+                rendererReference.current?.off("render:error", onRendererError);
+            });
+        }
+        for (const remove of removeProcessListeners.splice(0))
+            attemptCleanup(remove);
+    };
+    const disposePresentation = () => {
+        if (presentationDisposed || !mountedRoot)
+            return;
+        presentationDisposed = true;
+        const root = mountedRoot;
+        attemptCleanup(() => {
+            root.dispose();
+        });
+    };
+    const completeFinalization = () => {
+        finalizationObserved = true;
+        if (creating || mounting || finalizationCompleted)
+            return;
+        finalizationCompleted = true;
+        const retainedReason = exitReason ?? normalExit();
+        exitReason = retainedReason;
+        try {
+            disposePresentation();
+            removeListeners();
+        }
+        finally {
+            attemptCleanup(() => {
+                for (const line of describeAbnormalExit(retainedReason, cleanupErrors))
+                    dependencies.process.report(line);
+            });
+            dependencies.process.exit(retainedReason.exitCode);
+        }
+    };
+    const requestDestroy = () => {
+        if (destroyRequested || finalizationObserved)
+            return;
+        destroyRequested = true;
+        disposePresentation();
+        const renderer = rendererReference.current;
+        if (!renderer)
+            return;
+        attemptCleanup(() => {
+            renderer.destroy();
+        });
+    };
+    const rollbackStartup = () => {
+        removeListeners();
+        requestDestroy();
+    };
+    const shutdown = (reason = normalExit()) => {
+        exitReason ??= reason;
+        shutdownPending = true;
+        if (mounting)
+            return;
+        requestDestroy();
+    };
+    const onRendererError = (event) => {
+        shutdown({ kind: "renderer-error", error: event.error, exitCode: 1 });
+    };
+    let renderer;
+    try {
+        renderer = await dependencies.createRenderer({
+            exitOnCtrlC: false,
+            exitSignals: [],
+            openConsoleOnError: false,
+            onDestroy: completeFinalization,
+        });
+        rendererReference.current = renderer;
+        creating = false;
+    }
+    catch (error) {
+        creating = false;
+        exitReason = { kind: "uncaught-exception", error, exitCode: 1 };
+        shutdownPending = true;
+        if (finalizationWasObserved())
+            completeFinalization();
+        throw error;
+    }
+    if (!finalizationWasObserved()) {
+        try {
+            dependencies.prepareRenderer(renderer, (error) => cleanupErrors.push(error));
+            rendererSubscriptionAttempted = true;
+            renderer.on("render:error", onRendererError);
+            for (const signal of dependencies.exitSignals) {
+                removeProcessListeners.push(dependencies.process.onSignal(signal, () => {
+                    shutdown({ kind: "signal", signal, exitCode: dependencies.process.signalExitCode(signal) });
+                }));
+            }
+            removeProcessListeners.push(dependencies.process.onUncaughtException((error) => {
+                shutdown({ kind: "uncaught-exception", error, exitCode: 1 });
+            }));
+            removeProcessListeners.push(dependencies.process.onUnhandledRejection((error) => {
+                shutdown({ kind: "unhandled-rejection", error, exitCode: 1 });
+            }));
+            mounting = true;
+            mountedRoot = dependencies.mount(renderer, shutdown) ?? undefined;
+            mounting = false;
+        }
+        catch (error) {
+            mounting = false;
+            exitReason ??= { kind: "uncaught-exception", error, exitCode: 1 };
+            shutdownPending = true;
+            rollbackStartup();
+            if (finalizationWasObserved())
+                completeFinalization();
+            throw error;
+        }
+    }
+    if (finalizationWasObserved())
+        completeFinalization();
+    else if (shutdownWasRequested())
+        requestDestroy();
+    return {
+        renderer,
+        get exitReason() {
+            return exitReason;
+        },
+        get cleanupErrors() {
+            return cleanupErrors;
+        },
+        shutdown,
+    };
+}
+function normalExit() {
+    return { kind: "normal", exitCode: 0 };
+}
+/**
+ * Describe an exit that is neither normal nor a signal, so the cause survives the process.
+ * @param reason - Retained first shutdown reason.
+ * @param cleanupErrors - Failures collected while releasing runtime resources; reported only alongside a described exit.
+ * @returns Lines to write after terminal restoration; empty for a normal exit or a signal.
+ */
+function describeAbnormalExit(reason, cleanupErrors) {
+    if (reason.kind === "normal" || reason.kind === "signal")
+        return [];
+    return [
+        `pager tui exited: ${reason.kind}`,
+        describeThrown(reason.error),
+        ...cleanupErrors.map((error) => `cleanup failed: ${describeThrown(error)}`),
+    ];
+}
+function describeThrown(value) {
+    if (value instanceof Error)
+        return value.stack ?? `${value.name}: ${value.message}`;
+    if (typeof value !== "object" || value === null)
+        return String(value);
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "[unserializable value]";
+    }
+}