@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/db_naming.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Per-project database name resolution with historical-name compatibility.
+ *
+ * Mirrors the orchestration-engine Go implementation
+ * (`internal/domains/orchestration-engine/dbresolve.go`) and the Python copies
+ * (`mongomem_core/db_naming.py`, `agent_engine_runner_shared/db_naming.py`). The codebases
+ * are independent, so the algorithm is intentionally duplicated rather than
+ * shared. Keep them in sync. See
+ * `docs/decisions/008-per-project-database-isolation.md`.
+ *
+ * The runner/AER applies this to the agent *store* database only; memory
+ * writes go through the memory-server proxy, which scopes its own database.
+ */
+/**
+ * Derive the effective database name for `base` scoped to `projectId`.
+ *
+ * 1. empty `projectId` -> return `base` unchanged.
+ * 2. `base` already ends with `_{projectId}` -> return as-is (idempotent).
+ * 3. `scoped = base + "_" + projectId`:
+ *    - `scoped` exists on the cluster -> use it.
+ *    - else an existing scoped `legacyBases` candidate -> use it.
+ *    - else an existing unscoped `legacyBases` candidate -> use it.
+ *    - else -> use `scoped` (fresh deployment).
+ *
+ * Unscoped fallback is limited to known platform defaults. The current base and arbitrary names are never auto-adopted.
+ */
+export declare function resolveProjectScopedDb(base: string, projectId: string, existing: string[], legacyBases?: string[]): string;
+/**
+ * Whether an empty PROJECT_ID must fail closed (REQUIRE_PROJECT_SCOPED_DB).
+ *
+ * ECP stamps this flag on managed AER pods (where PROJECT_ID is always injected),
+ * so an empty PROJECT_ID there fails closed rather than silently writing to the
+ * unscoped store. Local CLI dev leaves the flag unset and uses the unscoped name.
+ */
+export declare function projectScopingRequired(): boolean;
+export interface ListsDatabaseNames {
+    listDatabaseNames(): Promise<string[]>;
+}
+/**
+ * Resolve `base` against the live cluster via `listDatabaseNames`.
+ *
+ * Empty `projectId` throws when scoping is required (`required`, defaulting to
+ * {@link projectScopingRequired}), else warns and returns `base`. A listing
+ * failure throws so a transient error cannot create a competing current-name
+ * database beside an existing legacy one. `legacyBases` are previous defaults
+ * whose project-scoped forms, then bare forms, are adopted before a fresh
+ * scoped database is created.
+ */
+export declare function resolveEffectiveDb(client: ListsDatabaseNames, base: string, projectId: string, opts?: {
+    required?: boolean;
+    label?: string;
+    legacyBases?: string[];
+}): Promise<string>;
+//# sourceMappingURL=db_naming.d.ts.map

package/dist/db_naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db_naming.d.ts","sourceRoot":"","sources":["../src/db_naming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,GAAE,MAAM,EAAO,GACzB,MAAM,CAeR;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAIhD;AAED,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACxC;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GACxE,OAAO,CAAC,MAAM,CAAC,CAuCjB"}

package/dist/db_naming.js

