@vellumai/assistant 0.3.20 → 0.3.21

package/src/config/mcp-schema.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+const McpStdioTransportSchema = z.object({
+  type: z.literal('stdio'),
+  command: z.string({ error: 'mcp transport command must be a string' }),
+  args: z.array(z.string()).default([]),
+  env: z.record(z.string(), z.string()).optional(),
+});
+
+const McpSseTransportSchema = z.object({
+  type: z.literal('sse'),
+  url: z.string({ error: 'mcp transport url must be a string' }),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+const McpStreamableHttpTransportSchema = z.object({
+  type: z.literal('streamable-http'),
+  url: z.string({ error: 'mcp transport url must be a string' }),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+export const McpTransportSchema = z.discriminatedUnion('type', [
+  McpStdioTransportSchema,
+  McpSseTransportSchema,
+  McpStreamableHttpTransportSchema,
+]);
+
+export const McpServerConfigSchema = z.object({
+  transport: McpTransportSchema,
+  enabled: z.boolean({ error: 'mcp server enabled must be a boolean' }).default(true),
+  defaultRiskLevel: z.enum(['low', 'medium', 'high'], {
+    error: 'mcp server defaultRiskLevel must be one of: low, medium, high',
+  }).default('high'),
+  maxTools: z.number({ error: 'mcp server maxTools must be a number' }).int().positive().default(20),
+  allowedTools: z.array(z.string()).optional(),
+  blockedTools: z.array(z.string()).optional(),
+});
+
+export const McpConfigSchema = z.object({
+  servers: z.record(z.string(), McpServerConfigSchema).default({} as any),
+  globalMaxTools: z.number({ error: 'mcp globalMaxTools must be a number' }).int().positive().default(50),
+});
+
+export type McpTransport = z.infer<typeof McpTransportSchema>;
+export type McpServerConfig = z.infer<typeof McpServerConfigSchema>;
+export type McpConfig = z.infer<typeof McpConfigSchema>;

package/src/config/schema.ts

@@ -114,6 +114,16 @@ export type {
 export {
   SandboxConfigSchema,
 } from './sandbox-schema.js';
+export type {
+  McpConfig,
+  McpServerConfig,
+  McpTransport,
+} from './mcp-schema.js';
+export {
+  McpConfigSchema,
+  McpServerConfigSchema,
+  McpTransportSchema,
+} from './mcp-schema.js';
 export type {
   RemotePolicyConfig,
   RemoteProviderConfig,
@@ -152,6 +162,7 @@ import {
   TimeoutConfigSchema,
   UiConfigSchema,
 } from './core-schema.js';
+import { McpConfigSchema } from './mcp-schema.js';
 import { MemoryConfigSchema } from './memory-schema.js';
 import { NotificationsConfigSchema } from './notifications-schema.js';
 import { SandboxConfigSchema } from './sandbox-schema.js';
@@ -213,6 +224,7 @@ export const AssistantConfigSchema = z.object({
     .default([]),
   heartbeat: HeartbeatConfigSchema.default({} as any),
   swarm: SwarmConfigSchema.default({} as any),
+  mcp: McpConfigSchema.default({} as any),
   skills: SkillsConfigSchema.default({} as any),
   workspaceGit: WorkspaceGitConfigSchema.default({} as any),
   calls: CallsConfigSchema.default({} as any),

package/src/config/vellum-skills/telegram-setup/SKILL.md

@@ -12,8 +12,9 @@ You are helping your user connect a Telegram bot to the Vellum Assistant gateway
 
 Before beginning setup, verify these conditions are met:
 
-1. **Gateway is running:** Run `curl -sf http://localhost:7830/healthz` — it should return OK. If it fails, tell the user to start the daemon with `vellum daemon start` and wait for it to become healthy before continuing.
+1. **Gateway API base URL is set and reachable:** Use the configured gateway URL in `GATEWAY_BASE_URL` (from Settings "Local Gateway Target"), then run `curl -sf "$GATEWAY_BASE_URL/healthz"` — it should return gateway health JSON (for example `{"status":"ok"}`). If it fails, tell the user to start the daemon with `vellum daemon start` and wait for it to become healthy before continuing.
 2. **Public ingress URL is configured.** The gateway webhook URL is derived from `${ingress.publicBaseUrl}/webhooks/telegram`. If the ingress URL is not configured, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the URL before continuing.
+3. **Use gateway control-plane routes only.** Telegram setup/config actions in this skill must call gateway endpoints under `/v1/integrations/telegram/*` — never call the daemon runtime port directly.
 
 ## What You Need
 
@@ -36,7 +37,7 @@ The token is collected securely via a system-level prompt and is never exposed i
 After the token is collected, call the composite setup endpoint which validates the token, stores credentials, and registers bot commands in a single request:
 
 ```bash
-curl -sf -X POST http://localhost:7830/v1/integrations/telegram/setup \
+curl -sf -X POST "$GATEWAY_BASE_URL/v1/integrations/telegram/setup" \
   -H "Authorization: Bearer $(cat ~/.vellum/http-token)" \
   -H "Content-Type: application/json" \
   -d '{}'
@@ -97,7 +98,7 @@ If routing is misconfigured, inbound Telegram messages will be rejected and the
 Before reporting success, confirm the guardian binding was actually created. Check the guardian binding status:
 
 ```bash
-curl -sf http://localhost:7830/v1/integrations/guardian/status?channel=telegram \
+curl -sf "$GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" \
   -H "Authorization: Bearer $(cat ~/.vellum/http-token)"
 ```
 
@@ -116,7 +117,7 @@ Summarize what was done:
 - Guardian identity: {verified | not configured}
 - Guardian verification status: {verified via outbound flow | skipped}
 - Routing configuration validated
-- To re-check guardian status later, use: `curl -sf http://localhost:7830/v1/integrations/guardian/status?channel=telegram -H "Authorization: Bearer $(cat ~/.vellum/http-token)"`
+- To re-check guardian status later, use: `curl -sf "$GATEWAY_BASE_URL/v1/integrations/guardian/status?channel=telegram" -H "Authorization: Bearer $(cat ~/.vellum/http-token)"`
 
 The gateway automatically detects credentials from the vault, reconciles the Telegram webhook registration, and begins accepting Telegram webhooks shortly. In single-assistant mode, routing is automatically configured — no manual environment variable configuration or webhook registration is needed. If the webhook secret changes later, the gateway's credential watcher will automatically re-register the webhook. If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
 

package/src/config/vellum-skills/trusted-contacts/SKILL.md

@@ -10,6 +10,7 @@ You are helping your user manage trusted contacts and invite links for the Vellu
 ## Prerequisites
 
 - The gateway API is available at `http://localhost:7830` (or the configured gateway port).
+- Use gateway control-plane routes only: this skill calls `/v1/ingress/*` and `/v1/integrations/telegram/config` on the gateway, never the daemon runtime port directly.
 - The bearer token is stored at `~/.vellum/http-token`. Read it with: `TOKEN=$(cat ~/.vellum/http-token)`.
 
 ## Concepts

package/src/daemon/lifecycle.ts

@@ -54,6 +54,7 @@ import { createGuardianActionCopyGenerator, createGuardianFollowUpConversationGe
 import { initPairingHandlers } from './handlers/pairing.js';
 import { installCliLaunchers } from './install-cli-launchers.js';
 import type { ServerMessage } from './ipc-protocol.js';
+import { getMcpServerManager } from '../mcp/manager.js';
 import { initializeProvidersAndTools, registerMessagingProviders,registerWatcherProviders } from './providers-setup.js';
 import { seedInterfaceFiles } from './seed-files.js';
 import { DaemonServer } from './server.js';
@@ -398,6 +399,12 @@ export async function runDaemon(): Promise<void> {
     server.setHeartbeatService(heartbeat);
     log.info({ enabled: heartbeatConfig.enabled, intervalMs: heartbeatConfig.intervalMs }, 'Heartbeat service configured');
 
+    // Retrieve the MCP manager if MCP servers were configured.
+    // The manager is a singleton created during initializeProvidersAndTools().
+    const mcpManager = config.mcp?.servers && Object.keys(config.mcp.servers).length > 0
+      ? getMcpServerManager()
+      : null;
+
     installShutdownHandlers({
       server,
       workspaceHeartbeat,
@@ -407,6 +414,7 @@ export async function runDaemon(): Promise<void> {
       scheduler,
       memoryWorker,
       qdrantManager,
+      mcpManager,
       cleanupPidFile,
     });
   } catch (err) {

package/src/daemon/providers-setup.ts

@@ -1,4 +1,5 @@
 import type { AssistantConfig } from '../config/types.js';
+import { getMcpServerManager } from '../mcp/manager.js';
 import { gmailMessagingProvider } from '../messaging/providers/gmail/adapter.js';
 import { slackProvider as slackMessagingProvider } from '../messaging/providers/slack/adapter.js';
 import { smsMessagingProvider } from '../messaging/providers/sms/adapter.js';
@@ -6,7 +7,8 @@ import { telegramBotMessagingProvider } from '../messaging/providers/telegram-bo
 import { whatsappMessagingProvider } from '../messaging/providers/whatsapp/adapter.js';
 import { registerMessagingProvider } from '../messaging/registry.js';
 import { initializeProviders } from '../providers/registry.js';
-import { initializeTools } from '../tools/registry.js';
+import { createMcpToolsFromServer } from '../tools/mcp/mcp-tool-factory.js';
+import { initializeTools, registerMcpTools } from '../tools/registry.js';
 import { getLogger } from '../util/logger.js';
 import { initWatcherEngine } from '../watcher/engine.js';
 import { registerWatcherProvider } from '../watcher/provider-registry.js';
@@ -19,9 +21,32 @@ import { slackProvider as slackWatcherProvider } from '../watcher/providers/slac
 const log = getLogger('lifecycle');
 
 export async function initializeProvidersAndTools(config: AssistantConfig): Promise<void> {
+  console.log('[Daemon] Initializing providers and tools...');
   log.info('Daemon startup: initializing providers and tools');
   initializeProviders(config);
+  console.log('[Daemon] Providers initialized');
   await initializeTools();
+  console.log('[Daemon] Tools initialized');
+
+  // Start MCP servers and register their tools
+  if (config.mcp?.servers && Object.keys(config.mcp.servers).length > 0) {
+    console.log('[MCP] Initializing MCP servers:', Object.keys(config.mcp.servers).join(', '));
+    const manager = getMcpServerManager();
+    try {
+      const serverToolInfos = await manager.start(config.mcp);
+      for (const { serverId, serverConfig, tools } of serverToolInfos) {
+        console.log(`[MCP] Server "${serverId}" connected — discovered ${tools.length} tools:`, tools.map(t => t.name).join(', '));
+        const mcpTools = createMcpToolsFromServer(tools, serverId, serverConfig, manager);
+        registerMcpTools(mcpTools);
+        console.log(`[MCP] Registered ${mcpTools.length} tools from "${serverId}":`, mcpTools.map(t => t.name).join(', '));
+      }
+    } catch (err) {
+      console.error('[MCP] Server initialization failed:', err);
+      log.error({ err }, 'MCP server initialization failed — continuing without MCP tools');
+    }
+  }
+
+  console.log('[Daemon] Providers and tools initialization complete');
   log.info('Daemon startup: providers and tools initialized');
 }
 

package/src/daemon/shutdown-handlers.ts

@@ -3,6 +3,7 @@ import * as Sentry from '@sentry/node';
 import type { HeartbeatService } from '../heartbeat/heartbeat-service.js';
 import type { HookManager } from '../hooks/manager.js';
 import { getSqlite, resetDb } from '../memory/db.js';
+import type { McpServerManager } from '../mcp/manager.js';
 import type { QdrantManager } from '../memory/qdrant-manager.js';
 import type { RuntimeHttpServer } from '../runtime/http-server.js';
 import { browserManager } from '../tools/browser/browser-manager.js';
@@ -22,6 +23,7 @@ export interface ShutdownDeps {
   scheduler: { stop(): void };
   memoryWorker: { stop(): void };
   qdrantManager: QdrantManager;
+  mcpManager: McpServerManager | null;
   cleanupPidFile: () => void;
 }
 
@@ -86,6 +88,15 @@ export function installShutdownHandlers(deps: ShutdownDeps): void {
     await browserManager.closeAllPages();
     deps.scheduler.stop();
     deps.memoryWorker.stop();
+
+    if (deps.mcpManager) {
+      try {
+        await deps.mcpManager.stop();
+      } catch (err) {
+        log.warn({ err }, 'MCP server manager shutdown failed (non-fatal)');
+      }
+    }
+
     await deps.qdrantManager.stop();
 
     // Checkpoint WAL and close SQLite so no writes are lost on exit.

package/src/index.ts

@@ -26,6 +26,7 @@ import {
 import { registerEmailCommand } from './cli/email.js';
 import { registerInfluencerCommand } from './cli/influencer.js';
 import { registerMapCommand } from './cli/map.js';
+import { registerMcpCommand } from './cli/mcp.js';
 import { registerSequenceCommand } from './cli/sequence.js';
 import { registerTwitterCommand } from './cli/twitter.js';
 import { registerHooksCommand } from './hooks/cli.js';
@@ -48,6 +49,7 @@ registerMemoryCommand(program);
 registerAuditCommand(program);
 registerDoctorCommand(program);
 registerHooksCommand(program);
+registerMcpCommand(program);
 registerEmailCommand(program);
 registerAmazonCommand(program);
 registerCompletionsCommand(program);

package/src/mcp/client.ts

@@ -0,0 +1,152 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+import type { McpTransport } from '../config/mcp-schema.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('mcp-client');
+
+const CONNECT_TIMEOUT_MS = 30_000;
+
+export interface McpToolInfo {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface McpCallResult {
+  content: string;
+  isError: boolean;
+}
+
+export class McpClient {
+  readonly serverId: string;
+  private client: Client;
+  private transport: StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport | null = null;
+  private connected = false;
+
+  constructor(serverId: string) {
+    this.serverId = serverId;
+    this.client = new Client({
+      name: 'vellum-assistant',
+      version: '1.0.0',
+    });
+  }
+
+  async connect(transportConfig: McpTransport): Promise<void> {
+    if (this.connected) return;
+
+    console.log(`[MCP] Connecting to server "${this.serverId}"...`);
+    this.transport = this.createTransport(transportConfig);
+    try {
+      await Promise.race([
+        this.client.connect(this.transport),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error(`MCP server "${this.serverId}" connection timed out after ${CONNECT_TIMEOUT_MS}ms`)), CONNECT_TIMEOUT_MS),
+        ),
+      ]);
+    } catch (err) {
+      // Clean up the transport on failure (e.g., kill spawned stdio process)
+      try { await this.client.close(); } catch { /* ignore cleanup errors */ }
+      this.transport = undefined;
+      throw err;
+    }
+    this.connected = true;
+    console.log(`[MCP] Server "${this.serverId}" connected successfully`);
+    log.info({ serverId: this.serverId }, 'MCP client connected');
+  }
+
+  async listTools(): Promise<McpToolInfo[]> {
+    if (!this.connected) {
+      throw new Error(`MCP client "${this.serverId}" is not connected`);
+    }
+
+    const result = await Promise.race([
+      this.client.listTools(),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`MCP server "${this.serverId}" listTools timed out after ${CONNECT_TIMEOUT_MS}ms`)), CONNECT_TIMEOUT_MS),
+      ),
+    ]);
+    return result.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description ?? '',
+      inputSchema: tool.inputSchema as Record<string, unknown>,
+    }));
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<McpCallResult> {
+    if (!this.connected) {
+      throw new Error(`MCP client "${this.serverId}" is not connected`);
+    }
+
+    const result = await this.client.callTool({ name, arguments: args });
+    const isError = result.isError === true;
+
+    // Handle structuredContent if present
+    if (result.structuredContent !== undefined && result.structuredContent !== null) {
+      return {
+        content: JSON.stringify(result.structuredContent),
+        isError,
+      };
+    }
+
+    // Concatenate all content blocks into a single string
+    const textParts: string[] = [];
+    if (Array.isArray(result.content)) {
+      for (const block of result.content) {
+        if (typeof block === 'object' && block !== null && 'type' in block) {
+          if (block.type === 'text' && 'text' in block) {
+            textParts.push(String(block.text));
+          } else if (block.type === 'resource' && 'resource' in block) {
+            const resource = block.resource as Record<string, unknown>;
+            textParts.push(typeof resource.text === 'string' ? resource.text : JSON.stringify(resource));
+          } else {
+            // For other content types (image, etc.), include type and any available data
+            textParts.push(`[${block.type} content: ${JSON.stringify(block)}]`);
+          }
+        }
+      }
+    }
+
+    return {
+      content: textParts.join('\n') || (isError ? 'Tool execution failed' : 'Tool executed successfully'),
+      isError,
+    };
+  }
+
+  async disconnect(): Promise<void> {
+    if (!this.connected) return;
+
+    try {
+      await this.client.close();
+    } catch (err) {
+      log.warn({ err, serverId: this.serverId }, 'Error closing MCP client');
+    }
+    this.connected = false;
+    this.transport = null;
+    log.info({ serverId: this.serverId }, 'MCP client disconnected');
+  }
+
+  private createTransport(config: McpTransport): StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport {
+    switch (config.type) {
+      case 'stdio':
+        return new StdioClientTransport({
+          command: config.command,
+          args: config.args,
+          env: config.env ? { ...process.env, ...config.env } as Record<string, string> : undefined,
+        });
+      case 'sse':
+        return new SSEClientTransport(
+          new URL(config.url),
+          { requestInit: config.headers ? { headers: config.headers } : undefined },
+        );
+      case 'streamable-http':
+        return new StreamableHTTPClientTransport(
+          new URL(config.url),
+          { requestInit: config.headers ? { headers: config.headers } : undefined },
+        );
+    }
+  }
+}

package/src/mcp/manager.ts

@@ -0,0 +1,139 @@
+import type { McpConfig, McpServerConfig } from '../config/mcp-schema.js';
+import { getLogger } from '../util/logger.js';
+import { McpClient, type McpToolInfo } from './client.js';
+
+const log = getLogger('mcp-manager');
+
+export interface McpServerToolInfo {
+  serverId: string;
+  serverConfig: McpServerConfig;
+  tools: McpToolInfo[];
+}
+
+export class McpServerManager {
+  private clients = new Map<string, McpClient>();
+  private serverConfigs = new Map<string, McpServerConfig>();
+
+  async start(config: McpConfig): Promise<McpServerToolInfo[]> {
+    const results: McpServerToolInfo[] = [];
+
+    console.log(`[MCP] Starting ${Object.keys(config.servers).length} server(s)...`);
+    for (const [serverId, serverConfig] of Object.entries(config.servers)) {
+      if (!serverConfig.enabled) {
+        console.log(`[MCP] Server "${serverId}" is disabled, skipping`);
+        log.info({ serverId }, 'MCP server disabled, skipping');
+        continue;
+      }
+
+      try {
+        console.log(`[MCP] Starting server "${serverId}" (transport: ${serverConfig.transport.type})`);
+        const client = new McpClient(serverId);
+        await client.connect(serverConfig.transport);
+        this.clients.set(serverId, client);
+        this.serverConfigs.set(serverId, serverConfig);
+
+        let tools = await client.listTools();
+        log.info({ serverId, toolCount: tools.length }, 'MCP server tools discovered');
+
+        // Apply tool filtering
+        tools = this.filterTools(tools, serverConfig);
+
+        // Apply per-server maxTools limit
+        if (tools.length > serverConfig.maxTools) {
+          log.warn(
+            { serverId, discovered: tools.length, max: serverConfig.maxTools },
+            'MCP server exceeded maxTools limit, truncating',
+          );
+          tools = tools.slice(0, serverConfig.maxTools);
+        }
+
+        results.push({ serverId, serverConfig, tools });
+      } catch (err) {
+        console.error(`[MCP] Failed to connect to server "${serverId}":`, err);
+        log.error({ err, serverId }, 'Failed to connect to MCP server');
+        // Clean up any partially-connected client
+        const staleClient = this.clients.get(serverId);
+        if (staleClient) {
+          try { await staleClient.disconnect(); } catch { /* ignore */ }
+          this.clients.delete(serverId);
+          this.serverConfigs.delete(serverId);
+        }
+      }
+    }
+
+    // Apply global max tools limit
+    const totalTools = results.reduce((sum, r) => sum + r.tools.length, 0);
+    if (totalTools > config.globalMaxTools) {
+      log.warn(
+        { totalTools, globalMax: config.globalMaxTools },
+        'Total MCP tools exceed globalMaxTools, truncating',
+      );
+      let remaining = config.globalMaxTools;
+      for (const result of results) {
+        if (remaining <= 0) {
+          result.tools = [];
+        } else if (result.tools.length > remaining) {
+          result.tools = result.tools.slice(0, remaining);
+        }
+        remaining -= result.tools.length;
+      }
+    }
+
+    return results;
+  }
+
+  async stop(): Promise<void> {
+    const disconnects = Array.from(this.clients.values()).map((client) =>
+      client.disconnect().catch((err) => {
+        log.warn({ err, serverId: client.serverId }, 'Error disconnecting MCP server');
+      }),
+    );
+    await Promise.all(disconnects);
+    this.clients.clear();
+    this.serverConfigs.clear();
+    log.info('All MCP servers disconnected');
+  }
+
+  async callTool(serverId: string, toolName: string, args: Record<string, unknown>) {
+    const client = this.clients.get(serverId);
+    if (!client) {
+      throw new Error(`MCP server "${serverId}" not found`);
+    }
+    return client.callTool(toolName, args);
+  }
+
+  getClient(serverId: string): McpClient | undefined {
+    return this.clients.get(serverId);
+  }
+
+  private filterTools(tools: McpToolInfo[], config: McpServerConfig): McpToolInfo[] {
+    let filtered = tools;
+
+    if (config.allowedTools) {
+      const allowed = new Set(config.allowedTools);
+      filtered = filtered.filter((t) => allowed.has(t.name));
+    }
+
+    if (config.blockedTools) {
+      const blocked = new Set(config.blockedTools);
+      filtered = filtered.filter((t) => !blocked.has(t.name));
+    }
+
+    return filtered;
+  }
+}
+
+// Singleton instance
+let instance: McpServerManager | null = null;
+
+export function getMcpServerManager(): McpServerManager {
+  if (!instance) {
+    instance = new McpServerManager();
+  }
+  return instance;
+}
+
+/** Reset singleton for testing. */
+export function __resetMcpManagerForTesting(): void {
+  instance = null;
+}

package/src/runtime/routes/identity-routes.ts

@@ -3,6 +3,7 @@
  */
 
 import { existsSync, readFileSync, statfsSync,statSync } from 'node:fs';
+import { cpus, totalmem } from 'node:os';
 import { dirname,join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -36,6 +37,76 @@ function getDiskSpaceInfo(): DiskSpaceInfo | null {
   }
 }
 
+interface MemoryInfo {
+  currentMb: number;
+  maxMb: number;
+}
+
+// Read the container memory limit from cgroups if available, falling back to host total.
+// cgroups v2: /sys/fs/cgroup/memory.max (returns "max" when unlimited)
+// cgroups v1: /sys/fs/cgroup/memory/memory.limit_in_bytes (large sentinel when unlimited)
+function getContainerMemoryLimitBytes(): number | null {
+  try {
+    const v2 = readFileSync('/sys/fs/cgroup/memory.max', 'utf-8').trim();
+    if (v2 !== 'max') {
+      const bytes = parseInt(v2, 10);
+      if (!isNaN(bytes) && bytes > 0) return bytes;
+    }
+  } catch { /* not available */ }
+  try {
+    const v1 = readFileSync('/sys/fs/cgroup/memory/memory.limit_in_bytes', 'utf-8').trim();
+    const bytes = parseInt(v1, 10);
+    // cgroups v1 uses a near-INT64_MAX sentinel when no limit is set
+    if (!isNaN(bytes) && bytes > 0 && bytes < totalmem() * 1.5) return bytes;
+  } catch { /* not available */ }
+  return null;
+}
+
+function getMemoryInfo(): MemoryInfo {
+  const bytesToMb = (b: number) => Math.round((b / (1024 * 1024)) * 100) / 100;
+  return {
+    currentMb: bytesToMb(process.memoryUsage().rss),
+    maxMb: bytesToMb(getContainerMemoryLimitBytes() ?? totalmem()),
+  };
+}
+
+interface CpuInfo {
+  currentPercent: number;
+  maxCores: number;
+}
+
+// Track CPU usage over a rolling window so /healthz reports near-real-time
+// utilization instead of a lifetime average (total CPU time / total uptime).
+const CPU_SAMPLE_INTERVAL_MS = 5_000;
+let _lastCpuUsage: NodeJS.CpuUsage = process.cpuUsage();
+let _lastCpuTime: number = Date.now();
+let _cachedCpuPercent = 0;
+
+// Kick off the background sampler. unref() so it never prevents process exit.
+setInterval(() => {
+  const now = Date.now();
+  const newUsage = process.cpuUsage();
+  const elapsedMs = now - _lastCpuTime;
+  if (elapsedMs > 0) {
+    const deltaCpuUs =
+      (newUsage.user - _lastCpuUsage.user) +
+      (newUsage.system - _lastCpuUsage.system);
+    const deltaCpuMs = deltaCpuUs / 1000;
+    const numCores = cpus().length;
+    _cachedCpuPercent =
+      Math.round((deltaCpuMs / (elapsedMs * numCores)) * 10000) / 100;
+  }
+  _lastCpuUsage = newUsage;
+  _lastCpuTime = now;
+}, CPU_SAMPLE_INTERVAL_MS).unref();
+
+function getCpuInfo(): CpuInfo {
+  return {
+    currentPercent: _cachedCpuPercent,
+    maxCores: cpus().length,
+  };
+}
+
 function getPackageVersion(): string | undefined {
   try {
     const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '../../../package.json');
@@ -52,6 +123,8 @@ export function handleHealth(): Response {
     timestamp: new Date().toISOString(),
     version: getPackageVersion(),
     disk: getDiskSpaceInfo(),
+    memory: getMemoryInfo(),
+    cpu: getCpuInfo(),
   });
 }