@downtrace/agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raúl Jiménez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @downtrace/agent
+
+**A flight recorder for your Node.js backend.** Downtrace watches how your application normally behaves and, when something gets slower or breaks, tells you what changed. This is the agent: it observes incoming HTTP requests, aggregates them locally per route and 10-second interval, and ships compact batches to the Downtrace cloud — never in your request path, never able to throw into your code, with bounded memory.
+
+v0 observes incoming HTTP only. Outgoing calls, database queries and the black box come next.
+
+## Install
+
+```sh
+npm install @downtrace/agent
+```
+
+```sh
+DOWNTRACE_TOKEN=dt_… DOWNTRACE_URL=https://your-downtrace-cloud \
+  node --import @downtrace/agent/register server.js
+# or, without touching the start command:
+NODE_OPTIONS="--import @downtrace/agent/register" node server.js
+```
+
+| Variable | Required | What it is |
+|---|---|---|
+| `DOWNTRACE_TOKEN` | yes | The project's ingest token |
+| `DOWNTRACE_URL` | yes | Base URL of the cloud (`https://…`) |
+| `DOWNTRACE_ENV` | no | Environment; falls back to `NODE_ENV`, then `production` |
+| `DOWNTRACE_VERSION` | no | Deployed version or commit; detected from `APP_VERSION`, `GIT_SHA`, `VERCEL_GIT_COMMIT_SHA`, `HEROKU_SLUG_COMMIT`, `SOURCE_VERSION`, `RENDER_GIT_COMMIT`, `RAILWAY_GIT_COMMIT_SHA`; else `unknown` |
+| `DOWNTRACE_DEBUG` | no | `1` to log the agent's own activity to stderr |
+| `DOWNTRACE_INTERVAL_MS` | no | Aggregation interval (min 1000; default 10000) |
+
+Without `DOWNTRACE_TOKEN` and `DOWNTRACE_URL` the agent prints one warning and does nothing else.
+
+## What leaves your server
+
+Only structural metadata: method, **route template** (`/products/:id`, never the actual URL), status, counts and a fixed-bucket latency histogram per route and interval, plus the process identity (random id, hostname, pid) and the deploy (version, environment). No bodies, no headers, no query strings. The exact contract is the JSON Schema in [`@downtrace/protocol`](https://www.npmjs.com/package/@downtrace/protocol).
+
+## Guarantees
+
+- Observation through Node's `diagnostics_channel`; nothing in your application is monkey-patched.
+- Sending is asynchronous with `fetch`, off the request path; a bounded queue of 6 intervals — if the cloud is unreachable, the oldest is dropped.
+- Every hook is guarded; after 10 internal errors the agent disables itself and says so once.
+- At most 500 distinct routes per interval; the rest fold into `(other)`.
+- Measured overhead budget, enforced in CI: < 1 ms added at p99, < 3 percentage points of CPU, < 64 MiB.
+
+## Requirements
+
+Node.js 20 or newer (see `engines`). Express route templates are used when present; without a framework, identifier-looking path segments (numbers, UUIDs, long hex) are collapsed into `:id`.
+
+## Source
+
+This package is developed in a monorepo and mirrored read-only to [RadW2020/downtrace-agent](https://github.com/RadW2020/downtrace-agent). Issues are welcome there. MIT.

package/dist/config-nKU1VRvi.js

@@ -0,0 +1,458 @@
+import { randomUUID } from "node:crypto";
+import diagnostics_channel from "node:diagnostics_channel";
+import { hostname } from "node:os";
+import { AGGREGATES_PATH, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, latencyBucket } from "@downtrace/protocol";
+//#region src/routes.ts
+const METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+]);
+const MAX_ROUTE_LENGTH = 256;
+/** Route used when the per-interval cardinality cap is hit. */
+const OTHER_ROUTE = "(other)";
+function normalizeMethod(method) {
+	const m = (method ?? "").toUpperCase();
+	return METHODS.has(m) ? m : "OTHER";
+}
+/**
+* Route template for a request. Prefers the framework's own template
+* (`/products/:id` from Express); otherwise collapses identifier-looking path
+* segments (numbers, UUIDs, long hex) into `:id`.
+*/
+function routeOf(req) {
+	const route = expressTemplate(req) ?? heuristicTemplate(req.url ?? "/");
+	return route.length > MAX_ROUTE_LENGTH ? route.slice(0, MAX_ROUTE_LENGTH) : route;
+}
+function expressTemplate(req) {
+	const path = req.route?.path;
+	if (typeof path !== "string") return void 0;
+	const joined = `${typeof req.baseUrl === "string" ? req.baseUrl : ""}${path}`.replace(/\/{2,}/g, "/");
+	return joined === "" ? "/" : trimSlash(joined);
+}
+const NUMERIC = /^\d+$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX_ID = /^(?:[0-9a-f]{24}|[0-9a-f]{32,})$/i;
+function heuristicTemplate(url) {
+	return trimSlash((url.split(/[?#]/, 1)[0] ?? "/").split("/").map((s) => s !== "" && (NUMERIC.test(s) || UUID.test(s) || HEX_ID.test(s)) ? ":id" : s).join("/") || "/");
+}
+function trimSlash(path) {
+	return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+}
+//#endregion
+//#region src/aggregator.ts
+const DEFAULT_MAX_ROUTES = 500;
+/**
+* Aggregates finished requests for the current interval. Memory is bounded:
+* at most `maxRoutes` distinct routes per interval, the rest fold into (other).
+*/
+var IntervalAggregator = class {
+	endpoints = /* @__PURE__ */ new Map();
+	distinctRoutes = 0;
+	start;
+	maxRoutes;
+	now;
+	constructor(maxRoutes = 500, now = Date.now) {
+		this.maxRoutes = maxRoutes;
+		this.now = now;
+		this.start = now();
+	}
+	get size() {
+		return this.endpoints.size;
+	}
+	record(method, route, status, ms) {
+		let key = `${method} ${route}`;
+		let acc = this.endpoints.get(key);
+		if (!acc) {
+			if (route !== "(other)" && this.distinctRoutes >= this.maxRoutes) {
+				route = OTHER_ROUTE;
+				key = `${method} ${OTHER_ROUTE}`;
+				acc = this.endpoints.get(key);
+			} else if (route !== "(other)") this.distinctRoutes += 1;
+			if (!acc) {
+				acc = {
+					method,
+					route,
+					count: 0,
+					errors: 0,
+					success: 0,
+					redirect: 0,
+					clientError: 0,
+					serverError: 0,
+					counts: new Uint32Array(LATENCY_BUCKETS_V0),
+					sum: 0,
+					max: 0
+				};
+				this.endpoints.set(key, acc);
+			}
+		}
+		acc.count += 1;
+		if (status >= 500) {
+			acc.serverError += 1;
+			acc.errors += 1;
+		} else if (status >= 400) acc.clientError += 1;
+		else if (status >= 300) acc.redirect += 1;
+		else acc.success += 1;
+		const latency = ms >= 0 ? ms : 0;
+		const bucket = latencyBucket(latency);
+		acc.counts[bucket] = (acc.counts[bucket] ?? 0) + 1;
+		acc.sum += latency;
+		if (latency > acc.max) acc.max = latency;
+	}
+	/** Closes the current interval and starts a new one. Returns null when nothing was recorded. */
+	rotate() {
+		const now = this.now();
+		const start = this.start;
+		const endpoints = this.endpoints;
+		this.endpoints = /* @__PURE__ */ new Map();
+		this.distinctRoutes = 0;
+		this.start = now;
+		if (endpoints.size === 0) return null;
+		const out = [];
+		for (const acc of endpoints.values()) out.push({
+			method: acc.method,
+			route: acc.route,
+			count: acc.count,
+			errors: acc.errors,
+			status: {
+				success: acc.success,
+				redirect: acc.redirect,
+				clientError: acc.clientError,
+				serverError: acc.serverError
+			},
+			latency: {
+				counts: Array.from(acc.counts),
+				sum: round3(acc.sum),
+				max: round3(acc.max)
+			}
+		});
+		return {
+			start: Math.floor(start),
+			durationMs: Math.max(1, Math.round(now - start)),
+			endpoints: out
+		};
+	}
+};
+function round3(n) {
+	return Math.round(n * 1e3) / 1e3;
+}
+//#endregion
+//#region src/log.ts
+const PREFIX = "[downtrace]";
+/** Minimal stderr logger. `debug` lines only appear with DOWNTRACE_DEBUG. */
+function createLogger(debug, write = defaultWrite) {
+	return {
+		warn: (message) => write(`${PREFIX} ${message}`),
+		debug: (message) => {
+			if (debug) write(`${PREFIX} ${message}`);
+		}
+	};
+}
+function defaultWrite(line) {
+	process.stderr.write(`${line}\n`);
+}
+//#endregion
+//#region src/transport.ts
+const DEFAULT_MAX_QUEUED = 6;
+const DEFAULT_TIMEOUT_MS = 5e3;
+/**
+* Ships intervals to the cloud in batches. Never blocks, never grows without
+* bound: failed batches stay queued (up to maxQueued) and ride the next flush.
+*/
+var Sender = class {
+	queue = [];
+	inflight = false;
+	warnedAuth = false;
+	sent = 0;
+	failed = 0;
+	dropped = 0;
+	opts;
+	maxQueued;
+	timeoutMs;
+	fetchImpl;
+	constructor(opts) {
+		this.opts = opts;
+		this.maxQueued = opts.maxQueued ?? 6;
+		this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.fetchImpl = opts.fetchImpl ?? fetch;
+	}
+	get pending() {
+		return this.queue.length;
+	}
+	enqueue(interval) {
+		this.queue.push(interval);
+		while (this.queue.length > this.maxQueued) {
+			this.queue.shift();
+			this.dropped += 1;
+		}
+	}
+	/** Sends everything queued in one batch. Resolves true when the cloud accepted it. */
+	async flush(timeoutMs = this.timeoutMs) {
+		if (this.inflight || this.queue.length === 0) return false;
+		this.inflight = true;
+		const intervals = this.queue.slice(0, this.maxQueued);
+		const batch = {
+			protocol: PROTOCOL_VERSION,
+			agent: this.opts.agent,
+			instance: this.opts.instance,
+			deploy: this.opts.deploy,
+			intervals
+		};
+		try {
+			const res = await this.fetchImpl(`${this.opts.url}${AGGREGATES_PATH}`, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					authorization: `Bearer ${this.opts.token}`
+				},
+				body: JSON.stringify(batch),
+				signal: AbortSignal.timeout(timeoutMs)
+			});
+			if (res.ok) {
+				this.queue = this.queue.filter((iv) => !intervals.includes(iv));
+				this.sent += 1;
+				this.opts.log.debug(`sent ${intervals.length} interval(s)`);
+				return true;
+			}
+			this.failed += 1;
+			if (res.status === 401 && !this.warnedAuth) {
+				this.warnedAuth = true;
+				this.opts.log.warn("the cloud rejected DOWNTRACE_TOKEN (401); aggregates will be dropped until it is fixed");
+			} else this.opts.log.debug(`cloud responded ${res.status}; keeping ${this.queue.length} interval(s) queued`);
+			return false;
+		} catch (err) {
+			this.failed += 1;
+			this.opts.log.debug(`send failed: ${err instanceof Error ? err.message : String(err)}`);
+			return false;
+		} finally {
+			this.inflight = false;
+		}
+	}
+};
+//#endregion
+//#region src/version.ts
+/** Version of this agent build, from package.json. */
+const AGENT_VERSION = "0.1.0";
+//#endregion
+//#region src/agent.ts
+const REQUEST_START = "http.server.request.start";
+const RESPONSE_FINISH = "http.server.response.finish";
+const MAX_INTERNAL_ERRORS = 10;
+const SHUTDOWN_FLUSH_MS = 1e3;
+const SIGNALS = ["SIGTERM", "SIGINT"];
+/**
+* The Downtrace Node agent, v0: observes finished HTTP requests through
+* diagnostics_channel, aggregates them per route and interval, and ships
+* batches asynchronously. Nothing here runs synchronously against the cloud,
+* nothing here can throw into the application, and memory is bounded.
+*/
+var Agent = class {
+	config;
+	instance;
+	log;
+	recorder;
+	sender;
+	handleSignals;
+	starts = /* @__PURE__ */ new WeakMap();
+	timer;
+	started = false;
+	recorded = 0;
+	internalErrors = 0;
+	disabled = false;
+	onStart = (message) => this.guard(() => this.requestStarted(message));
+	onFinish = (message) => this.guard(() => this.responseFinished(message));
+	onSignal;
+	onBeforeExit = () => {
+		this.flushNow(SHUTDOWN_FLUSH_MS);
+	};
+	constructor(config, deps = {}) {
+		this.config = config;
+		this.log = deps.log ?? createLogger(config.debug);
+		this.instance = {
+			id: randomUUID(),
+			hostname: hostname() || "unknown",
+			pid: process.pid
+		};
+		const agent = {
+			name: "@downtrace/agent",
+			version: AGENT_VERSION,
+			runtime: "node",
+			runtimeVersion: process.version
+		};
+		const deploy = {
+			version: config.version,
+			environment: config.environment
+		};
+		this.recorder = deps.recorder ?? new IntervalAggregator();
+		this.sender = deps.sender ?? new Sender({
+			url: config.url,
+			token: config.token,
+			agent,
+			instance: this.instance,
+			deploy,
+			log: this.log,
+			fetchImpl: deps.fetchImpl
+		});
+		this.handleSignals = deps.handleSignals ?? false;
+		this.onSignal = {
+			SIGTERM: () => this.signalled("SIGTERM"),
+			SIGINT: () => this.signalled("SIGINT")
+		};
+	}
+	get stats() {
+		return {
+			recorded: this.recorded,
+			internalErrors: this.internalErrors,
+			disabled: this.disabled,
+			sent: this.sender.sent,
+			failed: this.sender.failed,
+			dropped: this.sender.dropped,
+			pending: this.sender.pending
+		};
+	}
+	start() {
+		if (this.started || this.disabled) return;
+		this.started = true;
+		diagnostics_channel.subscribe(REQUEST_START, this.onStart);
+		diagnostics_channel.subscribe(RESPONSE_FINISH, this.onFinish);
+		this.timer = setInterval(() => void this.flushNow(), this.config.intervalMs);
+		this.timer.unref();
+		process.once("beforeExit", this.onBeforeExit);
+		if (this.handleSignals) for (const s of SIGNALS) process.on(s, this.onSignal[s]);
+		this.log.debug(`started: ${this.config.url} · ${this.config.environment} · ${this.config.version} · every ${this.config.intervalMs} ms`);
+	}
+	/** Unsubscribes and stops timers; attempts a last flush. Idempotent. */
+	async stop() {
+		if (!this.started) return;
+		this.started = false;
+		diagnostics_channel.unsubscribe(REQUEST_START, this.onStart);
+		diagnostics_channel.unsubscribe(RESPONSE_FINISH, this.onFinish);
+		if (this.timer) clearInterval(this.timer);
+		process.removeListener("beforeExit", this.onBeforeExit);
+		for (const s of SIGNALS) process.removeListener(s, this.onSignal[s]);
+		await this.flushNow(SHUTDOWN_FLUSH_MS);
+	}
+	/** Closes the current interval and sends everything queued. */
+	async flushNow(timeoutMs) {
+		try {
+			const interval = this.recorder.rotate();
+			if (interval) this.sender.enqueue(interval);
+			return await this.sender.flush(timeoutMs);
+		} catch (err) {
+			this.internalError(err);
+			return false;
+		}
+	}
+	requestStarted(message) {
+		const request = message.request;
+		if (request) this.starts.set(request, performance.now());
+	}
+	responseFinished(message) {
+		const { request, response } = message;
+		if (!request) return;
+		const startedAt = this.starts.get(request);
+		this.starts.delete(request);
+		const ms = startedAt === void 0 ? 0 : performance.now() - startedAt;
+		this.recorder.record(normalizeMethod(request.method), routeOf(request), response?.statusCode ?? 0, ms);
+		this.recorded += 1;
+	}
+	/** Every hook runs through here: an agent bug must never reach the application. */
+	guard(fn) {
+		try {
+			fn();
+		} catch (err) {
+			this.internalError(err);
+		}
+	}
+	internalError(err) {
+		this.internalErrors += 1;
+		this.log.debug(`internal error: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+		if (this.internalErrors >= MAX_INTERNAL_ERRORS && !this.disabled) {
+			this.disabled = true;
+			this.log.warn(`agent disabled after ${this.internalErrors} internal errors; your application is unaffected`);
+			this.stop();
+		}
+	}
+	/**
+	* If we are the only listener, flush briefly and then let the default signal
+	* behaviour happen exactly as if the agent were not installed. If the app has
+	* its own handlers, flush in the background and stay out of the way.
+	*/
+	signalled(signal) {
+		const onlyUs = process.listenerCount(signal) === 1;
+		const flush = this.flushNow(SHUTDOWN_FLUSH_MS);
+		if (!onlyUs) return;
+		const resume = () => {
+			process.removeListener(signal, this.onSignal[signal]);
+			process.kill(process.pid, signal);
+		};
+		flush.then(resume, resume);
+	}
+};
+function createAgent(config, deps = {}) {
+	return new Agent(config, deps);
+}
+//#endregion
+//#region src/config.ts
+const DEFAULT_INTERVAL_MS = 1e4;
+const MIN_INTERVAL_MS = 1e3;
+/** Env vars commonly set by deploy platforms, in order of preference, used when DOWNTRACE_VERSION is absent. */
+const VERSION_ENV_VARS = [
+	"DOWNTRACE_VERSION",
+	"APP_VERSION",
+	"GIT_SHA",
+	"VERCEL_GIT_COMMIT_SHA",
+	"HEROKU_SLUG_COMMIT",
+	"SOURCE_VERSION",
+	"RENDER_GIT_COMMIT",
+	"RAILWAY_GIT_COMMIT_SHA"
+];
+function configFromEnv(env = process.env) {
+	const token = env.DOWNTRACE_TOKEN?.trim() ?? "";
+	const rawUrl = env.DOWNTRACE_URL?.trim() ?? "";
+	if (token === "" && rawUrl === "") return {
+		ok: false,
+		reason: "DOWNTRACE_TOKEN and DOWNTRACE_URL are not set"
+	};
+	if (token === "") return {
+		ok: false,
+		reason: "DOWNTRACE_TOKEN is not set"
+	};
+	if (rawUrl === "") return {
+		ok: false,
+		reason: "DOWNTRACE_URL is not set"
+	};
+	if (!/^https?:\/\//.test(rawUrl)) return {
+		ok: false,
+		reason: "DOWNTRACE_URL must start with http:// or https://"
+	};
+	const interval = Number(env.DOWNTRACE_INTERVAL_MS);
+	return {
+		ok: true,
+		config: {
+			token,
+			url: rawUrl.replace(/\/+$/, ""),
+			environment: clamp(env.DOWNTRACE_ENV ?? env.NODE_ENV ?? "production", 64),
+			version: detectVersion(env),
+			debug: env.DOWNTRACE_DEBUG === "1" || env.DOWNTRACE_DEBUG === "true",
+			intervalMs: Number.isInteger(interval) && interval >= MIN_INTERVAL_MS ? interval : DEFAULT_INTERVAL_MS
+		}
+	};
+}
+function detectVersion(env) {
+	for (const name of VERSION_ENV_VARS) {
+		const v = env[name]?.trim();
+		if (v) return clamp(v, 128);
+	}
+	return "unknown";
+}
+function clamp(value, max) {
+	const v = value.trim();
+	return v.length > max ? v.slice(0, max) : v || "unknown";
+}
+//#endregion
+export { createAgent as a, Sender as c, IntervalAggregator as d, OTHER_ROUTE as f, routeOf as h, Agent as i, createLogger as l, normalizeMethod as m, configFromEnv as n, AGENT_VERSION as o, heuristicTemplate as p, detectVersion as r, DEFAULT_MAX_QUEUED as s, DEFAULT_INTERVAL_MS as t, DEFAULT_MAX_ROUTES as u };

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+import { AgentInfo, DeployInfo, Endpoint, InstanceInfo, Interval } from "@downtrace/protocol";
+//#region src/routes.d.ts
+type Method = Endpoint["method"];
+/** Route used when the per-interval cardinality cap is hit. */
+declare const OTHER_ROUTE = "(other)";
+declare function normalizeMethod(method: string | undefined): Method;
+/** What we read off a request: Express sets `route`/`baseUrl`; plain Node gives us `url`. */
+interface RouteSource {
+  url?: string | undefined;
+  route?: unknown;
+  baseUrl?: unknown;
+}
+/**
+ * Route template for a request. Prefers the framework's own template
+ * (`/products/:id` from Express); otherwise collapses identifier-looking path
+ * segments (numbers, UUIDs, long hex) into `:id`.
+ */
+declare function routeOf(req: RouteSource): string;
+declare function heuristicTemplate(url: string): string;
+//#endregion
+//#region src/aggregator.d.ts
+interface Recorder {
+  record(method: Method, route: string, status: number, ms: number): void;
+  rotate(): Interval | null;
+}
+declare const DEFAULT_MAX_ROUTES = 500;
+/**
+ * Aggregates finished requests for the current interval. Memory is bounded:
+ * at most `maxRoutes` distinct routes per interval, the rest fold into (other).
+ */
+declare class IntervalAggregator implements Recorder {
+  private endpoints;
+  private distinctRoutes;
+  private start;
+  private readonly maxRoutes;
+  private readonly now;
+  constructor(maxRoutes?: number, now?: () => number);
+  get size(): number;
+  record(method: Method, route: string, status: number, ms: number): void;
+  /** Closes the current interval and starts a new one. Returns null when nothing was recorded. */
+  rotate(): Interval | null;
+}
+//#endregion
+//#region src/config.d.ts
+interface AgentConfig {
+  token: string;
+  /** Ingest base URL, without trailing slash. */
+  url: string;
+  environment: string;
+  version: string;
+  debug: boolean;
+  /** Aggregation interval; 10 s in production. */
+  intervalMs: number;
+}
+type ConfigResult = {
+  ok: true;
+  config: AgentConfig;
+} | {
+  ok: false;
+  reason: string;
+};
+declare const DEFAULT_INTERVAL_MS = 10000;
+declare function configFromEnv(env?: NodeJS.ProcessEnv): ConfigResult;
+declare function detectVersion(env: NodeJS.ProcessEnv): string;
+//#endregion
+//#region src/log.d.ts
+interface Logger {
+  warn(message: string): void;
+  debug(message: string): void;
+}
+/** Minimal stderr logger. `debug` lines only appear with DOWNTRACE_DEBUG. */
+declare function createLogger(debug: boolean, write?: (line: string) => void): Logger;
+//#endregion
+//#region src/transport.d.ts
+interface SenderOptions {
+  url: string;
+  token: string;
+  agent: AgentInfo;
+  instance: InstanceInfo;
+  deploy: DeployInfo;
+  log: Logger;
+  /** Intervals kept while the cloud is unreachable; the oldest is dropped beyond this. */
+  maxQueued?: number | undefined;
+  timeoutMs?: number | undefined;
+  fetchImpl?: typeof fetch | undefined;
+}
+declare const DEFAULT_MAX_QUEUED = 6;
+/**
+ * Ships intervals to the cloud in batches. Never blocks, never grows without
+ * bound: failed batches stay queued (up to maxQueued) and ride the next flush.
+ */
+declare class Sender {
+  private queue;
+  private inflight;
+  private warnedAuth;
+  sent: number;
+  failed: number;
+  dropped: number;
+  private readonly opts;
+  private readonly maxQueued;
+  private readonly timeoutMs;
+  private readonly fetchImpl;
+  constructor(opts: SenderOptions);
+  get pending(): number;
+  enqueue(interval: Interval): void;
+  /** Sends everything queued in one batch. Resolves true when the cloud accepted it. */
+  flush(timeoutMs?: number): Promise<boolean>;
+}
+//#endregion
+//#region src/agent.d.ts
+interface AgentDeps {
+  recorder?: Recorder | undefined;
+  sender?: Sender | undefined;
+  log?: Logger | undefined;
+  fetchImpl?: typeof fetch | undefined;
+  /** Flush on SIGTERM/SIGINT. Off in tests; on when loaded via register. */
+  handleSignals?: boolean | undefined;
+}
+interface AgentStats {
+  recorded: number;
+  internalErrors: number;
+  disabled: boolean;
+  sent: number;
+  failed: number;
+  dropped: number;
+  pending: number;
+}
+/**
+ * The Downtrace Node agent, v0: observes finished HTTP requests through
+ * diagnostics_channel, aggregates them per route and interval, and ships
+ * batches asynchronously. Nothing here runs synchronously against the cloud,
+ * nothing here can throw into the application, and memory is bounded.
+ */
+declare class Agent {
+  readonly config: AgentConfig;
+  readonly instance: InstanceInfo;
+  private readonly log;
+  private readonly recorder;
+  private readonly sender;
+  private readonly handleSignals;
+  private readonly starts;
+  private timer;
+  private started;
+  private recorded;
+  private internalErrors;
+  private disabled;
+  private readonly onStart;
+  private readonly onFinish;
+  private readonly onSignal;
+  private readonly onBeforeExit;
+  constructor(config: AgentConfig, deps?: AgentDeps);
+  get stats(): AgentStats;
+  start(): void;
+  /** Unsubscribes and stops timers; attempts a last flush. Idempotent. */
+  stop(): Promise<void>;
+  /** Closes the current interval and sends everything queued. */
+  flushNow(timeoutMs?: number): Promise<boolean>;
+  private requestStarted;
+  private responseFinished;
+  /** Every hook runs through here: an agent bug must never reach the application. */
+  private guard;
+  private internalError;
+  /**
+   * If we are the only listener, flush briefly and then let the default signal
+   * behaviour happen exactly as if the agent were not installed. If the app has
+   * its own handlers, flush in the background and stay out of the way.
+   */
+  private signalled;
+}
+declare function createAgent(config: AgentConfig, deps?: AgentDeps): Agent;
+//#endregion
+//#region src/version.d.ts
+/** Version of this agent build, from package.json. */
+declare const AGENT_VERSION: string;
+//#endregion
+export { AGENT_VERSION, Agent, type AgentConfig, type AgentDeps, type AgentStats, type ConfigResult, DEFAULT_INTERVAL_MS, DEFAULT_MAX_QUEUED, DEFAULT_MAX_ROUTES, IntervalAggregator, type Logger, type Method, OTHER_ROUTE, type Recorder, Sender, type SenderOptions, configFromEnv, createAgent, createLogger, detectVersion, heuristicTemplate, normalizeMethod, routeOf };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as createAgent, c as Sender, d as IntervalAggregator, f as OTHER_ROUTE, h as routeOf, i as Agent, l as createLogger, m as normalizeMethod, n as configFromEnv, o as AGENT_VERSION, p as heuristicTemplate, r as detectVersion, s as DEFAULT_MAX_QUEUED, t as DEFAULT_INTERVAL_MS, u as DEFAULT_MAX_ROUTES } from "./config-nKU1VRvi.js";
+export { AGENT_VERSION, Agent, DEFAULT_INTERVAL_MS, DEFAULT_MAX_QUEUED, DEFAULT_MAX_ROUTES, IntervalAggregator, OTHER_ROUTE, Sender, configFromEnv, createAgent, createLogger, detectVersion, heuristicTemplate, normalizeMethod, routeOf };

package/dist/register.d.ts

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

package/dist/register.js

@@ -0,0 +1,17 @@
+import { a as createAgent, l as createLogger, n as configFromEnv } from "./config-nKU1VRvi.js";
+//#region src/register.ts
+/**
+* Entry point users load with `node --import @downtrace/agent/register`.
+*
+* Reads DOWNTRACE_TOKEN / DOWNTRACE_URL (and friends) from the environment and
+* starts the agent. Without them it says so once and does nothing else: an
+* installed but unconfigured agent must never affect the application.
+*/
+const result = configFromEnv();
+if (result.ok) createAgent(result.config, {
+	log: createLogger(result.config.debug),
+	handleSignals: true
+}).start();
+else createLogger(false).warn(`agent disabled: ${result.reason}`);
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@downtrace/agent",
+  "version": "0.1.0",
+  "description": "Downtrace agent for Node.js: a flight recorder for your backend. Observes HTTP requests, aggregates locally, ships compact batches, never in your request path.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "default": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@downtrace/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "ajv": "^8.20.0",
+    "express": "^5.2.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RadW2020/downtrace-agent.git",
+    "directory": "packages/agent"
+  },
+  "homepage": "https://github.com/RadW2020/downtrace-agent#readme",
+  "keywords": [
+    "downtrace",
+    "observability",
+    "apm",
+    "agent",
+    "latency",
+    "regression",
+    "node"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsdown"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}