@@ -0,0 +1,94 @@
+/**
+ * Per-project database name resolution with historical-name compatibility.
+ *
+ * Mirrors the orchestration-engine Go implementation
+ * (`internal/domains/orchestration-engine/dbresolve.go`) and the Python copies
+ * (`mongomem_core/db_naming.py`, `agent_engine_runner_shared/db_naming.py`). The codebases
+ * are independent, so the algorithm is intentionally duplicated rather than
+ * shared. Keep them in sync. See
+ * `docs/decisions/008-per-project-database-isolation.md`.
+ *
+ * The runner/AER applies this to the agent *store* database only; memory
+ * writes go through the memory-server proxy, which scopes its own database.
+ */
+import { getLogger } from "./logger.js";
+const logger = getLogger("agent_engine_runner_shared.db_naming");
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+/**
+ * Derive the effective database name for `base` scoped to `projectId`.
+ *
+ * 1. empty `projectId` -> return `base` unchanged.
+ * 2. `base` already ends with `_{projectId}` -> return as-is (idempotent).
+ * 3. `scoped = base + "_" + projectId`:
+ *    - `scoped` exists on the cluster -> use it.
+ *    - else an existing scoped `legacyBases` candidate -> use it.
+ *    - else an existing unscoped `legacyBases` candidate -> use it.
+ *    - else -> use `scoped` (fresh deployment).
+ *
+ * Unscoped fallback is limited to known platform defaults. The current base and arbitrary names are never auto-adopted.
+ */
+export function resolveProjectScopedDb(base, projectId, existing, legacyBases = []) {
+    if (!projectId)
+        return base;
+    const suffix = "_" + projectId;
+    if (base.endsWith(suffix))
+        return base;
+    const scoped = base + suffix;
+    const names = new Set(existing);
+    if (names.has(scoped))
+        return scoped;
+    for (const legacy of legacyBases) {
+        const legacyScoped = legacy + suffix;
+        if (names.has(legacyScoped))
+            return legacyScoped;
+    }
+    for (const legacy of legacyBases) {
+        if (names.has(legacy))
+            return legacy;
+    }
+    return scoped;
+}
+/**
+ * Whether an empty PROJECT_ID must fail closed (REQUIRE_PROJECT_SCOPED_DB).
+ *
+ * ECP stamps this flag on managed AER pods (where PROJECT_ID is always injected),
+ * so an empty PROJECT_ID there fails closed rather than silently writing to the
+ * unscoped store. Local CLI dev leaves the flag unset and uses the unscoped name.
+ */
+export function projectScopingRequired() {
+    return TRUTHY.has((process.env["REQUIRE_PROJECT_SCOPED_DB"] ?? "").trim().toLowerCase());
+}
+/**
+ * Resolve `base` against the live cluster via `listDatabaseNames`.
+ *
+ * Empty `projectId` throws when scoping is required (`required`, defaulting to
+ * {@link projectScopingRequired}), else warns and returns `base`. A listing
+ * failure throws so a transient error cannot create a competing current-name
+ * database beside an existing legacy one. `legacyBases` are previous defaults
+ * whose project-scoped forms, then bare forms, are adopted before a fresh
+ * scoped database is created.
+ */
+export async function resolveEffectiveDb(client, base, projectId, opts = {}) {
+    const required = opts.required ?? projectScopingRequired();
+    const label = opts.label ?? "database";
+    if (!projectId) {
+        if (required) {
+            throw new Error(`PROJECT_ID is empty but per-project DB isolation is required ` +
+                `(REQUIRE_PROJECT_SCOPED_DB); refusing to use the unscoped ${label} '${base}'`);
+        }
+        logger.warn(`PROJECT_ID is empty; per-project DB isolation disabled, using unscoped ${label} '${base}'`);
+        return base;
+    }
+    let existing;
+    try {
+        existing = await client.listDatabaseNames();
+    }
+    catch (err) {
+        throw new Error(`database discovery failed for project '${projectId}'; refusing to select a database`, { cause: err });
+    }
+    const resolved = resolveProjectScopedDb(base, projectId, existing, opts.legacyBases);
+    if (resolved !== base + "_" + projectId && !base.endsWith("_" + projectId)) {
+        logger.info(`using historical ${label} '${resolved}' for project '${projectId}'`);
+    }
+    return resolved;
+}

