@alfe.ai/gateway 0.2.5 → 0.3.1

package/dist/bin/gateway.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as installService, c as uninstallService, f as SOCKET_PATH, i as checkExistingDaemon, n as queryDaemonHealth, r as startDaemon, s as stopExistingDaemon, t as formatHealthReport } from "../health.js";
+import { a as installService, c as uninstallService, i as checkExistingDaemon, n as queryDaemonHealth, r as startDaemon, s as stopExistingDaemon, t as formatHealthReport, y as SOCKET_PATH } from "../health.js";
 import { t as LOG_FILE } from "../logger.js";
 import { spawn } from "node:child_process";
 //#region bin/gateway.ts

package/dist/health.js

@@ -7,7 +7,7 @@ import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import pino from "pino";
 import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { getEndpointFromToken, readConfig } from "@alfe.ai/config";
+import { getEndpointFromToken, readConfig, resolveConfig } from "@alfe.ai/config";
 import crypto from "crypto";
 import { parse } from "smol-toml";
 import WebSocket from "ws";
@@ -5330,6 +5330,215 @@ var NoopRuntimeGate = class {
 	requestRestart() {}
 };
 //#endregion
+//#region src/sentry.ts
+/**
+* Agent-side error reporting (Sentry) for the Alfe CLI + gateway daemon.
+*
+* This module is the single Sentry bootstrap shared by both published
+* agent-side packages — `@alfe.ai/gateway` (the daemon) and `@alfe.ai/cli`
+* (which re-imports these helpers from `@alfe.ai/gateway`). It exists so
+* integration-installation failures on customer/managed VMs surface centrally
+* instead of silently rotting until someone SSHes into the box.
+*
+* Design constraints (see packages/gateway/DEVELOPING.md → "Error reporting"):
+*   - Errors only. No tracing/profiling (`tracesSampleRate: 0`, `sampleRate: 1`).
+*   - `@sentry/node` is lazy-imported so `alfe --version` doesn't pay for it.
+*   - Sentry can NEVER break the CLI/daemon — every entry point is try/catch'd.
+*   - The DSNs are baked as constants: published tarballs run on agent VMs and
+*     cannot read the repo's `config/config.ts`. That file's `SENTRY_DSNS`
+*     registry (keys `agentDaemon` + `cli`) mirrors them as the human reference.
+*   - Secrets are scrubbed in `beforeSend`; request/env payloads are dropped.
+*   - Opt-out via `ALFE_ERROR_REPORTING=0|false` or `errorReporting = false`
+*     in `~/.alfe/config.toml`. Default ON.
+*/
+/**
+* Baked per-surface Sentry DSNs (org `alfe-ai`). DSNs are public by design
+* (they only permit event ingestion). Mirrors of `config/config.ts` →
+* `SENTRY_DSNS.agentDaemon` / `SENTRY_DSNS.cli`. If you rotate a DSN, update
+* both places.
+*/
+const AGENT_DAEMON_SENTRY_DSN = "https://a47f010d8d39fb4350f913492189f283@o4511008239452160.ingest.us.sentry.io/4511679448547328";
+/** Surface → Sentry project: `cli` and `agent-daemon` respectively. */
+const SURFACE_DSNS = {
+	cli: "https://82dde4631336561f2fcc89d7531623de@o4511008239452160.ingest.us.sentry.io/4511679411191808",
+	daemon: AGENT_DAEMON_SENTRY_DSN
+};
+/** Held after a successful init so the capture helpers can run synchronously. */
+let sentry = null;
+/**
+* Map the configured API URL to a coarse environment tag. Best-effort — returns
+* `"unknown"` when no config is present yet (e.g. `alfe login` pre-setup).
+*/
+function deriveEnvironment() {
+	try {
+		const { apiUrl } = resolveConfig();
+		if (apiUrl.includes("api.dev.alfe.ai") || apiUrl.includes("dev.alfe.ai")) return "dev";
+		if (apiUrl.includes("api.test.alfe.ai")) return "test";
+		if (apiUrl.includes("api.demo.alfe.ai")) return "demo";
+		if (apiUrl.includes("api.alfe.ai")) return "prod";
+	} catch {}
+	return "unknown";
+}
+/** Active runtime (`openclaw`/`hermes`) from config, or undefined if unknown. */
+function deriveRuntime() {
+	try {
+		return resolveConfig().runtime;
+	} catch {
+		return;
+	}
+}
+/** True when the operator has opted out of error reporting. */
+function errorReportingDisabled() {
+	const env = process.env.ALFE_ERROR_REPORTING?.trim().toLowerCase();
+	if (env === "0" || env === "false") return true;
+	try {
+		if (readConfig().errorReporting === false) return true;
+	} catch {}
+	return false;
+}
+const KV_SECRET_RE = /\b(authorization|api[_-]?key|apikey|token|secret|password|passwd|bearer)\b(\s*[:=]\s*|\s+)("?)([^\s"']+)\3/gi;
+const MIN_BARE_SECRET_LEN = 16;
+const ALFE_TOKEN_RE = /alfe_(?:dev|test|demo|live)_[A-Za-z0-9._-]+/g;
+const BEARER_RE = /\bbearer\s+[A-Za-z0-9._\-+/=]+/gi;
+function scrubString(value) {
+	return value.replace(BEARER_RE, "Bearer [REDACTED]").replace(KV_SECRET_RE, (match, label, sep, _q, secret) => {
+		if (!/[:=]/.test(sep) && secret.length < MIN_BARE_SECRET_LEN) return match;
+		return `${label}${sep}[REDACTED]`;
+	}).replace(ALFE_TOKEN_RE, "alfe_[REDACTED]");
+}
+/** Scrub secrets from a breadcrumb's message + string data values in place. */
+function scrubBreadcrumb(b) {
+	if (typeof b.message === "string") b.message = scrubString(b.message);
+	const data = b.data;
+	if (data) for (const k of Object.keys(data)) {
+		const dv = data[k];
+		if (typeof dv === "string") data[k] = scrubString(dv);
+	}
+	return b;
+}
+/**
+* Scrub secrets and drop request/env payloads before an event is sent.
+* Generic so it preserves the caller's exact event subtype (`beforeSend`
+* receives — and must return — an `ErrorEvent`, not a widened `Event`).
+*/
+function scrubEvent(event) {
+	delete event.request;
+	if (event.contexts) delete event.contexts.runtime;
+	delete event.extra;
+	delete event.server_name;
+	if (typeof event.message === "string") event.message = scrubString(event.message);
+	const values = event.exception?.values;
+	if (values) {
+		for (const v of values) if (typeof v.value === "string") v.value = scrubString(v.value);
+	}
+	if (event.breadcrumbs) for (const b of event.breadcrumbs) scrubBreadcrumb(b);
+	return event;
+}
+/**
+* Initialise Sentry for the agent-side CLI/daemon. Idempotent, best-effort, and
+* a no-op when opted out or when the baked DSN is empty. Never throws.
+*/
+async function initAgentSentry(options) {
+	try {
+		if (sentry) return;
+		if (errorReportingDisabled()) return;
+		const dsn = SURFACE_DSNS[options.surface].trim();
+		if (!dsn) return;
+		const mod = await import("@sentry/node");
+		if (mod.getClient()) {
+			sentry = mod;
+			return;
+		}
+		mod.init({
+			dsn,
+			environment: deriveEnvironment(),
+			...options.release ? { release: options.release } : {},
+			sampleRate: 1,
+			tracesSampleRate: 0,
+			sendDefaultPii: false,
+			beforeSend: (event) => scrubEvent(event),
+			beforeBreadcrumb: (breadcrumb) => scrubBreadcrumb(breadcrumb)
+		});
+		sentry = mod;
+		mod.setTag("surface", options.surface);
+		const runtime = deriveRuntime();
+		if (runtime) mod.setTag("runtime", runtime);
+	} catch {
+		sentry = null;
+	}
+}
+/**
+* Attach the resolved agent identity to all subsequent events. Called by the
+* daemon once `loadDaemonConfig()` has resolved `agentId`/`runtime`.
+*/
+function setAgentContext(context) {
+	if (!sentry) return;
+	try {
+		if (context.agentId) sentry.setTag("agentId", context.agentId);
+		if (context.runtime) sentry.setTag("runtime", context.runtime);
+	} catch {}
+}
+/**
+* Capture an integration lifecycle failure (install/activate/reinstall/remove)
+* with `{ integration, phase }` tags. Accepts an `Error` (captured with stack)
+* or a plain message string (captured as an error-level message). No-op when
+* Sentry is not initialised.
+*/
+function captureIntegrationFailure(integration, phase, cause) {
+	if (!sentry) return;
+	try {
+		if (cause instanceof Error) sentry.captureException(cause, { tags: {
+			integration,
+			phase
+		} });
+		else sentry.captureMessage(String(cause), {
+			level: "error",
+			tags: {
+				integration,
+				phase
+			}
+		});
+	} catch {}
+}
+/**
+* Capture a generic CLI failure with a `{ context }` tag. The CLI counterpart
+* to `captureIntegrationFailure` — used by `exitWithError` at the handled-error
+* `process.exit()` sites in `@alfe.ai/cli`'s commands, which otherwise report
+* nothing (the error was caught, never thrown). Accepts an `Error` (captured
+* with stack), a defined non-Error value (captured as an error-level message),
+* or nothing (the `context` string itself becomes the message). No-op when
+* Sentry is not initialised. Never throws.
+*/
+function captureCliFailure(context, cause) {
+	if (!sentry) return;
+	try {
+		if (cause instanceof Error) sentry.captureException(cause, { tags: { context } });
+		else if (cause === void 0) sentry.captureMessage(context, { level: "error" });
+		else sentry.captureMessage(String(cause), {
+			level: "error",
+			tags: { context }
+		});
+	} catch {}
+}
+/** Flush queued events (small timeout) so short-lived commands deliver them. */
+async function flushSentry(timeoutMs = 2e3) {
+	if (!sentry) return;
+	try {
+		await sentry.flush(timeoutMs);
+	} catch {}
+}
+/**
+* Capture a fatal error — for the CLI's top-level catch. Does NOT flush: the
+* caller's `finally { await flushSentry() }` delivers it (flushing here too
+* doubled the worst-case exit delay on a failing command).
+*/
+function captureFatal(cause) {
+	if (!sentry) return;
+	try {
+		sentry.captureException(cause);
+	} catch {}
+}
+//#endregion
 //#region src/reconciliation.ts
 const log$2 = logger$1.child({ component: "Reconciliation" });
 /**
@@ -5466,6 +5675,7 @@ var ReconciliationEngine = class {
 					const attempts = this.manager.getReinstallAttempts(id);
 					if (attempts >= 3) {
 						log$2.error(`Auto-reinstall blocked for ${id} — ${String(attempts)} consecutive failures. Manual reinstall required.`);
+						captureIntegrationFailure(id, "reinstall", `Max auto-reinstall attempts (${String(attempts)}) reached — manual reinstall required`);
 						report.errors.push({
 							integrationId: id,
 							error: `Max auto-reinstall attempts (${String(attempts)}) reached`
@@ -5495,6 +5705,7 @@ var ReconciliationEngine = class {
 					} catch (reinstallErr) {
 						const reinstallMsg = reinstallErr instanceof Error ? reinstallErr.message : String(reinstallErr);
 						log$2.error({ err: reinstallErr }, `Auto-reinstall failed for ${id}`);
+						captureIntegrationFailure(id, "reinstall", reinstallErr);
 						report.errors.push({
 							integrationId: id,
 							error: reinstallMsg
@@ -5526,6 +5737,7 @@ var ReconciliationEngine = class {
 					} catch (reactivateErr) {
 						const reactivateMsg = reactivateErr instanceof Error ? reactivateErr.message : String(reactivateErr);
 						log$2.warn(`Re-activation of ${id} from error state failed (attempt ${String(activateAttempts + 1)}/${String(MAX_ERROR_ACTIVATE_ATTEMPTS)}): ${reactivateMsg}`);
+						captureIntegrationFailure(id, "reactivate", reactivateErr);
 						report.errors.push({
 							integrationId: id,
 							error: reactivateMsg
@@ -5540,6 +5752,7 @@ var ReconciliationEngine = class {
 					}
 				}
 				log$2.warn(`Integration ${id} is in error state — re-activation exhausted, waiting for reinstall request`);
+				captureIntegrationFailure(id, "reactivate", `Integration ${id} stuck in error state — re-activation attempts exhausted`);
 				report.errors.push({
 					integrationId: id,
 					error: "Integration is in error state"
@@ -5588,6 +5801,7 @@ var ReconciliationEngine = class {
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			log$2.error({ err }, `Error reconciling ${id}`);
+			captureIntegrationFailure(id, "reconcile_active", err);
 			report.errors.push({
 				integrationId: id,
 				error: message
@@ -5626,6 +5840,7 @@ var ReconciliationEngine = class {
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			log$2.error({ err }, `Error removing ${id}`);
+			captureIntegrationFailure(id, "reconcile_removed", err);
 			report.errors.push({
 				integrationId: id,
 				error: message
@@ -22530,6 +22745,7 @@ async function getRuntimeVersion(runtime) {
 * process.exit() can drop buffered log lines — this ensures they're written first.
 */
 async function flushAndExit(code) {
+	await flushSentry();
 	await new Promise((resolve) => {
 		logger$1.flush();
 		setTimeout(resolve, 500);
@@ -22592,6 +22808,10 @@ async function startDaemon() {
 		managed,
 		pid: process.pid
 	}, "Starting Alfe Gateway Daemon...");
+	await initAgentSentry({
+		surface: "daemon",
+		release: await getCliVersion()
+	});
 	if (!managed) {
 		await mkdir(join(homedir(), ".alfe"), { recursive: true });
 		const existingPid = await checkExistingDaemon();
@@ -22608,6 +22828,10 @@ async function startDaemon() {
 			orgId: config.orgId,
 			wsUrl: config.gatewayWsUrl
 		}, "Config loaded, identity resolved");
+		setAgentContext({
+			agentId: config.agentId,
+			runtime: config.runtime
+		});
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		const stack = err instanceof Error ? err.stack : void 0;
@@ -23575,4 +23799,4 @@ function formatDuration(ms) {
 	return `${String(Math.round(seconds / 3600))}h`;
 }
 //#endregion
-export { installService as a, uninstallService as c, PID_PATH as d, SOCKET_PATH as f, PINNED_OPENCLAW_VERSION as g, resolveAgentIdentity as h, checkExistingDaemon as i, PROTOCOL_VERSION as l, loadDaemonConfig as m, queryDaemonHealth as n, startService as o, fetchAgentConfig as p, startDaemon as r, stopExistingDaemon as s, formatHealthReport as t, ALFE_DIR as u };
+export { PINNED_OPENCLAW_VERSION as C, resolveAgentIdentity as S, ALFE_DIR as _, installService as a, fetchAgentConfig as b, uninstallService as c, captureFatal as d, captureIntegrationFailure as f, PROTOCOL_VERSION as g, setAgentContext as h, checkExistingDaemon as i, AGENT_DAEMON_SENTRY_DSN as l, initAgentSentry as m, queryDaemonHealth as n, startService as o, flushSentry as p, startDaemon as r, stopExistingDaemon as s, formatHealthReport as t, captureCliFailure as u, PID_PATH as v, loadDaemonConfig as x, SOCKET_PATH as y };

package/dist/src/index.d.ts

@@ -46,6 +46,81 @@ declare function startDaemon(): Promise<void>;
  */
 declare const PINNED_OPENCLAW_VERSION = "2026.6.8";
 //#endregion
+//#region src/sentry.d.ts
+/**
+ * Agent-side error reporting (Sentry) for the Alfe CLI + gateway daemon.
+ *
+ * This module is the single Sentry bootstrap shared by both published
+ * agent-side packages — `@alfe.ai/gateway` (the daemon) and `@alfe.ai/cli`
+ * (which re-imports these helpers from `@alfe.ai/gateway`). It exists so
+ * integration-installation failures on customer/managed VMs surface centrally
+ * instead of silently rotting until someone SSHes into the box.
+ *
+ * Design constraints (see packages/gateway/DEVELOPING.md → "Error reporting"):
+ *   - Errors only. No tracing/profiling (`tracesSampleRate: 0`, `sampleRate: 1`).
+ *   - `@sentry/node` is lazy-imported so `alfe --version` doesn't pay for it.
+ *   - Sentry can NEVER break the CLI/daemon — every entry point is try/catch'd.
+ *   - The DSNs are baked as constants: published tarballs run on agent VMs and
+ *     cannot read the repo's `config/config.ts`. That file's `SENTRY_DSNS`
+ *     registry (keys `agentDaemon` + `cli`) mirrors them as the human reference.
+ *   - Secrets are scrubbed in `beforeSend`; request/env payloads are dropped.
+ *   - Opt-out via `ALFE_ERROR_REPORTING=0|false` or `errorReporting = false`
+ *     in `~/.alfe/config.toml`. Default ON.
+ */
+/**
+ * Baked per-surface Sentry DSNs (org `alfe-ai`). DSNs are public by design
+ * (they only permit event ingestion). Mirrors of `config/config.ts` →
+ * `SENTRY_DSNS.agentDaemon` / `SENTRY_DSNS.cli`. If you rotate a DSN, update
+ * both places.
+ */
+declare const AGENT_DAEMON_SENTRY_DSN = "https://a47f010d8d39fb4350f913492189f283@o4511008239452160.ingest.us.sentry.io/4511679448547328";
+/** Which surface initialised Sentry — tagged on every event. */
+type SentrySurface = "cli" | "daemon";
+interface InitAgentSentryOptions {
+  /** `"cli"` or `"daemon"` — tagged as `surface`. */
+  surface: SentrySurface;
+  /** Release identifier — the package version. */
+  release?: string;
+}
+/**
+ * Initialise Sentry for the agent-side CLI/daemon. Idempotent, best-effort, and
+ * a no-op when opted out or when the baked DSN is empty. Never throws.
+ */
+declare function initAgentSentry(options: InitAgentSentryOptions): Promise<void>;
+/**
+ * Attach the resolved agent identity to all subsequent events. Called by the
+ * daemon once `loadDaemonConfig()` has resolved `agentId`/`runtime`.
+ */
+declare function setAgentContext(context: {
+  agentId?: string;
+  runtime?: string;
+}): void;
+/**
+ * Capture an integration lifecycle failure (install/activate/reinstall/remove)
+ * with `{ integration, phase }` tags. Accepts an `Error` (captured with stack)
+ * or a plain message string (captured as an error-level message). No-op when
+ * Sentry is not initialised.
+ */
+declare function captureIntegrationFailure(integration: string, phase: string, cause: unknown): void;
+/**
+ * Capture a generic CLI failure with a `{ context }` tag. The CLI counterpart
+ * to `captureIntegrationFailure` — used by `exitWithError` at the handled-error
+ * `process.exit()` sites in `@alfe.ai/cli`'s commands, which otherwise report
+ * nothing (the error was caught, never thrown). Accepts an `Error` (captured
+ * with stack), a defined non-Error value (captured as an error-level message),
+ * or nothing (the `context` string itself becomes the message). No-op when
+ * Sentry is not initialised. Never throws.
+ */
+declare function captureCliFailure(context: string, cause?: unknown): void;
+/** Flush queued events (small timeout) so short-lived commands deliver them. */
+declare function flushSentry(timeoutMs?: number): Promise<void>;
+/**
+ * Capture a fatal error — for the CLI's top-level catch. Does NOT flush: the
+ * caller's `finally { await flushSentry() }` delivers it (flushing here too
+ * doubled the worst-case exit delay on a failing command).
+ */
+declare function captureFatal(cause: unknown): void;
+//#endregion
 //#region src/config.d.ts
 /**
  * Daemon configuration — reads ~/.alfe/config.toml and resolves agent identity.
@@ -218,4 +293,4 @@ declare function checkExistingDaemon(): Promise<number | null>;
  */
 declare function stopExistingDaemon(): Promise<boolean>;
 //#endregion
-export { ALFE_DIR, type AgentIdentity, type AgentWorkspaceConfig, type DaemonConfig, type DaemonHealth, type IPCEvent, type IPCRequest, type IPCResponse, PID_PATH, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, SOCKET_PATH, checkExistingDaemon, fetchAgentConfig, formatHealthReport, installService, loadDaemonConfig, logger, queryDaemonHealth, resolveAgentIdentity, startDaemon, startService, stopExistingDaemon, uninstallService };
+export { AGENT_DAEMON_SENTRY_DSN, ALFE_DIR, type AgentIdentity, type AgentWorkspaceConfig, type DaemonConfig, type DaemonHealth, type IPCEvent, type IPCRequest, type IPCResponse, type InitAgentSentryOptions, PID_PATH, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, SOCKET_PATH, type SentrySurface, captureCliFailure, captureFatal, captureIntegrationFailure, checkExistingDaemon, fetchAgentConfig, flushSentry, formatHealthReport, initAgentSentry, installService, loadDaemonConfig, logger, queryDaemonHealth, resolveAgentIdentity, setAgentContext, startDaemon, startService, stopExistingDaemon, uninstallService };

package/dist/src/index.js

@@ -1,3 +1,3 @@
-import { a as installService, c as uninstallService, d as PID_PATH, f as SOCKET_PATH, g as PINNED_OPENCLAW_VERSION, h as resolveAgentIdentity, i as checkExistingDaemon, l as PROTOCOL_VERSION, m as loadDaemonConfig, n as queryDaemonHealth, o as startService, p as fetchAgentConfig, r as startDaemon, s as stopExistingDaemon, t as formatHealthReport, u as ALFE_DIR } from "../health.js";
+import { C as PINNED_OPENCLAW_VERSION, S as resolveAgentIdentity, _ as ALFE_DIR, a as installService, b as fetchAgentConfig, c as uninstallService, d as captureFatal, f as captureIntegrationFailure, g as PROTOCOL_VERSION, h as setAgentContext, i as checkExistingDaemon, l as AGENT_DAEMON_SENTRY_DSN, m as initAgentSentry, n as queryDaemonHealth, o as startService, p as flushSentry, r as startDaemon, s as stopExistingDaemon, t as formatHealthReport, u as captureCliFailure, v as PID_PATH, x as loadDaemonConfig, y as SOCKET_PATH } from "../health.js";
 import { n as logger } from "../logger.js";
-export { ALFE_DIR, PID_PATH, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, SOCKET_PATH, checkExistingDaemon, fetchAgentConfig, formatHealthReport, installService, loadDaemonConfig, logger, queryDaemonHealth, resolveAgentIdentity, startDaemon, startService, stopExistingDaemon, uninstallService };
+export { AGENT_DAEMON_SENTRY_DSN, ALFE_DIR, PID_PATH, PINNED_OPENCLAW_VERSION, PROTOCOL_VERSION, SOCKET_PATH, captureCliFailure, captureFatal, captureIntegrationFailure, checkExistingDaemon, fetchAgentConfig, flushSentry, formatHealthReport, initAgentSentry, installService, loadDaemonConfig, logger, queryDaemonHealth, resolveAgentIdentity, setAgentContext, startDaemon, startService, stopExistingDaemon, uninstallService };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/gateway",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "Alfe local gateway daemon — persistent control plane for agent integrations",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "dist"
   ],
   "dependencies": {
+    "@sentry/node": "^10.42.0",
     "pino": "^9.6.0",
     "pino-roll": "^1.2.0",
     "smol-toml": ">=1.6.1",
@@ -26,7 +27,7 @@
     "@alfe.ai/ai-proxy-local": "^0.0.13",
     "@alfe.ai/config": "^0.3.0",
     "@alfe.ai/integration-manifest": "^0.3.1",
-    "@alfe.ai/integrations": "^0.2.6",
+    "@alfe.ai/integrations": "^0.2.7",
     "@alfe.ai/mcp-bundler": "^0.2.2"
   },
   "license": "UNLICENSED",