feat: add sentry config

.changeset/trueforge-sentry-p1.md

@@ -0,0 +1,6 @@
+---
+"@truefoundry/trueforge": minor
+"@truefoundry/trueforge-core": patch
+---
+
+Add Sentry for P1 critical flows: TrueFoundry auth-server or SENTRY_DSN init, and agent-team captures for controller, dual-write, SFY hard failures, missing external_id, and sandbox init.

packages/trueforge-core/src/core/sandbox/Sandbox.ts

@@ -101,6 +101,7 @@ export interface SandboxOptions {
   mcpConnectTimeoutMs: number;
   tracing: AgentTracing;
   logger: Logger;
+  onInitFailure?: ((error: unknown) => void) | undefined;
 }
 
 export const SANDBOX_EXEC_TOOL_NAME = 'exec';
@@ -210,6 +211,7 @@ export class Sandbox extends LocalToolMCP {
   private readonly logger: Logger;
   // Pre-resolved credential-store file content (null = clear / no git auth).
   private readonly resolvedGitCredentialsContent: string | null;
+  private readonly onInitFailure: ((error: unknown) => void) | undefined;
   private codeModeDispatcher: CodeModeDispatcher | undefined;
   private codeModeTransport: CodeModeTransport | undefined;
   /** Cached from transport.getClientInstall after sandbox init (when Code Mode is configured). */
@@ -234,6 +236,7 @@ export class Sandbox extends LocalToolMCP {
     this.requestTimeoutSeconds = Math.ceil(mcpBoundTimeoutMs / 1000) + NATS_REQUEST_TIMEOUT_BUFFER_SECONDS;
     this.logger = options.logger.child({ module: 'Sandbox' });
     this.resolvedGitCredentialsContent = options.resolvedGitCredentialsContent ?? null;
+    this.onInitFailure = options.onInitFailure;
 
     if (this.existingSandboxId) {
       this.existingSandboxInfo = { sandbox_id: this.existingSandboxId };
@@ -525,6 +528,7 @@ export class Sandbox extends LocalToolMCP {
       ({ sandboxInfo, sandboxCreated } = await this.ensureReadySandbox());
     } catch (e) {
       this.logger.error('Sandbox initialization failed', extractErrorLogFields(e));
+      this.onInitFailure?.(e);
       const message = e instanceof Error ? e.message : 'Sandbox initialization failed';
       const fallback = this.existingSandboxInfo;
       return toolResultResponse({

packages/trueforge/.env.example

@@ -34,6 +34,15 @@ PORT=8790
 # TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS=10000
 ## Max ms for ServiceFoundry agent create/update/delete calls. Default 3000.
 # TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_AGENT_TIMEOUT_MS=3000
+## Auth server for Sentry DSN lookup when SENTRY_ENABLED=true in TrueFoundry mode.
+# TRUEFOUNDRY_AUTH_SERVER_URL=https://auth.truefoundry.com
+## Optional tenantName query param for the auth-server Sentry DSN lookup.
+# TRUEFOUNDRY_TENANT_NAME=
+
+## Sentry error reporting (off by default). No-op when NODE_ENV is development/test/local.
+# SENTRY_ENABLED=false
+## Required when SENTRY_ENABLED=true and not in TrueFoundry mode.
+# SENTRY_DSN=
 
 ## Mutual TLS for this process's HTTPS listener and controller→server. Off by default (plain HTTP).
 ## When true, serves HTTPS with client-cert enforcement (except /healthz) and the controller

packages/trueforge/package.json

@@ -66,6 +66,7 @@
     "@hono/swagger-ui": "^0.2.2",
     "@hono/zod-openapi": "^1.6.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "@sentry/node": "^10.74.0",
     "@truefoundry/trueforge-core": "workspace:*",
     "@truefoundry/trueforge-sdk": "workspace:*",
     "better-sqlite3": "^13.0.3",

packages/trueforge/src/config.ts

@@ -545,6 +545,8 @@ export interface SharedServerConfiguration {
    * `TRUEFORGE_MTLS_ENABLED` is true. Env: `TRUEFORGE_MTLS_CERTS_DIR`. Default `/etc/tls`.
    */
   TRUEFORGE_MTLS_CERTS_DIR: string;
+  SENTRY_ENABLED: boolean;
+  SENTRY_DSN: string | undefined;
 }
 
 export type StandaloneServerConfiguration = SharedServerConfiguration & {
@@ -654,6 +656,8 @@ export type DistributedServerConfiguration = SharedServerConfiguration & {
    * Env: `TRUEFOUNDRY_SANDBOX_SETTINGS`.
    */
   TRUEFOUNDRY_SANDBOX_SETTINGS: string | undefined;
+  TRUEFOUNDRY_AUTH_SERVER_URL: string | undefined;
+  TRUEFOUNDRY_TENANT_NAME: string | undefined;
 };
 
 export type ServerConfiguration = StandaloneServerConfiguration | DistributedServerConfiguration;
@@ -768,6 +772,12 @@ const shared: SharedServerConfiguration = {
     defaultValue: false,
   }),
   TRUEFORGE_MTLS_CERTS_DIR: getEnv('TRUEFORGE_MTLS_CERTS_DIR', { defaultValue: '/etc/tls' }) ?? '/etc/tls',
+  SENTRY_ENABLED: parseBoolean({
+    envKey: 'SENTRY_ENABLED',
+    raw: getEnv('SENTRY_ENABLED'),
+    defaultValue: false,
+  }),
+  SENTRY_DSN: getEnv('SENTRY_DSN', { required: false }),
 };
 
 const configuration: ServerConfiguration = standalone
@@ -829,6 +839,8 @@ const configuration: ServerConfiguration = standalone
       TRUEFOUNDRY_SANDBOX_API_KEY: getEnv('TRUEFOUNDRY_SANDBOX_API_KEY', { required: false }),
       TRUEFOUNDRY_SANDBOX_SERVER_URL: getEnv('TRUEFOUNDRY_SANDBOX_SERVER_URL', { required: false }),
       TRUEFOUNDRY_SANDBOX_SETTINGS: getEnv('TRUEFOUNDRY_SANDBOX_SETTINGS', { required: false }),
+      TRUEFOUNDRY_AUTH_SERVER_URL: getEnv('TRUEFOUNDRY_AUTH_SERVER_URL', { required: false }),
+      TRUEFOUNDRY_TENANT_NAME: getEnv('TRUEFOUNDRY_TENANT_NAME', { required: false }),
     };
 
 export function isOidcConfigured(

packages/trueforge/src/controller-main.ts

@@ -18,6 +18,7 @@ import { createDb } from './db/postgres/client';
 import { PostgresScheduleStore } from './db/postgres/schedule-store/PostgresScheduleStore';
 import { createControllerLogger } from './logger';
 import { PACKAGE_VERSION } from './packageVersion';
+import { captureCriticalException, exitAfterFlushSentry, initSentry } from './sentry';
 
 try {
   const logger = createControllerLogger({
@@ -26,6 +27,8 @@ try {
     version: PACKAGE_VERSION,
   });
 
+  await initSentry(configuration, logger, { tags: { component: 'controller' } });
+
   if (configuration.STANDALONE) {
     // Not an error: in standalone the server process owns the controller in-process, so a
     // dedicated controller has nothing to do. Exit cleanly (e.g. `pnpm standalone:dev` also
@@ -55,5 +58,6 @@ try {
   });
 } catch (error) {
   console.error('Failed to start controller:', error instanceof Error ? error.message : error);
-  process.exit(1);
+  captureCriticalException(error, { tags: { module: 'controller', operation: 'boot' } });
+  await exitAfterFlushSentry(1);
 }

packages/trueforge/src/controller.ts

@@ -3,6 +3,7 @@ import { Controller } from './controller/Controller';
 import { scheduleDispatchLoop } from './controller/scheduleDispatch';
 import type { IScheduleStore } from './db/scheduleStore';
 import type { WithTransaction } from './db/transaction';
+import { captureCriticalException, exitAfterFlushSentry } from './sentry';
 
 /**
  * Controller whose schedule loop hands runs to the server over HTTP
@@ -52,7 +53,11 @@ export function runController<TTransaction>(params: {
     // Passes only hold short transactions, so the deadline should never elapse.
     setTimeout(() => {
       logger.warn(`Controller drain timed out after ${String(gracefulTimeoutSeconds)}s, exiting`);
-      process.exit(1);
+      captureCriticalException(new Error('Controller drain timed out'), {
+        tags: { module: 'controller', operation: 'drain' },
+        extra: { gracefulTimeoutSeconds },
+      });
+      void exitAfterFlushSentry(1);
     }, gracefulTimeoutSeconds * 1000).unref();
 
     await controller.stop();

packages/trueforge/src/controller/Controller.ts

@@ -9,6 +9,7 @@
  * process. Loops are written assuming this.
  */
 import type { Logger } from 'winston';
+import { captureCriticalException } from '../sentry';
 
 /** Reason passed to {@link AbortController.abort} when {@link Controller.stop} runs. */
 export const CONTROLLER_STOPPED = 'controller-stopped';
@@ -120,6 +121,10 @@ export class Controller {
           return;
         }
         this.#logger.error('Control loop pass failed', { loop: loop.name, error });
+        captureCriticalException(error, {
+          tags: { module: 'controller', operation: 'tick' },
+          extra: { loop: loop.name },
+        });
       }
     })();
 

packages/trueforge/src/controller/scheduleDispatch.ts

@@ -13,6 +13,7 @@ import type { WithTransaction } from '../db/transaction';
 import { createTlsFetch, normalizeTlsUrl } from '../http/tls';
 import { nextTriggerAfter } from '../runtime/cron';
 import { InvalidCronError, type ScheduleRunStatus } from '../schemas/schedule';
+import { captureCriticalException } from '../sentry';
 import type { ControlLoop } from './Controller';
 
 /**
@@ -303,6 +304,10 @@ export async function dispatchScheduledRuns<TTransaction>(params: {
           run_id: run.id,
           error,
         });
+        captureCriticalException(error, {
+          tags: { module: 'scheduleDispatch', operation: 'handoff' },
+          extra: { schedule_id: schedule.id, run_id: run.id },
+        });
         await finishScheduledRun({
           store,
           run,
@@ -329,6 +334,10 @@ export async function dispatchScheduledRuns<TTransaction>(params: {
         run_id: run.id,
         error,
       });
+      captureCriticalException(error, {
+        tags: { module: 'scheduleDispatch', operation: 'processRun' },
+        extra: { schedule_id: run.schedule_id, run_id: run.id },
+      });
     }
   }
 

packages/trueforge/src/main.ts

@@ -86,6 +86,7 @@ import type { IOAuthTokenStore } from './mcp/auth/types';
 import { PACKAGE_VERSION } from './packageVersion';
 import { ActiveTurnRegistry } from './runtime/activeTurns';
 import { EventSubscriptionRegistry } from './runtime/event-subscription';
+import { captureCriticalException, exitAfterFlushSentry, initSentry } from './sentry';
 import { printStandaloneStartupBanner } from './startupBanner';
 import {
   parsePerServerMcpHeaders,
@@ -588,6 +589,8 @@ try {
     version: PACKAGE_VERSION,
   });
 
+  await initSentry(configuration, logger, { tags: { component: 'server' } });
+
   if (configuration.STANDALONE) {
     printStandaloneStartupBanner({ version: PACKAGE_VERSION, color: shouldColorize() });
     await prepareCodeModeSocketParent({ path: configuration.CODE_MODE_SOCKET_PARENT, logger });
@@ -686,7 +689,8 @@ try {
 
   server.on('error', (error: unknown) => {
     console.error('Failed to start server:', error instanceof Error ? error.message : error);
-    process.exit(1);
+    captureCriticalException(error, { tags: { module: 'main', operation: 'listen' } });
+    void exitAfterFlushSentry(1);
   });
 
   // Graceful drain is the safe default for built and direct execution.
@@ -703,7 +707,11 @@ try {
       // Arm at the start of each shutdown; unref so this timer alone cannot keep the process alive.
       setTimeout(() => {
         logger.warn(`Drain timed out after ${String(configuration.GRACEFUL_TIMEOUT_SECONDS)}s, exiting`);
-        process.exit(1);
+        captureCriticalException(new Error('Server drain timed out'), {
+          tags: { module: 'main', operation: 'drain' },
+          extra: { gracefulTimeoutSeconds: configuration.GRACEFUL_TIMEOUT_SECONDS },
+        });
+        void exitAfterFlushSentry(1);
       }, configuration.GRACEFUL_TIMEOUT_SECONDS * 1000).unref();
 
       const closed = new Promise<void>(resolve => {
@@ -747,5 +755,6 @@ try {
   }
 } catch (error) {
   console.error('Failed to start server:', error instanceof Error ? error.message : error);
-  process.exit(1);
+  captureCriticalException(error, { tags: { module: 'main', operation: 'startup' } });
+  await exitAfterFlushSentry(1);
 }

packages/trueforge/src/runtime/sessionResources.ts

@@ -22,6 +22,7 @@ import { LocalSandboxProvider } from '../sandbox/local/provider/LocalSandboxProv
 import { getCachedLocalSandboxSupport, isLocalSandboxFallbackEnabled } from '../sandbox/localRuntime';
 import { toSandboxProviderFromRecord } from '../sandbox/providerUtils';
 import type { ReasoningEffort } from '../schemas/modelProvider';
+import { captureCriticalException } from '../sentry';
 
 export interface McpConnection {
   url: string;
@@ -244,6 +245,11 @@ export function buildTurnSandbox(input: {
     skillMounter: new SkillMounter({ skills: input.skills ?? [] }),
     tracing: input.tracing,
     logger: input.logger,
+    onInitFailure: error => {
+      captureCriticalException(error, {
+        tags: { module: 'sandbox', operation: 'init' },
+      });
+    },
   });
 }
 

packages/trueforge/src/sentry/captureCriticalException.ts

@@ -0,0 +1,23 @@
+import * as Sentry from '@sentry/node';
+import { isTrueFoundryModeEnabled } from '../config';
+
+export function captureCriticalException(
+  err: unknown,
+  options?: { tags?: Record<string, string>; extra?: Record<string, unknown> },
+): void {
+  Sentry.withScope(scope => {
+    scope.setTags({
+      ...(isTrueFoundryModeEnabled()
+        ? {
+            priority: 'p1',
+            team: 'agent-team',
+          }
+        : {}),
+      ...options?.tags,
+    });
+    if (options?.extra) {
+      scope.setExtras(options.extra);
+    }
+    Sentry.captureException(err);
+  });
+}

packages/trueforge/src/sentry/index.ts

@@ -0,0 +1,15 @@
+import * as Sentry from '@sentry/node';
+
+export { captureCriticalException } from './captureCriticalException';
+export { initSentry, type InitSentryOptions } from './initSentry';
+
+export const SENTRY_FLUSH_TIMEOUT_MS = 2000;
+
+export async function flushSentry(timeoutMs: number = SENTRY_FLUSH_TIMEOUT_MS): Promise<void> {
+  await Sentry.flush(timeoutMs);
+}
+
+export async function exitAfterFlushSentry(exitCode: number): Promise<never> {
+  await flushSentry();
+  process.exit(exitCode);
+}

packages/trueforge/src/sentry/initSentry.ts

@@ -0,0 +1,68 @@
+import * as Sentry from '@sentry/node';
+import type { Logger } from 'winston';
+
+import { isTrueFoundryModeEnabled, type ServerConfiguration } from '../config';
+import { PACKAGE_VERSION } from '../packageVersion';
+import { initTrueFoundrySentry } from '../truefoundry/initTrueFoundrySentry';
+
+function isLocalLikeEnv(nodeEnv: string | undefined): boolean {
+  return nodeEnv === 'development' || nodeEnv === 'test' || nodeEnv === 'local';
+}
+
+export interface InitSentryOptions {
+  tags?: Record<string, string>;
+}
+
+export async function initSentry(
+  config: ServerConfiguration,
+  logger: Pick<Logger, 'info' | 'error'>,
+  options?: InitSentryOptions,
+): Promise<void> {
+  if (!config.SENTRY_ENABLED || isLocalLikeEnv(config.NODE_ENV)) {
+    logger.info('Sentry is not enabled (SENTRY_ENABLED=false or local-like NODE_ENV)');
+    return;
+  }
+
+  if (isTrueFoundryModeEnabled(config)) {
+    const authServerUrl = config.TRUEFOUNDRY_AUTH_SERVER_URL;
+    const apiKey = config.TRUEFOUNDRY_API_KEY;
+    if (authServerUrl === undefined || authServerUrl.trim() === '') {
+      logger.error('TRUEFOUNDRY_AUTH_SERVER_URL is required when SENTRY_ENABLED in TrueFoundry mode');
+      return;
+    }
+    if (apiKey === undefined || apiKey.trim() === '') {
+      logger.error('TRUEFOUNDRY_API_KEY is required when SENTRY_ENABLED in TrueFoundry mode');
+      return;
+    }
+    await initTrueFoundrySentry({
+      config: {
+        TRUEFOUNDRY_AUTH_SERVER_URL: authServerUrl,
+        TRUEFOUNDRY_API_KEY: apiKey,
+        TRUEFOUNDRY_TENANT_NAME: config.TRUEFOUNDRY_TENANT_NAME,
+        TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS: config.TRUEFOUNDRY_SERVICEFOUNDRY_HTTP_TIMEOUT_MS,
+      },
+      logger,
+      version: PACKAGE_VERSION,
+      tags: options?.tags,
+    });
+    return;
+  }
+
+  const dsn = config.SENTRY_DSN;
+  if (dsn === undefined || dsn.trim() === '') {
+    logger.error('SENTRY_DSN is required when SENTRY_ENABLED outside TrueFoundry mode');
+    return;
+  }
+  Sentry.init({
+    dsn,
+    includeLocalVariables: false,
+    integrations: [],
+  });
+  Sentry.getGlobalScope().setTag('TRUEFORGE_VERSION', PACKAGE_VERSION);
+  if (options?.tags) {
+    for (const [key, value] of Object.entries(options.tags)) {
+      Sentry.getGlobalScope().setTag(key, value);
+    }
+  }
+  logger.info('Sentry initialised');
+}