package/dist/error_reporting.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared local error reporting helpers for CLI-generated runtime flows.
+ *
+ * Mirrors `agent_engine_runner_shared/error_reporting.py`. Reports agent runtime/build
+ * failures to Sentry, gated by env (`AGENTIC_SENTRY_ENABLED=1` + a DSN). All
+ * outbound payloads are scrubbed for secrets and the caller's home directory
+ * via `beforeSend` plus per-value redaction before capture.
+ *
+ * `@sentry/node` is an *optional* dependency (a devDependency here for types
+ * and tests): it is loaded via a guarded dynamic import only when reporting is
+ * enabled, so agents that never flip `AGENTIC_SENTRY_ENABLED` never install or
+ * pay for it. When the module isn't present, or anything in the reporting path
+ * faults, every function degrades to a no-op — reporting must never block an
+ * agent from starting or mask its real failure.
+ */
+type SeverityLevel = "fatal" | "error" | "warning" | "log" | "info" | "debug";
+/** @internal — test-only override of the resolved home directory. */
+export declare function setHomeDirForTest(dir: string): void;
+export interface InitErrorReportingArgs {
+    surface: string;
+    component?: string | null;
+    mode?: string | null;
+}
+/**
+ * Initialize Sentry error reporting. No-op (returns `false`) unless
+ * `AGENTIC_SENTRY_ENABLED=1` and `AGENTIC_SENTRY_DSN` are both set, and
+ * `@sentry/node` is installed. Tags every event with `surface` and, when
+ * provided, `component` / `mode`.
+ *
+ * Never throws: a missing module or a faulting `Sentry.init` leaves reporting
+ * disabled rather than propagating — enabling observability must not turn into
+ * a boot blocker.
+ */
+export declare function initErrorReporting(args: InitErrorReportingArgs): Promise<boolean>;
+export interface CaptureExceptionArgs {
+    summary?: string | null;
+    extra?: Record<string, unknown>;
+}
+/**
+ * Capture an exception. When `summary` is given, the reported error message is
+ * the (redacted) summary with the original exception's type/message preserved
+ * as scoped extras — matching Python's `_exception_for_capture`.
+ */
+export declare function captureException(exc: unknown, args?: CaptureExceptionArgs): void;
+export declare function captureMessage(message: string, level?: SeverityLevel, extra?: Record<string, unknown>): void;
+export declare function flush(timeoutMs?: number): Promise<void>;
+export interface SubprocessFailure {
+    /** The command that failed — array (argv) or a single string. */
+    command: string | readonly string[];
+    /** Process exit code, if known. */
+    exitCode?: number | null;
+    stdout?: string | Uint8Array | null;
+    stderr?: string | Uint8Array | null;
+}
+/**
+ * A one-line summary of a failed subprocess: the command label plus the most
+ * meaningful line of its output, or the exit code when no output stands out.
+ */
+export declare function summarizeSubprocessFailure(exc: SubprocessFailure): string;
+/** The trailing `MAX_OUTPUT_TAIL_CHARS` of a subprocess's stdout+stderr. */
+export declare function subprocessOutputTail(exc: SubprocessFailure): string;
+/** @internal — exported only for tests; not part of the public API. */
+export declare function beforeSend(event: Record<string, unknown>, _hint?: unknown): Record<string, unknown>;
+/** @internal — exported only for tests; not part of the public API. */
+export declare function redactText(text: string): string;
+export {};
+//# sourceMappingURL=error_reporting.d.ts.map

package/dist/error_reporting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_reporting.d.ts","sourceRoot":"","sources":["../src/error_reporting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,KAAK,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAiC9E,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAwClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,IAAI,GAAE,oBAAyB,GAC9B,IAAI,CAwBN;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,aAAuB,EAC9B,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,IAAI,CAaN;AAED,wBAAsB,KAAK,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAO3D;AAMD,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACpC,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAKzE;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAUnE;AAMD,uEAAuE;AACvE,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,CAAC,EAAE,OAAO,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBzB;AAmCD,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C"}

package/dist/error_reporting.js

