The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix: attribute Sentry errors to the loaded source release (#13719)
Devin Foley600e552d7bef
diff --git a/Dockerfile b/Dockerfileindex a3d046c96e..eda927f77a 100644--- a/Dockerfile+++ b/Dockerfile@@ -128,16 +128,17 @@ COPY --from=deps /app /appCOPY . .RUN find packages/paperclip-runner/runner packages/paperclip-runner/protocol -type f -exec touch -d @0 {} + \&& touch -d @0 packages/paperclip-runner/rust-toolchain.toml+# Both the browser bundle and server stamp need the source commit. Declare it+# after the stable dependency layers, before either application build.+ARG PAPERCLIP_BUILD_COMMIT=""RUN pnpm --filter @paperclipai/ui buildRUN pnpm --filter @paperclipai/plugin-sdk build# The server build runs scripts/write-build-stamp.mjs, which stamps the built# commit into dist/build-info.json. The build context has no .git, so the# script reads PAPERCLIP_BUILD_COMMIT instead. Docker exposes an ARG to the-# next RUN as an environment variable, so declare it here — in the build-# stage — before the server build. The production stage below declares the+# next RUN as an environment variable. The production stage below declares the# same ARG again for the runtime fallback; an ARG goes out of scope at the# end of its stage. Empty for local `docker build`, which then writes no stamp.-ARG PAPERCLIP_BUILD_COMMIT=""ENV NODE_OPTIONS=--max-old-space-size=4096RUN pnpm --filter @paperclipai/server buildRUN test -f server/dist/index.js || (echo "ERROR: server build output missing" && exit 1)diff --git a/doc/observability.md b/doc/observability.mdindex f604150e95..501b095e44 100644--- a/doc/observability.md+++ b/doc/observability.md@@ -375,7 +375,23 @@ sends, so an operator can read what the feature does before turning it on.Each Sentry integration name below is verified against the defaultintegration list of `@sentry/[email protected]` and `@sentry/[email protected]`.-**Server attribute this feature sets**+**Release attribution**++The server sets `release` to the full source commit from its build metadata.+An explicit `SENTRY_RELEASE` overrides that default. If neither is available,+the server leaves the release unset.++The browser also sets `release`, using the full `PAPERCLIP_BUILD_COMMIT`+supplied when its bundle is built, or the checkout commit for source and npm+builds. The server reads its packaged build stamp when no deployment marker+is present. Docker passes the same commit to both+application builds. A cached browser bundle keeps its own release after a+server deployment, so its errors are attributed to the code actually loaded.+Browser builds without a valid full commit leave the release unset. The+browser does not read a release from the current server, page URL, or session.+These fields contain build identifiers; they add no tenant or user identity.++**Server identity**- `server_name` — every server event carries the host name of the process.The `@sentry/node` client already sets this value by default when thediff --git a/server/scripts/write-build-stamp.mjs b/server/scripts/write-build-stamp.mjsindex bceb09455f..684246c65f 100644--- a/server/scripts/write-build-stamp.mjs+++ b/server/scripts/write-build-stamp.mjs@@ -5,7 +5,7 @@// report `service.version`, so the value tracks the true built commit.//// The build resolves the commit in two steps:-// 1. `git rev-parse --short HEAD` in the server directory.+// 1. `git rev-parse HEAD` in the server directory.// 2. The `PAPERCLIP_BUILD_COMMIT` environment variable.// A Docker image build excludes `.git`, so the git lookup fails there. The// image build passes the commit in `PAPERCLIP_BUILD_COMMIT` instead, so the@@ -44,14 +44,14 @@ export function resolveBuildCommit(gitCommit, suppliedCommit) {}/**- * Read the short commit SHA with `git rev-parse --short HEAD` in the server+ * Read the full commit SHA with `git rev-parse HEAD` in the server* directory. Return the SHA, or null on any failure.** @returns {string | null}*/function readGitCommit() {try {- const out = execFileSync("git", ["rev-parse", "--short", "HEAD"], {+ const out = execFileSync("git", ["rev-parse", "HEAD"], {cwd: serverDir,stdio: ["ignore", "pipe", "ignore"],})diff --git a/server/src/__tests__/build-commit.test.ts b/server/src/__tests__/build-commit.test.tsindex f76dc8505c..c000bcb642 100644--- a/server/src/__tests__/build-commit.test.ts+++ b/server/src/__tests__/build-commit.test.ts@@ -15,6 +15,28 @@ describe("parseBuildCommit", () => {});describe("readBuildCommit", () => {+ it("reads the built server stamp in npm packages without a deployment marker", () => {+ const commit = "0123456789abcdef0123456789abcdef01234567";+ expect(readBuildCommit({+ environmentCommit: null,+ buildCommitPath: "/app/.paperclip-build-commit",+ buildInfoPath: "/app/server/dist/build-info.json",+ readTextFile: (path) => {+ if (path.endsWith(".paperclip-build-commit")) throw new Error("ENOENT");+ return JSON.stringify({ commit });+ },+ })).toBe(commit);+ });++ it.each(["invalid json", "null", '{"commit":"short"}', '{"commit":42}'])(+ "fails open on an invalid server stamp: %s", (stamp) => {+ expect(readBuildCommit({+ environmentCommit: null,+ readTextFile: () => stamp,+ })).toBeNull();+ },+ );+it("prefers an explicit environment commit", () => {const readTextFile = vi.fn(() => "ffffffffffffffffffffffffffffffffffffffff");diff --git a/server/src/__tests__/sentry.test.ts b/server/src/__tests__/sentry.test.tsindex 9067b96f36..5f34a1ff97 100644--- a/server/src/__tests__/sentry.test.ts+++ b/server/src/__tests__/sentry.test.ts@@ -268,6 +268,13 @@ describe("missing @sentry/node package", () => {it("logs one warning and resolves", async () => {process.env[BACKEND_DSN_ENV] = "https://[email protected]/1";const warn = vi.spyOn(console, "warn").mockImplementation(() => {});+ // Keep this failure-mode test valid when the optional real-SDK tests run.+ vi.doMock("../peer-version-check.js", () => ({+ checkExactPeerVersions: () => ({+ ok: false,+ detail: { missing: ["@sentry/node"], mismatched: [] },+ }),+ }));const { sentryReady } = await importFreshSentry();@@ -537,6 +544,41 @@ describe("buildSentryInitOptions serverName", () => {});});+describe("buildSentryInitOptions release", () => {+ const commit = "0123456789abcdef0123456789abcdef01234567";+ const integrations = {+ httpIntegration: () => ({ name: "Http" }),+ onUnhandledRejectionIntegration: () => ({ name: "OnUnhandledRejection" }),+ };++ beforeEach(() => {+ vi.stubEnv("SENTRY_RELEASE", "");+ vi.doMock("../build-commit.js", () => ({ readBuildCommit: () => commit }));+ });++ afterEach(() => {+ vi.unstubAllEnvs();+ vi.doUnmock("../build-commit.js");+ });++ it("uses the server build commit", async () => {+ const { buildSentryInitOptions } = await importFreshSentry();+ expect(buildSentryInitOptions("test-dsn", integrations).release).toBe(commit);+ });++ it("preserves an operator's explicit release", async () => {+ vi.stubEnv("SENTRY_RELEASE", " custom-release ");+ const { buildSentryInitOptions } = await importFreshSentry();+ expect(buildSentryInitOptions("test-dsn", integrations).release).toBe("custom-release");+ });++ it("leaves an unknown build unattributed", async () => {+ vi.doMock("../build-commit.js", () => ({ readBuildCommit: () => null }));+ const { buildSentryInitOptions } = await importFreshSentry();+ expect(buildSentryInitOptions("test-dsn", integrations).release).toBeUndefined();+ });+});+describe("with @sentry/node mocked", () => {it("initializes the client and shares captureException / shutdownSentry with it", async () => {process.env[DSN_ENV] = "https://[email protected]/1";@@ -644,6 +686,22 @@ describe.skipIf(!sentryPackage)("captured event shape against the real @sentry/nSentry.init(options);}+ it("attaches the actual build commit to an emitted event", async () => {+ const commit = "0123456789abcdef0123456789abcdef01234567";+ vi.stubEnv("PAPERCLIP_BUILD_COMMIT", commit);+ vi.stubEnv("SENTRY_RELEASE", "");+ try {+ let captured: Record<string, unknown> | null = null;+ await initRealSentryForTest((event) => { captured = event; });+ sentryPackage!.captureException(new Error("build attribution check"));+ await sentryPackage!.flush(2000);+ expect(captured).toMatchObject({ release: commit });+ expect(captured).not.toHaveProperty("request");+ } finally {+ vi.unstubAllEnvs();+ }+ });+it("a server event captured after a console.error call carries no console breadcrumb", async () => {const Sentry = sentryPackage!;let captured: Record<string, unknown> | null = null;diff --git a/server/src/__tests__/write-build-stamp.test.ts b/server/src/__tests__/write-build-stamp.test.tsindex eb7d55e63a..108d8254dc 100644--- a/server/src/__tests__/write-build-stamp.test.ts+++ b/server/src/__tests__/write-build-stamp.test.ts@@ -1,7 +1,32 @@import { describe, expect, it } from "vitest";+import { execFileSync } from "node:child_process";+import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";import { resolveBuildCommit } from "../../scripts/write-build-stamp.mjs";+it("packages a full source commit without a Docker build argument", () => {+ const root = realpathSync(mkdtempSync(join(tmpdir(), "paperclip-build-stamp-")));+ try {+ const scriptDir = join(root, "server", "scripts");+ mkdirSync(scriptDir, { recursive: true });+ const script = join(scriptDir, "write-build-stamp.mjs");+ copyFileSync(new URL("../../scripts/write-build-stamp.mjs", import.meta.url), script);+ const git = (...args: string[]) => execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();+ git("init", "--quiet");+ git("-c", "user.name=Test", "-c", "[email protected]", "commit", "--allow-empty", "--no-gpg-sign", "-m", "fixture");+ const env = { ...process.env };+ delete env.PAPERCLIP_BUILD_COMMIT;+ execFileSync(process.execPath, [script], { cwd: root, env, stdio: "pipe" });+ const stamp = JSON.parse(readFileSync(join(root, "server", "dist", "build-info.json"), "utf8"));+ expect(stamp.commit).toBe(git("rev-parse", "HEAD"));+ expect(stamp.commit).toMatch(/^[0-9a-f]{40}$/);+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+});+describe("resolveBuildCommit", () => {it("prefers the git commit over the supplied environment commit", () => {expect(resolveBuildCommit("aaaaaaa", "bbbbbbb")).toBe("aaaaaaa");diff --git a/server/src/build-commit.ts b/server/src/build-commit.tsindex 105c6d590c..7c27a2befd 100644--- a/server/src/build-commit.ts+++ b/server/src/build-commit.ts@@ -7,6 +7,7 @@ const FULL_SHA_RE = /^[0-9a-f]{40}$/i;const DEFAULT_BUILD_COMMIT_PATH = fileURLToPath(new URL("../../.paperclip-build-commit", import.meta.url),);+const DEFAULT_BUILD_INFO_PATH = fileURLToPath(new URL("./build-info.json", import.meta.url));export function parseBuildCommit(value: string | null | undefined): string | null {const commit = value?.trim() ?? "";@@ -17,6 +18,7 @@ export function readBuildCommit(opts: {environmentCommit?: string | null;buildCommitPath?: string;+ buildInfoPath?: string;readTextFile?: ReadTextFile;} = {},): string | null {@@ -27,9 +29,14 @@ export function readBuildCommit();if (environmentCommit) return environmentCommit;+ const readTextFile = opts.readTextFile ?? ((path: string) => readFileSync(path, "utf8"));try {- const readTextFile = opts.readTextFile ?? ((path: string) => readFileSync(path, "utf8"));- return parseBuildCommit(readTextFile(opts.buildCommitPath ?? DEFAULT_BUILD_COMMIT_PATH));+ const markerCommit = parseBuildCommit(readTextFile(opts.buildCommitPath ?? DEFAULT_BUILD_COMMIT_PATH));+ if (markerCommit) return markerCommit;+ } catch { /* The deployment marker is absent in npm packages. */ }+ try {+ const stamp = JSON.parse(readTextFile(opts.buildInfoPath ?? DEFAULT_BUILD_INFO_PATH));+ return typeof stamp?.commit === "string" ? parseBuildCommit(stamp.commit) : null;} catch {return null;}diff --git a/server/src/sentry.ts b/server/src/sentry.tsindex cfe7ecb929..2b8c59423e 100644--- a/server/src/sentry.ts+++ b/server/src/sentry.ts@@ -56,6 +56,7 @@// `instrumentation.ts`.import os from "node:os";+import { readBuildCommit } from "./build-commit.js";import { checkExactPeerVersions } from "./peer-version-check.js";import { resolveSentryDsns } from "./sentry-dsn.js";@@ -200,12 +201,13 @@ export function shutdownSentry(): Promise<void> {*/interface SentryModuleLike {httpIntegration(options: { breadcrumbs: boolean }): { name: string };- onUnhandledRejectionIntegration(options: { mode: string }): { name: string };+ onUnhandledRejectionIntegration(options: { mode: "strict" }): { name: string };}/** The `Sentry.init` options this gate builds. */export interface SentryInitOptions {dsn: string;+ release?: string;skipOpenTelemetrySetup: boolean;tracesSampleRate: number;sendDefaultPii: boolean;@@ -225,6 +227,7 @@ export function buildSentryInitOptions(): SentryInitOptions {return {dsn,+ release: process.env.SENTRY_RELEASE?.trim() || readBuildCommit() || undefined,skipOpenTelemetrySetup: true,tracesSampleRate: 0,sendDefaultPii: false,diff --git a/ui/src/lib/sentry.test.ts b/ui/src/lib/sentry.test.tsindex b2838ebb53..e1612a197e 100644--- a/ui/src/lib/sentry.test.ts+++ b/ui/src/lib/sentry.test.ts@@ -296,6 +296,29 @@ function resolveIntegrations(}describe("buildBrowserSentryInitOptions", () => {+ it("keeps the loaded bundle's release when the server version changes", async () => {+ const commit = "0123456789abcdef0123456789abcdef01234567";+ vi.stubGlobal("__PAPERCLIP_BUILD_COMMIT__", commit);+ vi.stubEnv("PAPERCLIP_BUILD_COMMIT", "abcdef0123456789abcdef0123456789abcdef01");+ try {+ const { buildBrowserSentryInitOptions } = await importFreshSentry();+ expect(buildBrowserSentryInitOptions(DSN).release).toBe(commit);+ } finally {+ vi.unstubAllGlobals();+ vi.unstubAllEnvs();+ }+ });++ it("does not invent a release for an unstamped bundle", async () => {+ vi.stubGlobal("__PAPERCLIP_BUILD_COMMIT__", null);+ try {+ const { buildBrowserSentryInitOptions } = await importFreshSentry();+ expect(buildBrowserSentryInitOptions(DSN).release).toBeUndefined();+ } finally {+ vi.unstubAllGlobals();+ }+ });+it("sets the recorded built-in privacy options", async () => {const { buildBrowserSentryInitOptions } = await importFreshSentry();@@ -367,6 +390,21 @@ describe("captured event shape against the real @sentry/browser SDK", () => {return Sentry;}+ it("attaches the bundle release to an emitted event without page context", async () => {+ const commit = "0123456789abcdef0123456789abcdef01234567";+ vi.stubGlobal("__PAPERCLIP_BUILD_COMMIT__", commit);+ try {+ let captured: Record<string, unknown> | null = null;+ const Sentry = await initRealSentryForTest((event) => { captured = event; });+ Sentry.captureException(new Error("bundle attribution check"));+ await Sentry.flush(2000);+ expect(captured).toMatchObject({ release: commit });+ expect(captured).not.toHaveProperty("request");+ } finally {+ vi.unstubAllGlobals();+ }+ });+it("an event from a page URL that holds a test capability value carries no request URL, no query string, and no referrer", async () => {window.history.pushState({}, "", "/dashboard?token=test-capability-value");Object.defineProperty(document, "referrer", {diff --git a/ui/src/lib/sentry.ts b/ui/src/lib/sentry.tsindex 404f64191e..bb433c5d2f 100644--- a/ui/src/lib/sentry.ts+++ b/ui/src/lib/sentry.ts@@ -155,6 +155,11 @@ export function captureBrowserException(error: unknown): void {export function buildBrowserSentryInitOptions(dsn: string): BrowserSentryInitOptions {return {dsn,+ // Use the loaded bundle's build, even when the server has since deployed.+ release:+ typeof __PAPERCLIP_BUILD_COMMIT__ === "string"+ ? __PAPERCLIP_BUILD_COMMIT__+ : undefined,tracesSampleRate: 0,sendDefaultPii: false,integrations: (defaults) =>diff --git a/ui/src/lib/vite-build-commit.test.ts b/ui/src/lib/vite-build-commit.test.tsnew file mode 100644index 0000000000..ea764732ab--- /dev/null+++ b/ui/src/lib/vite-build-commit.test.ts@@ -0,0 +1,44 @@+import { readFileSync } from "node:fs";+import { fileURLToPath } from "node:url";+import { describe, expect, it, vi } from "vitest";+import { resolveBrowserBuildCommit } from "./vite-build-commit";++describe("browser build attribution", () => {+ const commit = "0123456789abcdef0123456789abcdef01234567";++ it("uses the checkout commit for source and npm builds", () => {+ expect(resolveBrowserBuildCommit(undefined, () => commit)).toBe(commit);+ });++ it("uses a supplied commit without requiring git in Docker", () => {+ const readGitCommit = vi.fn(() => "ffffffffffffffffffffffffffffffffffffffff");+ expect(resolveBrowserBuildCommit(commit, readGitCommit)).toBe(commit);+ expect(readGitCommit).not.toHaveBeenCalled();+ });++ it("leaves builds without git or a supplied commit unattributed", () => {+ expect(resolveBrowserBuildCommit(undefined, () => { throw new Error("no git"); })).toBeNull();+ expect(resolveBrowserBuildCommit(undefined, () => "not-a-commit")).toBeNull();+ });++ it("accepts and normalizes the full source commit supplied by image CI", () => {+ expect(resolveBrowserBuildCommit(" 0123456789ABCDEF0123456789ABCDEF01234567\n"))+ .toBe("0123456789abcdef0123456789abcdef01234567");+ });++ it.each([undefined, "", "main", "0123456", "https://example.invalid/private-build?token=canary"])(+ "omits an unknown or non-commit value: %s", (value) => {+ expect(resolveBrowserBuildCommit(value)).toBeNull();+ },+ );++ it("makes the Docker build commit available before building the browser", () => {+ const dockerfile = readFileSync(fileURLToPath(new URL("../../../Dockerfile", import.meta.url)), "utf8");+ const stage = dockerfile.split("FROM runner-build AS build")[1]?.split("FROM base AS production")[0];+ expect(stage).toBeDefined();+ const arg = stage!.indexOf('ARG PAPERCLIP_BUILD_COMMIT=""');+ const browserBuild = stage!.indexOf("RUN pnpm --filter @paperclipai/ui build");+ expect(arg).toBeGreaterThanOrEqual(0);+ expect(browserBuild).toBeGreaterThan(arg);+ });+});diff --git a/ui/src/lib/vite-build-commit.ts b/ui/src/lib/vite-build-commit.tsnew file mode 100644index 0000000000..b51fdde43c--- /dev/null+++ b/ui/src/lib/vite-build-commit.ts@@ -0,0 +1,31 @@+import { execFileSync } from "node:child_process";++function parseCommit(value: string | undefined): string | null {+ const commit = value?.trim() ?? "";+ return /^[0-9a-f]{40}$/i.test(commit) ? commit.toLowerCase() : null;+}++/** Only a full source commit may enter the public browser bundle. */+export function resolveBrowserBuildCommit(+ value: string | undefined,+ readGitCommit: () => string | undefined = () => undefined,+): string | null {+ const suppliedCommit = parseCommit(value);+ if (suppliedCommit) return suppliedCommit;+ try {+ return parseCommit(readGitCommit());+ } catch {+ return null;+ }+}++export function readBrowserBuildCommit(repositoryDirectory: string): string | null {+ return resolveBrowserBuildCommit(process.env.PAPERCLIP_BUILD_COMMIT, () =>+ execFileSync("git", ["rev-parse", "HEAD"], {+ cwd: repositoryDirectory,+ encoding: "utf8",+ stdio: ["ignore", "pipe", "ignore"],+ timeout: 1000,+ }),+ );+}diff --git a/ui/src/vite-env.d.ts b/ui/src/vite-env.d.tsindex 11f02fe2a0..88b91807f6 100644--- a/ui/src/vite-env.d.ts+++ b/ui/src/vite-env.d.ts@@ -1 +1,3 @@/// <reference types="vite/client" />++declare const __PAPERCLIP_BUILD_COMMIT__: string | null;diff --git a/ui/vite.config.ts b/ui/vite.config.tsindex 3ac9f91485..2ecc84ec77 100644--- a/ui/vite.config.ts+++ b/ui/vite.config.ts@@ -5,10 +5,16 @@ import tailwindcss from "@tailwindcss/vite";import { createUiDevWatchOptions } from "./src/lib/vite-watch";import { createApiProxy } from "./src/lib/vite-api-proxy";import { serviceWorkerBuildIdPlugin } from "./src/lib/vite-sw-build-id";+import { readBrowserBuildCommit } from "./src/lib/vite-build-commit";const apiProxy = createApiProxy();export default defineConfig(({ mode }) => ({+ define: {+ __PAPERCLIP_BUILD_COMMIT__: JSON.stringify(+ readBrowserBuildCommit(__dirname),+ ),+ },plugins: [react(), tailwindcss(), serviceWorkerBuildIdPlugin()],build: {minify: "esbuild",