midline-agent 0.2.0 → 0.3.0

package/README.md

@@ -246,6 +246,7 @@ MidlineAgent.init({
   },
   redactFields?: string[],        // added to the built-in list (maskFields still works)
   redactHeaders?: string[],
+  captureConsole?: boolean,       // MIDLINE_CAPTURE_CONSOLE — also send what the process prints (off by default)
 
   // Delivery
   flushIntervalMs?: number,       // default 1500
@@ -266,6 +267,7 @@ MidlineAgent.init({
 ```env
 MIDLINE_API_KEY=...
 MIDLINE_ENDPOINT=https://api.usemidline.com
+# MIDLINE_CAPTURE_CONSOLE=true
 
 # proxy mode
 TARGET_API_URL=http://localhost:4000
@@ -278,6 +280,32 @@ TARGET_API_URL=http://localhost:4000
 
 ---
 
+## Console output
+
+Set `captureConsole: true` (or `MIDLINE_CAPTURE_CONSOLE=true`) and whatever the process prints
+shows up on the dashboard's Logs page as `console` events, one per line, next to your requests. That
+covers `console.log`, Nest's logger, pino, winston: anything written to stdout or stderr.
+
+```ts
+MidlineAgent.init({ apiKey: process.env.MIDLINE_API_KEY, captureConsole: true });
+const app = await NestFactory.create(AppModule); // startup lines are captured from here on
+```
+
+- Initialise the agent before creating the app. Anything printed before `init()` isn't captured.
+- Your terminal output doesn't change. The agent reads each write after it has happened.
+- Colour codes are stripped, each line is capped at 4096 characters, and lines are redacted like any
+  other text.
+- Severity comes from the line: `ERROR` or `FATAL` is high, `WARN` is medium, other stderr output is
+  medium, and everything else is low.
+- Up to 100 lines a second are sent, with room for a 1,000-line burst such as Nest mapping its routes
+  at startup. Lines past that still print but aren't sent.
+- Printed lines don't count towards request totals, error rates or latency.
+- It needs a Midline server that knows the `console` event type. An older server refuses the first
+  line; the agent then turns console capture off, says so once, and keeps sending requests and errors.
+- The agent's own diagnostics are never captured.
+
+---
+
 ## Sensitive data
 
 Redaction happens **in your process, before an event is queued**. What's masked never reaches a
@@ -293,7 +321,7 @@ defence.
   `privatekey`, `authorization`, `cookie`, `session`, `credential`, `csrf`, `xsrf`, `signature`,
   `creditcard`, `cardnumber`, `cvv`, `cvc`, `ssn`, `socialsecurity`; and the exact keys `auth`,
   `pwd`, `pin`, `otp`, `sid`, `jwt`, `bearer`.
-- **Values inside any text** — error messages, stack traces, routes: bearer/basic credentials,
+- **Values inside any text** — error messages, stack traces, routes, console lines: bearer/basic credentials,
   JWTs, Midline keys (`ak_…`), Stripe and AWS key formats, PEM private keys, `user:pass@` in URLs,
   and `key=value` / `"key": value` pairs whose key is sensitive.
 - Query strings are never part of `route`.

package/dist/agent.d.ts

@@ -34,7 +34,7 @@ export interface ExchangeMessage {
     truncated?: boolean;
 }
 /**
- * Ships request/error events to the Midline server.
+ * Ships request, error and console events to the Midline server.
  *
  * The contract with the host application is that the agent is never allowed to
  * affect it: an unreachable, untrusted, slow or misconfigured Midline server costs a
@@ -65,6 +65,11 @@ export declare class MidlineAgent {
     private dropped;
     private maxRequestBytes;
     private batchLimit;
+    private consoleCapture;
+    private consoleTokens;
+    private consoleRefilledAt;
+    /** The server refused a console event: it predates them, so no more are sent. */
+    private consoleUnsupported;
     constructor(config?: MidlineConfig);
     /** False when the agent is off: no key, bad config, disabled, rejected key, or closed. */
     get active(): boolean;
@@ -73,6 +78,8 @@ export declare class MidlineAgent {
     addEvent(event: MidlineEvent): void;
     /** Records one HTTP exchange. Captured parts are redacted here, before queueing. */
     recordHttp(exchange: HttpExchange): void;
+    private recordConsole;
+    private takeConsoleToken;
     /** Sends whatever is buffered now, ignoring backoff, and keeps the process alive until done. */
     flush(): Promise<void>;
     /** Flushes with a deadline, then closes. For graceful shutdown. */
@@ -98,6 +105,12 @@ export declare class MidlineAgent {
     /** Returns false if delivery should stop for this drain. */
     private sendIndividually;
     private send;
+    /**
+     * True when a rejected event is a console line the server has no event type for,
+     * i.e. the server predates console capture. Capture switches itself off rather
+     * than paying a refused request for every line printed from then on.
+     */
+    private refusedConsole;
     /** One line per distinct fault, not one per failed event. */
     private report;
     private describe;

package/dist/agent.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MidlineAgent = exports.SDK_VERSION = void 0;
 const config_1 = require("./config");
+const console_1 = require("./console");
 const redact_1 = require("./redact");
 const transport_1 = require("./transport");
 exports.SDK_VERSION = (() => {
@@ -15,6 +16,10 @@ exports.SDK_VERSION = (() => {
 const MAX_REQUEST_BYTES = 512 * 1024;
 const MIN_REQUEST_BYTES = 16 * 1024;
 const MAX_QUEUE_BYTES = 16 * 1024 * 1024;
+/** Console lines: a startup burst (Nest mapping every route) fits, a log storm can't crowd out requests. */
+const CONSOLE_BURST_LINES = 1000;
+const CONSOLE_LINES_PER_SECOND = 100;
+const CONSOLE_SEVERITY = { info: "low", warn: "medium", error: "high" };
 /** Verification failures. Retrying is still right: they clear once the server is fixed. */
 const TLS_ERROR_REASONS = {
     DEPTH_ZERO_SELF_SIGNED_CERT: "presented a self-signed certificate",
@@ -31,7 +36,7 @@ const TLS_ERROR_REASONS = {
     HOSTNAME_MISMATCH: "presented a certificate issued for a different hostname",
 };
 /**
- * Ships request/error events to the Midline server.
+ * Ships request, error and console events to the Midline server.
  *
  * The contract with the host application is that the agent is never allowed to
  * affect it: an unreachable, untrusted, slow or misconfigured Midline server costs a
@@ -71,6 +76,11 @@ class MidlineAgent {
         this.dropped = 0;
         this.maxRequestBytes = MAX_REQUEST_BYTES;
         this.batchLimit = Number.MAX_SAFE_INTEGER;
+        this.consoleCapture = null;
+        this.consoleTokens = CONSOLE_BURST_LINES;
+        this.consoleRefilledAt = Date.now();
+        /** The server refused a console event: it predates them, so no more are sent. */
+        this.consoleUnsupported = false;
         this.onErrorHook = config.onError;
         this.debugLogs = config.debug ?? (0, config_1.envFlag)("MIDLINE_DEBUG") ?? false;
         this.redactor = new redact_1.Redactor([...(config.redactFields ?? []), ...(config.maskFields ?? [])], config.redactHeaders);
@@ -101,10 +111,15 @@ class MidlineAgent {
             userAgent: `midline-agent/${exports.SDK_VERSION} node/${process.version}`,
         });
         this.timer = setInterval(() => {
+            this.consoleCapture?.flushPending();
             void this.drain(false);
         }, resolved.flushIntervalMs);
         // Telemetry must never be the reason a process refuses to exit.
         this.timer.unref?.();
+        if (resolved.captureConsole) {
+            this.consoleCapture = new console_1.ConsoleCapture((line) => this.recordConsole(line));
+            this.consoleCapture.install();
+        }
     }
     /** False when the agent is off: no key, bad config, disabled, rejected key, or closed. */
     get active() {
@@ -165,10 +180,43 @@ class MidlineAgent {
             this.report("event-build", `midline: could not record a request (${err?.message}); skipped it.`);
         }
     }
+    recordConsole(line) {
+        if (!this.active || this.consoleUnsupported)
+            return;
+        if (!this.takeConsoleToken()) {
+            this.dropped += 1;
+            this.report("console-rate", `midline: console output is arriving faster than ${CONSOLE_LINES_PER_SECOND} lines/s; the extra lines still print but are not sent.`);
+            return;
+        }
+        try {
+            this.enqueue(this.toWire({
+                type: "console",
+                path: line.stream,
+                message: line.text,
+                timestamp: line.timestamp,
+                severity: CONSOLE_SEVERITY[line.level],
+                category: "application",
+                integration: "console",
+            }, false));
+        }
+        catch (err) {
+            this.report("event-build", `midline: could not record a console line (${err?.message}); skipped it.`);
+        }
+    }
+    takeConsoleToken() {
+        const now = Date.now();
+        this.consoleTokens = Math.min(CONSOLE_BURST_LINES, this.consoleTokens + ((now - this.consoleRefilledAt) / 1000) * CONSOLE_LINES_PER_SECOND);
+        this.consoleRefilledAt = now;
+        if (this.consoleTokens < 1)
+            return false;
+        this.consoleTokens -= 1;
+        return true;
+    }
     /** Sends whatever is buffered now, ignoring backoff, and keeps the process alive until done. */
     async flush() {
         if (!this.active)
             return;
+        this.consoleCapture?.flushPending(true);
         this.retryAfter = 0;
         if (this.drainPromise) {
             await this.drainPromise;
@@ -197,6 +245,8 @@ class MidlineAgent {
             clearInterval(this.timer);
             this.timer = null;
         }
+        this.consoleCapture?.uninstall();
+        this.consoleCapture = null;
         this.queue = [];
         this.queueBytes = 0;
         this.transport?.destroy();
@@ -241,13 +291,17 @@ class MidlineAgent {
     toWire(event, preRedacted) {
         const config = this.config;
         const type = event.type;
+        const isConsole = type === "console";
         const statusCode = Number.isInteger(event.statusCode) && event.statusCode >= 100 && event.statusCode <= 599
             ? event.statusCode
             : type === "error" ? 500 : undefined;
         const { severity, category } = classify(event, statusCode);
         const route = this.redactor.string(stripQuery(event.path) || "/", 2048);
         const payload = {};
-        if (type === "error" || event.message) {
+        if (isConsole) {
+            payload.message = this.redactor.string(event.message ?? "", console_1.MAX_LINE_CHARS);
+        }
+        else if (type === "error" || event.message) {
             payload.error = event.message ? this.redactor.string(event.message, 1024) : type === "error" ? "Unknown error" : undefined;
         }
         if (event.stack)
@@ -290,9 +344,10 @@ class MidlineAgent {
             apiKey: config.apiKey,
             eventType: type,
             route,
-            method: (event.method || "GET").toUpperCase().slice(0, 16),
+            // A printed line has no method or timing; defaults here would make it look like a request.
+            method: isConsole ? undefined : (event.method || "GET").toUpperCase().slice(0, 16),
             statusCode,
-            responseTime: Math.min(Math.max(0, Math.round(Number(event.duration) || 0)), 86400000),
+            responseTime: isConsole ? undefined : Math.min(Math.max(0, Math.round(Number(event.duration) || 0)), 86400000),
             timestamp: validTimestamp(event.timestamp),
             // Clamped to the server's validation limits: one over-long field would
             // otherwise get every event rejected.
@@ -405,6 +460,8 @@ class MidlineAgent {
             }
             if (outcome.kind === "rejected") {
                 if (batch.length === 1) {
+                    if (this.refusedConsole(batch[0], outcome.detail))
+                        continue;
                     this.dropped += 1;
                     this.report(`rejected:${outcome.detail}`, `midline: the Midline server rejected an event (${outcome.detail}); dropped it.`);
                     continue;
@@ -424,13 +481,17 @@ class MidlineAgent {
     /** Returns false if delivery should stop for this drain. */
     async sendIndividually(batch, keepProcessAlive) {
         for (let index = 0; index < batch.length; index++) {
+            if (this.consoleUnsupported && batch[index].wire.eventType === "console")
+                continue;
             const outcome = await this.send([batch[index]], keepProcessAlive);
             if (outcome.kind === "ok") {
                 this.onSuccess();
             }
             else if (outcome.kind === "rejected" || outcome.kind === "tooLarge") {
-                this.dropped += 1;
                 const detail = outcome.kind === "rejected" ? outcome.detail : "HTTP 413";
+                if (outcome.kind === "rejected" && this.refusedConsole(batch[index], detail))
+                    continue;
+                this.dropped += 1;
                 this.report(`rejected:${detail}`, `midline: the Midline server rejected an event (${detail}); dropped it.`);
             }
             else if (outcome.kind === "stop") {
@@ -493,6 +554,24 @@ class MidlineAgent {
         }
         return { kind: "rejected", detail: `HTTP ${status}${serverMessage(result.body)}` };
     }
+    /**
+     * True when a rejected event is a console line the server has no event type for,
+     * i.e. the server predates console capture. Capture switches itself off rather
+     * than paying a refused request for every line printed from then on.
+     */
+    refusedConsole(item, detail) {
+        if (item.wire.eventType !== "console" || !detail.includes("eventType"))
+            return false;
+        if (!this.consoleUnsupported) {
+            this.consoleUnsupported = true;
+            this.consoleCapture?.uninstall();
+            this.consoleCapture = null;
+            this.queue = this.queue.filter((queued) => queued.wire.eventType !== "console");
+            this.queueBytes = this.queue.reduce((sum, queued) => sum + queued.bytes, 0);
+            this.log("warn", "midline: this Midline server does not accept console events yet (it needs updating), so console capture is off. Request and error monitoring carry on.");
+        }
+        return true;
+    }
     /** One line per distinct fault, not one per failed event. */
     report(signature, message) {
         if (this.lastNotice === signature && !this.debugLogs) {
@@ -558,22 +637,26 @@ class MidlineAgent {
         this.close();
     }
     log(level, message) {
-        if (this.onErrorHook) {
-            try {
-                this.onErrorHook(message);
-            }
-            catch {
-                // A broken logging hook must not become the host application's problem.
+        // The agent's own diagnostics are never the application's console output,
+        // including when a hook hands them to a logger that prints them.
+        (0, console_1.withoutConsoleCapture)(() => {
+            if (this.onErrorHook) {
+                try {
+                    this.onErrorHook(message);
+                }
+                catch {
+                    // A broken logging hook must not become the host application's problem.
+                }
+                if (!this.debugLogs)
+                    return;
             }
-            if (!this.debugLogs)
-                return;
-        }
-        if (level === "error")
-            console.error(message);
-        else if (level === "warn")
-            console.warn(message);
-        else
-            console.info(message);
+            if (level === "error")
+                console.error(message);
+            else if (level === "warn")
+                console.warn(message);
+            else
+                console.info(message);
+        });
     }
 }
 exports.MidlineAgent = MidlineAgent;
@@ -595,6 +678,9 @@ function classify(event, statusCode) {
     else if (event.type === "custom") {
         category = "business";
     }
+    else if (event.type === "console") {
+        category = "application";
+    }
     else if (statusCode && statusCode >= 500) {
         severity = "high";
         category = "application";

package/dist/config.d.ts

@@ -27,6 +27,7 @@ export interface ResolvedConfig {
     redactFields: string[];
     redactHeaders: string[];
     capture: ResolvedCapture;
+    captureConsole: boolean;
     onError?: (message: string) => void;
     debug: boolean;
     flushIntervalMs: number;

package/dist/config.js

@@ -216,6 +216,7 @@ function resolveConfig(config) {
         redactFields: [...(config.redactFields ?? []), ...(config.maskFields ?? [])],
         redactHeaders: config.redactHeaders ?? [],
         capture: resolveCapture(config.capture),
+        captureConsole: config.captureConsole ?? envFlag("MIDLINE_CAPTURE_CONSOLE") ?? false,
         onError: config.onError,
         debug: config.debug ?? envFlag("MIDLINE_DEBUG") ?? false,
         flushIntervalMs: positiveInt(config.flushIntervalMs, 1500, 50, 60000),

package/dist/console.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Console capture: what the host process prints — `console.log`, Nest's logger,
+ * pino, anything that reaches stdout or stderr — copied into Midline line by line.
+ *
+ * The streams are never changed. The original `write` runs first with the
+ * caller's own arguments and its return value is handed straight back, so
+ * back-pressure, callbacks and the terminal output are exactly what they were.
+ */
+export type ConsoleStream = "stdout" | "stderr";
+export type ConsoleLevel = "info" | "warn" | "error";
+export interface ConsoleLine {
+    stream: ConsoleStream;
+    text: string;
+    level: ConsoleLevel;
+    /** When the line's first chunk was written, not when it was sent. */
+    timestamp: string;
+}
+/** Longest line kept. A log line past this is almost always a dumped payload. */
+export declare const MAX_LINE_CHARS = 4096;
+/**
+ * Runs `fn` with capture paused. The agent writes its own diagnostics through
+ * this, so a warning about delivery can't become an event that needs delivering.
+ */
+export declare function withoutConsoleCapture<T>(fn: () => T): T;
+export declare class ConsoleCapture {
+    private readonly onLine;
+    private readonly originals;
+    private readonly wrappers;
+    private readonly pending;
+    private busy;
+    private stopped;
+    constructor(onLine: (line: ConsoleLine) => void);
+    install(): void;
+    /** Restores the streams. A wrapper installed on top of ours is left alone — ours just goes quiet underneath it. */
+    uninstall(): void;
+    /**
+     * Emits lines still waiting for a newline. Without `force`, only the ones that
+     * were already unfinished at the previous call, so a line being written in
+     * pieces isn't cut in half by a timer tick.
+     */
+    flushPending(force?: boolean): void;
+    private take;
+    private emit;
+}
+/** Nest, most JSON loggers and console.warn/error leave enough behind to tell a failure from chatter. */
+export declare function levelOf(stream: ConsoleStream, text: string): ConsoleLevel;

package/dist/console.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Console capture: what the host process prints — `console.log`, Nest's logger,
+ * pino, anything that reaches stdout or stderr — copied into Midline line by line.
+ *
+ * The streams are never changed. The original `write` runs first with the
+ * caller's own arguments and its return value is handed straight back, so
+ * back-pressure, callbacks and the terminal output are exactly what they were.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleCapture = exports.MAX_LINE_CHARS = void 0;
+exports.withoutConsoleCapture = withoutConsoleCapture;
+exports.levelOf = levelOf;
+/** Longest line kept. A log line past this is almost always a dumped payload. */
+exports.MAX_LINE_CHARS = 4096;
+const STREAMS = ["stdout", "stderr"];
+/** CSI (colours, cursor moves), OSC (titles, hyperlinks) and the remaining two-byte escapes. */
+const ANSI_ESCAPE = /\x1B\[[0-?]*[ -\/]*[@-~]|\x1B\][^\x07\x1B]*(?:\x07|\x1B\\)|\x1B[@-Z\\-_]/g;
+// Level words are matched in capitals only: lower-case "error" turns up in plenty of harmless lines.
+const ERROR_MARKERS = [/\b(?:ERROR|FATAL|CRITICAL)\b/, /"level"\s*:\s*"?(?:error|fatal|critical|50|60)\b/i];
+const WARN_MARKERS = [/\bWARN(?:ING)?\b/, /"level"\s*:\s*"?(?:warn|warning|40)\b/i];
+let suppressed = 0;
+/**
+ * Runs `fn` with capture paused. The agent writes its own diagnostics through
+ * this, so a warning about delivery can't become an event that needs delivering.
+ */
+function withoutConsoleCapture(fn) {
+    suppressed += 1;
+    try {
+        return fn();
+    }
+    finally {
+        suppressed -= 1;
+    }
+}
+class ConsoleCapture {
+    constructor(onLine) {
+        this.onLine = onLine;
+        this.originals = new Map();
+        this.wrappers = new Map();
+        this.pending = {
+            stdout: { text: "", at: "", stale: false },
+            stderr: { text: "", at: "", stale: false },
+        };
+        this.busy = false;
+        this.stopped = false;
+    }
+    install() {
+        for (const stream of STREAMS) {
+            const target = process[stream];
+            const original = target.write;
+            const capture = this;
+            const wrapper = function (...args) {
+                const result = original.apply(this, args);
+                capture.take(stream, args[0], args[1]);
+                return result;
+            };
+            this.originals.set(stream, original);
+            this.wrappers.set(stream, wrapper);
+            target.write = wrapper;
+        }
+    }
+    /** Restores the streams. A wrapper installed on top of ours is left alone — ours just goes quiet underneath it. */
+    uninstall() {
+        this.stopped = true;
+        for (const stream of STREAMS) {
+            const wrapper = this.wrappers.get(stream);
+            if (wrapper && process[stream].write === wrapper) {
+                process[stream].write = this.originals.get(stream);
+            }
+        }
+        this.wrappers.clear();
+        this.originals.clear();
+    }
+    /**
+     * Emits lines still waiting for a newline. Without `force`, only the ones that
+     * were already unfinished at the previous call, so a line being written in
+     * pieces isn't cut in half by a timer tick.
+     */
+    flushPending(force = false) {
+        if (this.stopped || this.busy)
+            return;
+        this.busy = true;
+        try {
+            for (const stream of STREAMS) {
+                const pending = this.pending[stream];
+                if (!pending.text)
+                    continue;
+                if (force || pending.stale) {
+                    this.pending[stream] = { text: "", at: "", stale: false };
+                    this.emit(stream, pending.text, pending.at);
+                }
+                else {
+                    pending.stale = true;
+                }
+            }
+        }
+        catch {
+            // Best-effort, like the rest of capture.
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    take(stream, chunk, encoding) {
+        // `busy` also stops a loop if whatever handles a line prints something itself.
+        if (this.stopped || this.busy || suppressed > 0)
+            return;
+        this.busy = true;
+        try {
+            const text = decode(chunk, encoding);
+            if (!text)
+                return;
+            const now = new Date().toISOString();
+            const pending = this.pending[stream];
+            const lines = (pending.text + text).split("\n");
+            let rest = lines.pop() ?? "";
+            let at = pending.text ? pending.at : now;
+            for (const line of lines) {
+                this.emit(stream, line, at);
+                at = now;
+            }
+            if (rest.length > exports.MAX_LINE_CHARS) {
+                this.emit(stream, rest, at);
+                rest = "";
+            }
+            this.pending[stream] = { text: rest, at: rest ? at : "", stale: false };
+        }
+        catch {
+            // The write itself already happened; a line we couldn't read is just not sent.
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    emit(stream, raw, at) {
+        let text = raw.replace(ANSI_ESCAPE, "").replace(/\r$/, "");
+        // A carriage return redraws the line; what's left after the last one is what the terminal shows.
+        text = text.slice(text.lastIndexOf("\r") + 1);
+        if (!text.trim())
+            return;
+        if (text.length > exports.MAX_LINE_CHARS)
+            text = text.slice(0, exports.MAX_LINE_CHARS);
+        this.onLine({ stream, text, level: levelOf(stream, text), timestamp: at });
+    }
+}
+exports.ConsoleCapture = ConsoleCapture;
+/** Nest, most JSON loggers and console.warn/error leave enough behind to tell a failure from chatter. */
+function levelOf(stream, text) {
+    const head = text.slice(0, 256);
+    if (ERROR_MARKERS.some((pattern) => pattern.test(head)))
+        return "error";
+    if (WARN_MARKERS.some((pattern) => pattern.test(head)))
+        return "warn";
+    return stream === "stderr" ? "warn" : "info";
+}
+function decode(chunk, encoding) {
+    if (typeof chunk === "string") {
+        return typeof encoding === "string" && !/^utf-?8$/i.test(encoding) && Buffer.isEncoding(encoding)
+            ? Buffer.from(chunk, encoding).toString("utf8")
+            : chunk;
+    }
+    if (chunk instanceof Uint8Array) {
+        return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength).toString("utf8");
+    }
+    return "";
+}

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /** A PEM string, PEM bytes, a path to a PEM file, or several of those. */
 export type CaInput = string | Buffer | Array<string | Buffer>;
-export type EventType = "request" | "error" | "security" | "performance" | "custom";
+export type EventType = "request" | "error" | "security" | "performance" | "custom" | "console";
 export type EventSeverity = "low" | "medium" | "high" | "critical";
 export type EventCategory = "application" | "infrastructure" | "security" | "performance" | "business";
 /**
@@ -55,6 +55,13 @@ export interface MidlineConfig {
     redactHeaders?: string[];
     /** What to capture beyond method/path/status/timing. Defaults to nothing. */
     capture?: CaptureOptions;
+    /**
+     * Also send what the process prints — `console.log`, Nest's logger, anything
+     * written to stdout or stderr — as `console` events, one per line, redacted like
+     * any other text. Initialise the agent before creating the app to include its
+     * startup lines. Off by default. Env fallback: `MIDLINE_CAPTURE_CONSOLE`.
+     */
+    captureConsole?: boolean;
     /** Set to false to keep the agent inert. Env fallback: `MIDLINE_ENABLED`. */
     enabled?: boolean;
     /**
@@ -128,5 +135,5 @@ export interface MidlineEvent {
     errorCode?: string;
     /** Set when the client disconnected before the response finished. */
     aborted?: boolean;
-    integration?: "express" | "node-http" | "proxy" | "manual";
+    integration?: "express" | "node-http" | "proxy" | "console" | "manual";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midline-agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Midline — request & error monitoring with security detection",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/agent.ts

@@ -1,4 +1,5 @@
 import { ConfigError, ResolvedCapture, ResolvedConfig, envFlag, resolveConfig } from "./config";
+import { ConsoleCapture, ConsoleLevel, ConsoleLine, MAX_LINE_CHARS, withoutConsoleCapture } from "./console";
 import type { RequestContext } from "./context";
 import { Redactor } from "./redact";
 import { Transport } from "./transport";
@@ -16,6 +17,11 @@ const MAX_REQUEST_BYTES = 512 * 1024;
 const MIN_REQUEST_BYTES = 16 * 1024;
 const MAX_QUEUE_BYTES = 16 * 1024 * 1024;
 
+/** Console lines: a startup burst (Nest mapping every route) fits, a log storm can't crowd out requests. */
+const CONSOLE_BURST_LINES = 1000;
+const CONSOLE_LINES_PER_SECOND = 100;
+const CONSOLE_SEVERITY: Record<ConsoleLevel, EventSeverity> = { info: "low", warn: "medium", error: "high" };
+
 /** Verification failures. Retrying is still right: they clear once the server is fixed. */
 const TLS_ERROR_REASONS: Record<string, string> = {
   DEPTH_ZERO_SELF_SIGNED_CERT: "presented a self-signed certificate",
@@ -76,7 +82,7 @@ export interface ExchangeMessage {
 }
 
 /**
- * Ships request/error events to the Midline server.
+ * Ships request, error and console events to the Midline server.
  *
  * The contract with the host application is that the agent is never allowed to
  * affect it: an unreachable, untrusted, slow or misconfigured Midline server costs a
@@ -126,6 +132,11 @@ export class MidlineAgent {
   private dropped = 0;
   private maxRequestBytes = MAX_REQUEST_BYTES;
   private batchLimit = Number.MAX_SAFE_INTEGER;
+  private consoleCapture: ConsoleCapture | null = null;
+  private consoleTokens = CONSOLE_BURST_LINES;
+  private consoleRefilledAt = Date.now();
+  /** The server refused a console event: it predates them, so no more are sent. */
+  private consoleUnsupported = false;
 
   constructor(config: MidlineConfig = {}) {
     this.onErrorHook = config.onError;
@@ -162,10 +173,16 @@ export class MidlineAgent {
     });
 
     this.timer = setInterval(() => {
+      this.consoleCapture?.flushPending();
       void this.drain(false);
     }, resolved.flushIntervalMs);
     // Telemetry must never be the reason a process refuses to exit.
     this.timer.unref?.();
+
+    if (resolved.captureConsole) {
+      this.consoleCapture = new ConsoleCapture((line) => this.recordConsole(line));
+      this.consoleCapture.install();
+    }
   }
 
   /** False when the agent is off: no key, bad config, disabled, rejected key, or closed. */
@@ -229,9 +246,52 @@ export class MidlineAgent {
     }
   }
 
+  private recordConsole(line: ConsoleLine): void {
+    if (!this.active || this.consoleUnsupported) return;
+    if (!this.takeConsoleToken()) {
+      this.dropped += 1;
+      this.report(
+        "console-rate",
+        `midline: console output is arriving faster than ${CONSOLE_LINES_PER_SECOND} lines/s; the extra lines still print but are not sent.`,
+      );
+      return;
+    }
+    try {
+      this.enqueue(
+        this.toWire(
+          {
+            type: "console",
+            path: line.stream,
+            message: line.text,
+            timestamp: line.timestamp,
+            severity: CONSOLE_SEVERITY[line.level],
+            category: "application",
+            integration: "console",
+          },
+          false,
+        ),
+      );
+    } catch (err) {
+      this.report("event-build", `midline: could not record a console line (${(err as Error)?.message}); skipped it.`);
+    }
+  }
+
+  private takeConsoleToken(): boolean {
+    const now = Date.now();
+    this.consoleTokens = Math.min(
+      CONSOLE_BURST_LINES,
+      this.consoleTokens + ((now - this.consoleRefilledAt) / 1000) * CONSOLE_LINES_PER_SECOND,
+    );
+    this.consoleRefilledAt = now;
+    if (this.consoleTokens < 1) return false;
+    this.consoleTokens -= 1;
+    return true;
+  }
+
   /** Sends whatever is buffered now, ignoring backoff, and keeps the process alive until done. */
   async flush(): Promise<void> {
     if (!this.active) return;
+    this.consoleCapture?.flushPending(true);
     this.retryAfter = 0;
     if (this.drainPromise) {
       await this.drainPromise;
@@ -261,6 +321,8 @@ export class MidlineAgent {
       clearInterval(this.timer);
       this.timer = null;
     }
+    this.consoleCapture?.uninstall();
+    this.consoleCapture = null;
     this.queue = [];
     this.queueBytes = 0;
     this.transport?.destroy();
@@ -306,6 +368,7 @@ export class MidlineAgent {
   private toWire(event: MidlineEvent, preRedacted: boolean): Record<string, unknown> {
     const config = this.config!;
     const type = event.type;
+    const isConsole = type === "console";
     const statusCode = Number.isInteger(event.statusCode) && event.statusCode! >= 100 && event.statusCode! <= 599
       ? event.statusCode
       : type === "error" ? 500 : undefined;
@@ -313,7 +376,9 @@ export class MidlineAgent {
     const route = this.redactor.string(stripQuery(event.path) || "/", 2048);
 
     const payload: Record<string, unknown> = {};
-    if (type === "error" || event.message) {
+    if (isConsole) {
+      payload.message = this.redactor.string(event.message ?? "", MAX_LINE_CHARS);
+    } else if (type === "error" || event.message) {
       payload.error = event.message ? this.redactor.string(event.message, 1024) : type === "error" ? "Unknown error" : undefined;
     }
     if (event.stack) payload.stack = this.redactor.string(event.stack, 16 * 1024);
@@ -349,9 +414,10 @@ export class MidlineAgent {
       apiKey: config.apiKey,
       eventType: type,
       route,
-      method: (event.method || "GET").toUpperCase().slice(0, 16),
+      // A printed line has no method or timing; defaults here would make it look like a request.
+      method: isConsole ? undefined : (event.method || "GET").toUpperCase().slice(0, 16),
       statusCode,
-      responseTime: Math.min(Math.max(0, Math.round(Number(event.duration) || 0)), 86_400_000),
+      responseTime: isConsole ? undefined : Math.min(Math.max(0, Math.round(Number(event.duration) || 0)), 86_400_000),
       timestamp: validTimestamp(event.timestamp),
       // Clamped to the server's validation limits: one over-long field would
       // otherwise get every event rejected.
@@ -470,6 +536,7 @@ export class MidlineAgent {
       }
       if (outcome.kind === "rejected") {
         if (batch.length === 1) {
+          if (this.refusedConsole(batch[0], outcome.detail)) continue;
           this.dropped += 1;
           this.report(`rejected:${outcome.detail}`, `midline: the Midline server rejected an event (${outcome.detail}); dropped it.`);
           continue;
@@ -490,12 +557,14 @@ export class MidlineAgent {
   /** Returns false if delivery should stop for this drain. */
   private async sendIndividually(batch: QueuedEvent[], keepProcessAlive: boolean): Promise<boolean> {
     for (let index = 0; index < batch.length; index++) {
+      if (this.consoleUnsupported && batch[index].wire.eventType === "console") continue;
       const outcome = await this.send([batch[index]], keepProcessAlive);
       if (outcome.kind === "ok") {
         this.onSuccess();
       } else if (outcome.kind === "rejected" || outcome.kind === "tooLarge") {
-        this.dropped += 1;
         const detail = outcome.kind === "rejected" ? outcome.detail : "HTTP 413";
+        if (outcome.kind === "rejected" && this.refusedConsole(batch[index], detail)) continue;
+        this.dropped += 1;
         this.report(`rejected:${detail}`, `midline: the Midline server rejected an event (${detail}); dropped it.`);
       } else if (outcome.kind === "stop") {
         this.disable();
@@ -565,6 +634,27 @@ export class MidlineAgent {
     return { kind: "rejected", detail: `HTTP ${status}${serverMessage(result.body)}` };
   }
 
+  /**
+   * True when a rejected event is a console line the server has no event type for,
+   * i.e. the server predates console capture. Capture switches itself off rather
+   * than paying a refused request for every line printed from then on.
+   */
+  private refusedConsole(item: QueuedEvent, detail: string): boolean {
+    if (item.wire.eventType !== "console" || !detail.includes("eventType")) return false;
+    if (!this.consoleUnsupported) {
+      this.consoleUnsupported = true;
+      this.consoleCapture?.uninstall();
+      this.consoleCapture = null;
+      this.queue = this.queue.filter((queued) => queued.wire.eventType !== "console");
+      this.queueBytes = this.queue.reduce((sum, queued) => sum + queued.bytes, 0);
+      this.log(
+        "warn",
+        "midline: this Midline server does not accept console events yet (it needs updating), so console capture is off. Request and error monitoring carry on.",
+      );
+    }
+    return true;
+  }
+
   /** One line per distinct fault, not one per failed event. */
   private report(signature: string, message: string): void {
     if (this.lastNotice === signature && !this.debugLogs) {
@@ -638,17 +728,21 @@ export class MidlineAgent {
   }
 
   private log(level: "info" | "warn" | "error", message: string): void {
-    if (this.onErrorHook) {
-      try {
-        this.onErrorHook(message);
-      } catch {
-        // A broken logging hook must not become the host application's problem.
+    // The agent's own diagnostics are never the application's console output,
+    // including when a hook hands them to a logger that prints them.
+    withoutConsoleCapture(() => {
+      if (this.onErrorHook) {
+        try {
+          this.onErrorHook(message);
+        } catch {
+          // A broken logging hook must not become the host application's problem.
+        }
+        if (!this.debugLogs) return;
       }
-      if (!this.debugLogs) return;
-    }
-    if (level === "error") console.error(message);
-    else if (level === "warn") console.warn(message);
-    else console.info(message);
+      if (level === "error") console.error(message);
+      else if (level === "warn") console.warn(message);
+      else console.info(message);
+    });
   }
 }
 
@@ -667,6 +761,8 @@ function classify(event: MidlineEvent, statusCode: number | undefined): { severi
     category = "security";
   } else if (event.type === "custom") {
     category = "business";
+  } else if (event.type === "console") {
+    category = "application";
   } else if (statusCode && statusCode >= 500) {
     severity = "high";
     category = "application";

package/src/config.ts

@@ -37,6 +37,7 @@ export interface ResolvedConfig {
   redactFields: string[];
   redactHeaders: string[];
   capture: ResolvedCapture;
+  captureConsole: boolean;
   onError?: (message: string) => void;
   debug: boolean;
   flushIntervalMs: number;
@@ -218,6 +219,7 @@ export function resolveConfig(config: MidlineConfig): ResolvedConfig {
     redactFields: [...(config.redactFields ?? []), ...(config.maskFields ?? [])],
     redactHeaders: config.redactHeaders ?? [],
     capture: resolveCapture(config.capture),
+    captureConsole: config.captureConsole ?? envFlag("MIDLINE_CAPTURE_CONSOLE") ?? false,
     onError: config.onError,
     debug: config.debug ?? envFlag("MIDLINE_DEBUG") ?? false,
     flushIntervalMs: positiveInt(config.flushIntervalMs, 1500, 50, 60_000),

package/src/console.ts

@@ -0,0 +1,182 @@
+/**
+ * Console capture: what the host process prints — `console.log`, Nest's logger,
+ * pino, anything that reaches stdout or stderr — copied into Midline line by line.
+ *
+ * The streams are never changed. The original `write` runs first with the
+ * caller's own arguments and its return value is handed straight back, so
+ * back-pressure, callbacks and the terminal output are exactly what they were.
+ */
+
+export type ConsoleStream = "stdout" | "stderr";
+export type ConsoleLevel = "info" | "warn" | "error";
+
+export interface ConsoleLine {
+  stream: ConsoleStream;
+  text: string;
+  level: ConsoleLevel;
+  /** When the line's first chunk was written, not when it was sent. */
+  timestamp: string;
+}
+
+/** Longest line kept. A log line past this is almost always a dumped payload. */
+export const MAX_LINE_CHARS = 4096;
+
+const STREAMS: ConsoleStream[] = ["stdout", "stderr"];
+
+/** CSI (colours, cursor moves), OSC (titles, hyperlinks) and the remaining two-byte escapes. */
+const ANSI_ESCAPE = /\x1B\[[0-?]*[ -\/]*[@-~]|\x1B\][^\x07\x1B]*(?:\x07|\x1B\\)|\x1B[@-Z\\-_]/g;
+
+// Level words are matched in capitals only: lower-case "error" turns up in plenty of harmless lines.
+const ERROR_MARKERS = [/\b(?:ERROR|FATAL|CRITICAL)\b/, /"level"\s*:\s*"?(?:error|fatal|critical|50|60)\b/i];
+const WARN_MARKERS = [/\bWARN(?:ING)?\b/, /"level"\s*:\s*"?(?:warn|warning|40)\b/i];
+
+type WriteFn = (...args: any[]) => boolean;
+
+let suppressed = 0;
+
+/**
+ * Runs `fn` with capture paused. The agent writes its own diagnostics through
+ * this, so a warning about delivery can't become an event that needs delivering.
+ */
+export function withoutConsoleCapture<T>(fn: () => T): T {
+  suppressed += 1;
+  try {
+    return fn();
+  } finally {
+    suppressed -= 1;
+  }
+}
+
+interface Pending {
+  text: string;
+  at: string;
+  /** Already unfinished at the previous flush. */
+  stale: boolean;
+}
+
+export class ConsoleCapture {
+  private readonly originals = new Map<ConsoleStream, WriteFn>();
+  private readonly wrappers = new Map<ConsoleStream, WriteFn>();
+  private readonly pending: Record<ConsoleStream, Pending> = {
+    stdout: { text: "", at: "", stale: false },
+    stderr: { text: "", at: "", stale: false },
+  };
+  private busy = false;
+  private stopped = false;
+
+  constructor(private readonly onLine: (line: ConsoleLine) => void) {}
+
+  install(): void {
+    for (const stream of STREAMS) {
+      const target = process[stream];
+      const original = target.write as WriteFn;
+      const capture = this;
+      const wrapper: WriteFn = function (this: unknown, ...args: any[]) {
+        const result = original.apply(this, args);
+        capture.take(stream, args[0], args[1]);
+        return result;
+      };
+      this.originals.set(stream, original);
+      this.wrappers.set(stream, wrapper);
+      target.write = wrapper as NodeJS.WriteStream["write"];
+    }
+  }
+
+  /** Restores the streams. A wrapper installed on top of ours is left alone — ours just goes quiet underneath it. */
+  uninstall(): void {
+    this.stopped = true;
+    for (const stream of STREAMS) {
+      const wrapper = this.wrappers.get(stream);
+      if (wrapper && process[stream].write === wrapper) {
+        process[stream].write = this.originals.get(stream) as NodeJS.WriteStream["write"];
+      }
+    }
+    this.wrappers.clear();
+    this.originals.clear();
+  }
+
+  /**
+   * Emits lines still waiting for a newline. Without `force`, only the ones that
+   * were already unfinished at the previous call, so a line being written in
+   * pieces isn't cut in half by a timer tick.
+   */
+  flushPending(force = false): void {
+    if (this.stopped || this.busy) return;
+    this.busy = true;
+    try {
+      for (const stream of STREAMS) {
+        const pending = this.pending[stream];
+        if (!pending.text) continue;
+        if (force || pending.stale) {
+          this.pending[stream] = { text: "", at: "", stale: false };
+          this.emit(stream, pending.text, pending.at);
+        } else {
+          pending.stale = true;
+        }
+      }
+    } catch {
+      // Best-effort, like the rest of capture.
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  private take(stream: ConsoleStream, chunk: unknown, encoding: unknown): void {
+    // `busy` also stops a loop if whatever handles a line prints something itself.
+    if (this.stopped || this.busy || suppressed > 0) return;
+    this.busy = true;
+    try {
+      const text = decode(chunk, encoding);
+      if (!text) return;
+
+      const now = new Date().toISOString();
+      const pending = this.pending[stream];
+      const lines = (pending.text + text).split("\n");
+      let rest = lines.pop() ?? "";
+      let at = pending.text ? pending.at : now;
+
+      for (const line of lines) {
+        this.emit(stream, line, at);
+        at = now;
+      }
+      if (rest.length > MAX_LINE_CHARS) {
+        this.emit(stream, rest, at);
+        rest = "";
+      }
+      this.pending[stream] = { text: rest, at: rest ? at : "", stale: false };
+    } catch {
+      // The write itself already happened; a line we couldn't read is just not sent.
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  private emit(stream: ConsoleStream, raw: string, at: string): void {
+    let text = raw.replace(ANSI_ESCAPE, "").replace(/\r$/, "");
+    // A carriage return redraws the line; what's left after the last one is what the terminal shows.
+    text = text.slice(text.lastIndexOf("\r") + 1);
+    if (!text.trim()) return;
+    if (text.length > MAX_LINE_CHARS) text = text.slice(0, MAX_LINE_CHARS);
+    this.onLine({ stream, text, level: levelOf(stream, text), timestamp: at });
+  }
+}
+
+/** Nest, most JSON loggers and console.warn/error leave enough behind to tell a failure from chatter. */
+export function levelOf(stream: ConsoleStream, text: string): ConsoleLevel {
+  const head = text.slice(0, 256);
+  if (ERROR_MARKERS.some((pattern) => pattern.test(head))) return "error";
+  if (WARN_MARKERS.some((pattern) => pattern.test(head))) return "warn";
+  return stream === "stderr" ? "warn" : "info";
+}
+
+function decode(chunk: unknown, encoding: unknown): string {
+  if (typeof chunk === "string") {
+    return typeof encoding === "string" && !/^utf-?8$/i.test(encoding) && Buffer.isEncoding(encoding)
+      ? Buffer.from(chunk, encoding).toString("utf8")
+      : chunk;
+  }
+  if (chunk instanceof Uint8Array) {
+    return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength).toString("utf8");
+  }
+  return "";
+}

package/src/types.ts

@@ -1,7 +1,7 @@
 /** A PEM string, PEM bytes, a path to a PEM file, or several of those. */
 export type CaInput = string | Buffer | Array<string | Buffer>;
 
-export type EventType = "request" | "error" | "security" | "performance" | "custom";
+export type EventType = "request" | "error" | "security" | "performance" | "custom" | "console";
 export type EventSeverity = "low" | "medium" | "high" | "critical";
 export type EventCategory = "application" | "infrastructure" | "security" | "performance" | "business";
 
@@ -62,6 +62,13 @@ export interface MidlineConfig {
   redactHeaders?: string[];
   /** What to capture beyond method/path/status/timing. Defaults to nothing. */
   capture?: CaptureOptions;
+  /**
+   * Also send what the process prints — `console.log`, Nest's logger, anything
+   * written to stdout or stderr — as `console` events, one per line, redacted like
+   * any other text. Initialise the agent before creating the app to include its
+   * startup lines. Off by default. Env fallback: `MIDLINE_CAPTURE_CONSOLE`.
+   */
+  captureConsole?: boolean;
 
   /** Set to false to keep the agent inert. Env fallback: `MIDLINE_ENABLED`. */
   enabled?: boolean;
@@ -141,5 +148,5 @@ export interface MidlineEvent {
   errorCode?: string;
   /** Set when the client disconnected before the response finished. */
   aborted?: boolean;
-  integration?: "express" | "node-http" | "proxy" | "manual";
+  integration?: "express" | "node-http" | "proxy" | "console" | "manual";
 }

package/test/console.test.js

@@ -0,0 +1,182 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { MidlineAgent } = require("../dist");
+const { startCollector, diagnostics } = require("./helpers");
+
+function agentFor(endpoint, extra = {}) {
+  return new MidlineAgent({
+    apiKey: "ak_test_key",
+    serviceName: "console-test",
+    endpoint,
+    flushIntervalMs: 60_000,
+    timeoutMs: 2000,
+    connectTimeoutMs: 1000,
+    captureConsole: true,
+    ...extra,
+  });
+}
+
+/**
+ * Records every chunk that reaches the streams, then passes it on. Installed before
+ * the agent, so it sits underneath the agent's wrapper where the terminal would be.
+ */
+function recordStreams() {
+  const originals = { stdout: process.stdout.write, stderr: process.stderr.write };
+  const written = { stdout: [], stderr: [] };
+  const recorders = {};
+  for (const name of ["stdout", "stderr"]) {
+    recorders[name] = function (chunk, ...rest) {
+      written[name].push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+      return originals[name].call(this, chunk, ...rest);
+    };
+    process[name].write = recorders[name];
+  }
+  return {
+    written,
+    recorders,
+    restore: () => {
+      process.stdout.write = originals.stdout;
+      process.stderr.write = originals.stderr;
+    },
+  };
+}
+
+const consoleEvents = (collector) => collector.events().filter((event) => event.eventType === "console");
+
+test("console capture: printed lines become console events and the output itself is untouched", async () => {
+  const streams = recordStreams();
+  const collector = await startCollector();
+  const agent = agentFor(collector.url);
+  try {
+    const coloured = "\x1b[32m[Nest] 4242  - LOG [NestApplication] Nest application successfully started\x1b[39m\n";
+    process.stdout.write(coloured);
+    console.log("hello world");
+    process.stdout.write("written in ");
+    process.stdout.write("two pieces\n");
+    process.stderr.write("[Nest] 4242  - ERROR [ExceptionHandler] database unreachable\n");
+    console.log("connecting with password=hunter2");
+    process.stdout.write("\n   \n");
+    await agent.flush();
+
+    const events = consoleEvents(collector);
+    const byMessage = new Map(events.map((event) => [event.payload.message, event]));
+
+    const started = byMessage.get("[Nest] 4242  - LOG [NestApplication] Nest application successfully started");
+    assert.ok(started, "colour codes are stripped");
+    assert.equal(started.route, "stdout");
+    assert.equal(started.severity, "low");
+    assert.equal(started.method, undefined, "a printed line is not dressed up as a request");
+    assert.equal(started.statusCode, undefined);
+    assert.equal(started.responseTime, undefined);
+    assert.equal(started.metadata.integrationType, "console");
+
+    assert.ok(byMessage.has("hello world"));
+    assert.ok(byMessage.has("written in two pieces"), "a line written in chunks is one event");
+
+    const failure = byMessage.get("[Nest] 4242  - ERROR [ExceptionHandler] database unreachable");
+    assert.ok(failure);
+    assert.equal(failure.route, "stderr");
+    assert.equal(failure.severity, "high");
+
+    assert.ok(byMessage.has("connecting with password=[REDACTED]"));
+    assert.ok(!events.some((event) => event.payload.message.includes("hunter2")));
+    assert.ok(!events.some((event) => !event.payload.message.trim()), "blank lines are skipped");
+
+    assert.ok(streams.written.stdout.includes(coloured), "the terminal still gets the original bytes");
+    assert.ok(streams.written.stdout.includes("connecting with password=hunter2\n"), "redaction applies to what's sent, not what's printed");
+  } finally {
+    agent.close();
+    streams.restore();
+    await collector.close();
+  }
+});
+
+test("console capture: the agent's own warnings are not captured, and close() puts the streams back", async () => {
+  const streams = recordStreams();
+  const collector = await startCollector({ respond: () => ({ status: 503, body: { message: "down" } }) });
+  // No onError: the agent's diagnostics go to the console, where capture could see them.
+  const agent = agentFor(collector.url);
+  try {
+    assert.notEqual(process.stdout.write, streams.recorders.stdout, "capture wraps stdout");
+    console.log("before the outage");
+    await agent.flush();
+    assert.ok(streams.written.stderr.some((chunk) => chunk.includes("midline:")), "the warning was printed");
+
+    collector.setResponder((req) => ({ status: 201, body: { success: req.body.events.length, failed: 0 } }));
+    await agent.flush();
+    const messages = consoleEvents(collector).map((event) => event.payload.message);
+    assert.ok(messages.includes("before the outage"));
+    assert.ok(!messages.some((message) => message.includes("midline:")), "diagnostics never become events");
+
+    agent.close();
+    assert.equal(process.stdout.write, streams.recorders.stdout);
+    assert.equal(process.stderr.write, streams.recorders.stderr);
+  } finally {
+    agent.close();
+    streams.restore();
+    await collector.close();
+  }
+});
+
+test("console capture: a server without console events turns capture off and requests keep flowing", async () => {
+  const streams = recordStreams();
+  const collector = await startCollector({
+    respond: (req) => {
+      const events = req.body.events;
+      if (events.some((event) => event.eventType === "console")) {
+        return {
+          status: 400,
+          body: { message: ["events.1.eventType must be one of the following values: request, error, security, performance, custom"] },
+        };
+      }
+      return { status: 201, body: { success: events.length, failed: 0 } };
+    },
+  });
+  const { messages, onError } = diagnostics();
+  const agent = agentFor(collector.url, { onError });
+  try {
+    agent.addEvent({ type: "request", path: "/orders" });
+    console.log("server started");
+    console.log("second line");
+    await agent.flush();
+
+    const accepted = collector.requests
+      .filter((request) => !request.body.events.some((event) => event.eventType === "console"))
+      .flatMap((request) => request.body.events.map((event) => event.route));
+    assert.deepEqual(accepted, ["/orders"]);
+    assert.equal(agent.queued, 0);
+    assert.equal(agent.active, true, "only console capture stops");
+    assert.match(messages.join("\n"), /console capture is off/);
+    assert.equal(process.stdout.write, streams.recorders.stdout, "the stream wrapper is gone");
+
+    const refused = collector.requests.filter((request) => request.body.events.some((event) => event.eventType === "console"));
+    assert.equal(refused.length, 2, "the batch, then one console line on its own; the rest are not sent");
+  } finally {
+    agent.close();
+    streams.restore();
+    await collector.close();
+  }
+});
+
+test("console capture is off unless asked for, and MIDLINE_CAPTURE_CONSOLE turns it on", () => {
+  const before = process.stdout.write;
+  const settings = { apiKey: "ak_test_key", endpoint: "http://127.0.0.1:9", flushIntervalMs: 60_000 };
+
+  const off = new MidlineAgent(settings);
+  assert.equal(process.stdout.write, before);
+  off.close();
+
+  const previous = process.env.MIDLINE_CAPTURE_CONSOLE;
+  process.env.MIDLINE_CAPTURE_CONSOLE = "true";
+  const on = new MidlineAgent(settings);
+  try {
+    assert.notEqual(process.stdout.write, before);
+  } finally {
+    on.close();
+    if (previous === undefined) delete process.env.MIDLINE_CAPTURE_CONSOLE;
+    else process.env.MIDLINE_CAPTURE_CONSOLE = previous;
+  }
+  assert.equal(process.stdout.write, before);
+});