@@ -0,0 +1,311 @@
+/**
+ * Shared local error reporting helpers for CLI-generated runtime flows.
+ *
+ * Mirrors `agent_engine_runner_shared/error_reporting.py`. Reports agent runtime/build
+ * failures to Sentry, gated by env (`AGENTIC_SENTRY_ENABLED=1` + a DSN). All
+ * outbound payloads are scrubbed for secrets and the caller's home directory
+ * via `beforeSend` plus per-value redaction before capture.
+ *
+ * `@sentry/node` is an *optional* dependency (a devDependency here for types
+ * and tests): it is loaded via a guarded dynamic import only when reporting is
+ * enabled, so agents that never flip `AGENTIC_SENTRY_ENABLED` never install or
+ * pay for it. When the module isn't present, or anything in the reporting path
+ * faults, every function degrades to a no-op — reporting must never block an
+ * agent from starting or mask its real failure.
+ */
+import { homedir } from "node:os";
+// The lazily-imported @sentry/node module; null until a successful enable.
+let sentry = null;
+let enabled = false;
+const MAX_SUMMARY_LINE_LENGTH = 240;
+const MAX_OUTPUT_TAIL_CHARS = 8 * 1024;
+// Cap redaction recursion so a self-referential or pathologically nested
+// caller-supplied `extra` can't drive `redactValue` into a stack overflow.
+const MAX_REDACT_DEPTH = 12;
+// `key=value` / `key: value` inline secrets. Case-insensitive; keeps the key
+// and separator, redacts the value up to the next whitespace/comma/semicolon.
+const SECRET_INLINE_PATTERN = /\b(api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password)(=|:)\s*([^\s,;]+)/gi;
+const BEARER_PATTERN = /\b(bearer)\s+[A-Za-z0-9._-]+/gi;
+const URL_USERINFO_PATTERN = /\b([a-z][a-z0-9+.-]*:\/\/)[^:/\s@]+:[^@\s/]+@/gi;
+// Bare-token form (scheme://token@host, no ":" separator) — e.g. a GitHub PAT
+// embedded as `https://ghp_xxx@github.com`. Applied after URL_USERINFO_PATTERN
+// so a user:pass@ pair is never double-matched by this looser pattern.
+const URL_USERINFO_BARE_PATTERN = /\b([a-z][a-z0-9+.-]*:\/\/)[^:/\s@]+@/gi;
+function resolveHomeDir() {
+    try {
+        return homedir().trim();
+    }
+    catch {
+        return (process.env["HOME"] ?? "").trim();
+    }
+}
+let homeDir = resolveHomeDir();
+/** @internal — test-only override of the resolved home directory. */
+export function setHomeDirForTest(dir) {
+    homeDir = dir;
+}
+/**
+ * Initialize Sentry error reporting. No-op (returns `false`) unless
+ * `AGENTIC_SENTRY_ENABLED=1` and `AGENTIC_SENTRY_DSN` are both set, and
+ * `@sentry/node` is installed. Tags every event with `surface` and, when
+ * provided, `component` / `mode`.
+ *
+ * Never throws: a missing module or a faulting `Sentry.init` leaves reporting
+ * disabled rather than propagating — enabling observability must not turn into
+ * a boot blocker.
+ */
+export async function initErrorReporting(args) {
+    enabled = false;
+    sentry = null;
+    const dsn = (process.env["AGENTIC_SENTRY_DSN"] ?? "").trim();
+    if (!(process.env["AGENTIC_SENTRY_ENABLED"] === "1" && dsn))
+        return false;
+    try {
+        sentry = await import("@sentry/node");
+    }
+    catch {
+        // @sentry/node not installed — reporting is opt-in, so stay disabled.
+        return false;
+    }
+    try {
+        sentry.init({
+            dsn,
+            environment: process.env["AGENTIC_SENTRY_ENVIRONMENT"] ?? "local-dev",
+            release: process.env["AGENTIC_SENTRY_RELEASE"] || undefined,
+            tracesSampleRate: 0.0,
+            debug: process.env["AGENTIC_SENTRY_DEBUG"] === "1",
+            // Our scrubber operates on a generic event dict and returns the same
+            // (mutated) object; narrow the return to the callback's event type.
+            beforeSend: (event, hint) => beforeSend(event, hint),
+        });
+        sentry.setTag("surface", args.surface);
+        if (args.component)
+            sentry.setTag("component", args.component);
+        if (args.mode)
+            sentry.setTag("mode", args.mode);
+    }
+    catch {
+        // A malformed DSN/environment or any init fault disables reporting rather
+        // than crashing the agent at boot.
+        sentry = null;
+        return false;
+    }
+    enabled = true;
+    return true;
+}
+/**
+ * Capture an exception. When `summary` is given, the reported error message is
+ * the (redacted) summary with the original exception's type/message preserved
+ * as scoped extras — matching Python's `_exception_for_capture`.
+ */
+export function captureException(exc, args = {}) {
+    if (!enabled || !sentry)
+        return;
+    const s = sentry;
+    // Reporting must never throw into the caller — a fault here would mask the
+    // very failure the caller is trying to report.
+    try {
+        const { summary, extra } = args;
+        const captured = exceptionForCapture(exc, summary);
+        s.withScope((scope) => {
+            if (summary) {
+                scope.setExtra("original_exception_type", exc instanceof Error ? exc.name : typeof exc);
+                scope.setExtra("original_exception_message", redactText(String(exc)));
+            }
+            for (const [key, value] of Object.entries(extra ?? {})) {
+                scope.setExtra(key, redactValue(value));
+            }
+            s.captureException(captured);
+        });
+    }
+    catch {
+        /* swallow — best-effort reporting */
+    }
+}
+export function captureMessage(message, level = "error", extra = {}) {
+    if (!enabled || !sentry)
+        return;
+    const s = sentry;
+    try {
+        s.withScope((scope) => {
+            for (const [key, value] of Object.entries(extra)) {
+                scope.setExtra(key, redactValue(value));
+            }
+            s.captureMessage(redactText(message), level);
+        });
+    }
+    catch {
+        /* swallow — best-effort reporting */
+    }
+}
+export async function flush(timeoutMs = 2000) {
+    if (!enabled || !sentry)
+        return;
+    try {
+        await sentry.flush(timeoutMs);
+    }
+    catch {
+        /* swallow — best-effort reporting */
+    }
+}
+/**
+ * A one-line summary of a failed subprocess: the command label plus the most
+ * meaningful line of its output, or the exit code when no output stands out.
+ */
+export function summarizeSubprocessFailure(exc) {
+    const command = commandLabel(exc.command);
+    const headline = failureHeadline(subprocessOutputTail(exc));
+    if (headline)
+        return `${command} failed: ${headline}`;
+    return `${command} failed with exit ${exc.exitCode ?? "unknown"}`;
+}
+/** The trailing `MAX_OUTPUT_TAIL_CHARS` of a subprocess's stdout+stderr. */
+export function subprocessOutputTail(exc) {
+    const chunks = [];
+    for (const value of [exc.stdout, exc.stderr]) {
+        if (value === null || value === undefined)
+            continue;
+        chunks.push(typeof value === "string" ? value : Buffer.from(value).toString("utf-8"));
+    }
+    if (chunks.length === 0)
+        return "";
+    return tailText(chunks.join("\n"));
+}
+// =============================================================================
+// Redaction — internal, but pure and unit-tested directly
+// =============================================================================
+/** @internal — exported only for tests; not part of the public API. */
+export function beforeSend(event, _hint) {
+    const data = event;
+    data["server_name"] = null;
+    if ("message" in data) {
+        data["message"] = redactText(String(data["message"]));
+    }
+    for (const section of [
+        "request",
+        "user",
+        "tags",
+        "extra",
+        "contexts",
+        "exception",
+        "breadcrumbs",
+        "threads",
+        "logentry",
+        "modules",
+    ]) {
+        const payload = data[section];
+        if (payload !== null && typeof payload === "object") {
+            data[section] = redactValue(payload);
+        }
+    }
+    return event;
+}
+/**
+ * Recursively redact strings in a value. Guards against caller-supplied
+ * `extra` that is self-referential (WeakSet cycle check) or pathologically
+ * deep (`MAX_REDACT_DEPTH`): either would otherwise overflow the stack and
+ * take down the reporting path. A cycle/over-depth node is replaced with a
+ * sentinel rather than recursed into.
+ */
+function redactValue(value, depth = 0, seen = new WeakSet()) {
+    if (typeof value === "string")
+        return redactText(value);
+    if (value === null || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[Circular]";
+    if (depth >= MAX_REDACT_DEPTH)
+        return "[MaxDepth]";
+    seen.add(value);
+    const result = Array.isArray(value)
+        ? value.map((item) => redactValue(item, depth + 1, seen))
+        : Object.fromEntries(Object.entries(value).map(([k, v]) => [
+            k,
+            redactValue(v, depth + 1, seen),
+        ]));
+    // Allow the same object reached again via a sibling branch (a DAG, not a
+    // cycle) to serialize in full: only nodes on the current path are guarded.
+    seen.delete(value);
+    return result;
+}
+/** @internal — exported only for tests; not part of the public API. */
+export function redactText(text) {
+    if (!text)
+        return text;
+    let redacted = text;
+    if (homeDir)
+        redacted = redacted.split(homeDir).join("<home>");
+    redacted = redacted.replace(URL_USERINFO_PATTERN, "$1<redacted>:<redacted>@");
+    redacted = redacted.replace(URL_USERINFO_BARE_PATTERN, "$1<redacted>@");
+    redacted = redacted.replace(SECRET_INLINE_PATTERN, "$1$2<redacted>");
+    redacted = redacted.replace(BEARER_PATTERN, "$1 <redacted>");
+    return redacted;
+}
+function exceptionForCapture(exc, summary) {
+    if (!summary)
+        return exc;
+    const wrapped = new Error(redactText(summary));
+    // Preserve the original stack so Sentry groups on the real failure site.
+    if (exc instanceof Error && exc.stack)
+        wrapped.stack = exc.stack;
+    return wrapped;
+}
+function commandLabel(cmd) {
+    if (Array.isArray(cmd)) {
+        const parts = cmd.map(String).filter((p) => p.trim());
+        if (parts.length === 0)
+            return "subprocess";
+        if (parts.length >= 3 && parts[0] === "uv" && parts[1] === "pip") {
+            return parts.slice(0, 3).join(" ");
+        }
+        if (parts.length >= 2)
+            return parts.slice(0, 2).join(" ");
+        return parts[0];
+    }
+    const text = String(cmd).trim();
+    return text || "subprocess";
+}
+function failureHeadline(output) {
+    const normalized = output
+        .split("\n")
+        .map(normalizeFailureLine)
+        .filter((line) => line);
+    for (let i = normalized.length - 1; i >= 0; i--) {
+        const line = normalized[i];
+        const lower = line.toLowerCase();
+        if (lower.includes("failed") ||
+            lower.includes("error") ||
+            lower.includes("not found") ||
+            lower.includes("no matching") ||
+            lower.includes("exception")) {
+            return truncateSummaryLine(line);
+        }
+    }
+    if (normalized.length === 0)
+        return "";
+    return truncateSummaryLine(normalized[normalized.length - 1]);
+}
+function normalizeFailureLine(line) {
+    let cleaned = line
+        .trim()
+        .replace(/^[│>]+/, "")
+        .trim();
+    if (cleaned.startsWith("×"))
+        cleaned = cleaned.slice(1).trim();
+    if (cleaned.startsWith("╰─▶"))
+        cleaned = cleaned.slice(3).trim();
+    if (cleaned.toLowerCase().startsWith("error:"))
+        cleaned = cleaned.slice(6).trim();
+    return cleaned;
+}
+function tailText(text) {
+    const trimmed = text.trim();
+    if (trimmed.length <= MAX_OUTPUT_TAIL_CHARS)
+        return trimmed;
+    return trimmed.slice(-MAX_OUTPUT_TAIL_CHARS);
+}
+function truncateSummaryLine(line) {
+    if (line.length <= MAX_SUMMARY_LINE_LENGTH)
+        return line;
+    return line.slice(0, MAX_SUMMARY_LINE_LENGTH - 3) + "...";
+}