@animalabs/connectome-host 0.3.1 → 0.3.7

package/src/index.ts

@@ -15,10 +15,16 @@
  *   DATA_DIR            - Data directory for sessions (default: ./data)
  */
 
-import { Membrane, NativeFormatter } from '@animalabs/membrane';
+import {
+  Membrane,
+  NativeFormatter,
+  OpenAIResponsesAPIAdapter,
+  OpenAIResponsesFormatter,
+} from '@animalabs/membrane';
 import { LoggingAnthropicAdapter } from './logging-adapter.js';
+import { CallLedger } from './call-ledger.js';
 import { SettingsModule } from './modules/settings-module.js';
-import { AgentFramework, AutobiographicalStrategy, PassthroughStrategy, WorkspaceModule, type Module, type MountConfig } from '@animalabs/agent-framework';
+import { AgentFramework, AutobiographicalStrategy, PassthroughStrategy, WorkspaceModule, resolveTimeZone, type Module, type MountConfig } from '@animalabs/agent-framework';
 import { resolve, join, basename } from 'node:path';
 import { appendFile, mkdir, stat, rename } from 'node:fs/promises';
 import { readFileSync, existsSync } from 'node:fs';
@@ -34,6 +40,7 @@ import { ActivityModule } from './modules/activity-module.js';
 import { SubscriptionGcModule } from './modules/subscription-gc-module.js';
 import { ChannelModeModule } from './modules/channel-mode-module.js';
 import { WebUiModule } from './modules/web-ui-module.js';
+import { ObserversModule } from './modules/observers-module.js';
 import { McplAdminModule } from './modules/mcpl-admin-module.js';
 import { loadMcplServers, applyAgentOverlay, DEFAULT_CONFIG_PATH, DEFAULT_AGENT_OVERLAY_PATH } from './mcpl-config.js';
 import { SessionManager } from './session-manager.js';
@@ -60,15 +67,11 @@ const config = {
   // OAuth/Bearer token (e.g. a Claude subscription token). When set, it takes
   // precedence over the API key so requests never carry both auth schemes.
   authToken: process.env.ANTHROPIC_AUTH_TOKEN,
+  openaiApiKey: process.env.OPENAI_API_KEY,
   model: process.env.MODEL,
   dataDir: process.env.DATA_DIR || './data',
 };
 
-if (!config.apiKey && !config.authToken) {
-  console.error('Missing ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN). Set one in .env or environment.');
-  process.exit(1);
-}
-
 // ---------------------------------------------------------------------------
 // AppContext — mutable container for session switching
 // ---------------------------------------------------------------------------
@@ -137,14 +140,16 @@ async function createFramework(
   recipe: Recipe,
   agentName: string,
   settingsModule: SettingsModule,
+  callLedger: CallLedger | null,
 ): Promise<AgentFramework> {
   const model = config.model || recipe.agent.model || 'claude-opus-4-6';
   const modules = recipe.modules ?? {};
+  const timeZone = resolveTimeZone(recipe.agent.timezone);
 
   // -- Build module list --
   // SettingsModule is constructed in main() (before the adapter, so the
   // adapter can read its state for cross-cutting concerns like reasoning).
-  const moduleInstances: Module[] = [new TuiModule(), new TimeModule(), settingsModule];
+  const moduleInstances: Module[] = [new TuiModule(), new TimeModule(timeZone), settingsModule];
 
   // Subagents
   let subagentModule: SubagentModule | null = null;
@@ -168,10 +173,11 @@ async function createFramework(
 
   // Fleet (cross-process child orchestration). Opt-in via recipe.
   if (modules.fleet === true) {
-    moduleInstances.push(new FleetModule());
+    moduleInstances.push(new FleetModule({ timeZone }));
   } else if (modules.fleet && typeof modules.fleet === 'object') {
     const fleetCfg = modules.fleet;
     const fleetModuleConfig: FleetModuleConfig = {};
+    fleetModuleConfig.timeZone = timeZone;
     if (fleetCfg.children) {
       fleetModuleConfig.autoStart = fleetCfg.children.map((c) => {
         const entry: NonNullable<FleetModuleConfig['autoStart']>[number] = {
@@ -309,7 +315,7 @@ async function createFramework(
   // ability to spawn arbitrary commands via mcpl_deploy; see recipe.ts).
   let mcplAdminModule: McplAdminModule | null = null;
   if (modules.mcplAdmin === true) {
-    mcplAdminModule = new McplAdminModule();
+    mcplAdminModule = new McplAdminModule({ timeZone });
     moduleInstances.push(mcplAdminModule);
   }
 
@@ -317,13 +323,22 @@ async function createFramework(
   let webUiModule: WebUiModule | null = null;
   if (modules.webui !== undefined && modules.webui !== false) {
     const webuiConfig = typeof modules.webui === 'object' ? modules.webui : {};
+    // Observer grants (docs/observability.md): data/observers.json by
+    // default, overridable via OBSERVERS_FILE. The feature is inert until
+    // the file holds at least one grant. The companion ObserversModule
+    // gives the agent grant/revoke tools over the same file — interiority
+    // access is the agent's to give.
+    const observersPath = process.env.OBSERVERS_FILE || resolve(config.dataDir, 'observers.json');
     webUiModule = new WebUiModule({
       port: webuiConfig.port,
       host: webuiConfig.host,
       basicAuth: webuiConfig.basicAuth,
       allowedOrigins: webuiConfig.allowedOrigins,
+      observersPath,
+      ...(callLedger ? { callLedger } : {}),
     });
     moduleInstances.push(webUiModule);
+    moduleInstances.push(new ObserversModule({ path: observersPath }));
   }
 
   // -- Build MCP server list --
@@ -375,7 +390,12 @@ async function createFramework(
   // Apply the agent overlay (mcpl-servers.agent.json): servers the agent
   // deployed for itself load unconditionally (no recipe opt-in), and
   // tombstones suppress recipe/file servers the agent unloaded.
-  const finalServers = applyAgentOverlay(allServers, DEFAULT_AGENT_OVERLAY_PATH);
+  const finalServers = applyAgentOverlay(allServers, DEFAULT_AGENT_OVERLAY_PATH).map((server) => ({
+    ...server,
+    // Stdio MCPL children inherit a single agent-facing wall clock. Protocol
+    // timestamps remain UTC; only their rendered text uses this setting.
+    env: { ...(server.env ?? {}), AGENT_TIMEZONE: timeZone },
+  }));
 
   // No server augmentation needed — gate is wired via FrameworkConfig.gate
 
@@ -396,6 +416,7 @@ async function createFramework(
     compressionModel: strategyConfig?.compressionModel ?? model,
     autoTickOnNewMessage: true,
     maxMessageTokens: strategyConfig?.maxMessageTokens ?? 10000,
+    ...(strategyType === 'frontdesk' ? { timeZone } : {}),
   };
   // Forward optional tuning fields when set. The key list is typed
   // against `RecipeStrategy`, so an unknown field name is a compile
@@ -456,6 +477,20 @@ async function createFramework(
         maxStreamTokens: recipe.agent.maxStreamTokens ?? 150000,
         contextBudgetTokens: recipe.agent.contextBudgetTokens,
         ...(recipe.agent.cacheTtl && { cacheTtl: recipe.agent.cacheTtl }),
+        ...(recipe.agent.provider === 'openai-responses' && {
+          providerParams: {
+            reasoning: {
+              effort: recipe.agent.responses?.reasoningEffort ?? 'high',
+              context: recipe.agent.responses?.reasoningContext ?? 'all_turns',
+            },
+            ...(recipe.agent.responses?.compactThreshold ? {
+              context_management: [{
+                type: 'compaction',
+                compact_threshold: recipe.agent.responses.compactThreshold,
+              }],
+            } : {}),
+          },
+        }),
         strategy,
         ...(recipe.agent.thinking && { thinking: recipe.agent.thinking }),
         ...(recipe.agent.refusalHandling && { refusalHandling: recipe.agent.refusalHandling }),
@@ -464,6 +499,7 @@ async function createFramework(
     modules: moduleInstances,
     mcplServers: finalServers,
     gate: gateOptions,
+    timeZone,
   });
 
   // Wire post-creation hooks
@@ -743,6 +779,16 @@ function countLines(path: string): number {
 
 async function main() {
   const recipe = await resolveRecipe();
+  const provider = recipe.agent.provider ?? 'anthropic';
+
+  if (provider === 'openai-responses' && !config.openaiApiKey) {
+    console.error('Missing OPENAI_API_KEY for recipe provider "openai-responses".');
+    process.exit(1);
+  }
+  if (provider === 'anthropic' && !config.apiKey && !config.authToken) {
+    console.error('Missing ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN). Set one in .env or environment.');
+    process.exit(1);
+  }
 
   // SettingsModule constructed early so the adapter can read its state for
   // cross-cutting concerns (currently: reasoning). It's wired into the
@@ -757,22 +803,34 @@ async function main() {
     config.dataDir,
     `llm-calls.${new Date().toISOString().replace(/[:.]/g, '-')}.jsonl`,
   );
+  const callLedger = provider === 'anthropic'
+    ? new CallLedger({
+        dataDir: config.dataDir,
+        defaultTtl: recipe.agent.cacheTtl ?? '5m',
+      })
+    : null;
   // OAuth (subscription) auth wins over API-key auth when both are present.
   // Subscription tokens (sk-ant-oat…) additionally require the oauth beta
   // header on every request.
-  const adapter = new LoggingAnthropicAdapter(
-    {
-      ...(config.authToken
-        ? {
-            authToken: config.authToken,
-            defaultHeaders: { 'anthropic-beta': 'oauth-2025-04-20' },
-          }
-        : { apiKey: config.apiKey! }),
-      baseURL: process.env.ANTHROPIC_BASE_URL || undefined,
-    },
-    llmLogPath,
-    () => settingsModule.getReasoning(),
-  );
+  const adapter = provider === 'openai-responses'
+    ? new OpenAIResponsesAPIAdapter({
+        apiKey: config.openaiApiKey!,
+        baseURL: process.env.OPENAI_BASE_URL || undefined,
+      })
+    : new LoggingAnthropicAdapter(
+        {
+          ...(config.authToken
+            ? {
+                authToken: config.authToken,
+                defaultHeaders: { 'anthropic-beta': 'oauth-2025-04-20' },
+              }
+            : { apiKey: config.apiKey! }),
+          baseURL: process.env.ANTHROPIC_BASE_URL || undefined,
+        },
+        llmLogPath,
+        () => settingsModule.getReasoning(),
+        (record) => callLedger!.record(record),
+      );
 
   // Session management — resolved before Membrane construction so the
   // active session's import-source sidecar can contribute to agent-name
@@ -805,7 +863,9 @@ async function main() {
   const agentName = resolved.name;
 
   const membrane = new Membrane(adapter, {
-    formatter: new NativeFormatter(),
+    formatter: provider === 'openai-responses'
+      ? new OpenAIResponsesFormatter()
+      : new NativeFormatter(),
     // Anchor the assistant role for internal callers that don't set
     // request.assistantParticipant themselves (autobio compression,
     // executeMerge). Mismatch here flips stored assistant turns to
@@ -814,7 +874,7 @@ async function main() {
   });
 
   const storePath = sessionManager.getStorePath(activeSession.id);
-  const framework = await createFramework(membrane, storePath, recipe, agentName, settingsModule);
+  const framework = await createFramework(membrane, storePath, recipe, agentName, settingsModule, callLedger);
 
   // Build app context
   const app: AppContext = {
@@ -835,7 +895,7 @@ async function main() {
       // re-resolution would matter only if recipe.agent.name is absent
       // AND the user switches between imports that used different
       // --agent values; not the canonical flow.
-      this.framework = await createFramework(membrane, newStorePath, recipe, this.agentName, settingsModule);
+      this.framework = await createFramework(membrane, newStorePath, recipe, this.agentName, settingsModule, callLedger);
       this.framework.start();
       this.userMessageCount = 0;
       resetBranchState(this.branchState);

package/src/logging-adapter.ts

@@ -27,11 +27,13 @@ import type {
   StreamCallbacks,
 } from '@animalabs/membrane';
 import { appendFileSync } from 'node:fs';
+import { summarizeCacheControls, type ProviderCallRecord } from './call-ledger.js';
 
 /** Live read of the current reasoning setting. The host wires this to
  *  `SettingsModule.getReasoning()` so toggles via the `settings--reasoning_*`
  *  tools take effect on the next call without restart. */
 export type ReasoningGetter = () => { enabled: boolean; budgetTokens: number };
+export type ProviderCallObserver = (record: ProviderCallRecord) => void;
 
 /** Exact first-system-block identity Anthropic requires on subscription
  *  (sk-ant-oat…) OAuth traffic. Verified 2026-07-09: any other first block —
@@ -44,6 +46,7 @@ const OAUTH_SYSTEM_IDENTITY = "You are Claude Code, Anthropic's official CLI for
 export class LoggingAnthropicAdapter extends AnthropicAdapter {
   private readonly logPath: string;
   private readonly getReasoning?: ReasoningGetter;
+  private readonly onCall?: ProviderCallObserver;
   /** True when authenticated with an OAuth/Bearer token instead of an API
    *  key; requests then need the identity block prepended (see above). */
   private readonly oauthMode: boolean;
@@ -52,10 +55,12 @@ export class LoggingAnthropicAdapter extends AnthropicAdapter {
     config: ConstructorParameters<typeof AnthropicAdapter>[0],
     logPath: string,
     getReasoning?: ReasoningGetter,
+    onCall?: ProviderCallObserver,
   ) {
     super(config);
     this.logPath = logPath;
     this.getReasoning = getReasoning;
+    this.onCall = onCall;
     this.oauthMode = Boolean(config?.authToken);
   }
 
@@ -115,15 +120,61 @@ export class LoggingAnthropicAdapter extends AnthropicAdapter {
     }
   }
 
-  private requestSummary(request: ProviderRequest): Record<string, unknown> {
+  private requestSummary(request: ProviderRequest, rawRequest?: unknown): Record<string, unknown> {
+    const cache = rawRequest ? summarizeCacheControls(rawRequest) : undefined;
     return {
       model: request.model,
       maxTokens: request.maxTokens,
       messages: request.messages.length,
       tools: request.tools?.length ?? 0,
+      ...(cache ? { cacheBreakpoints: cache.count, cacheTtls: cache.ttls } : {}),
     };
   }
 
+  private observeCall(
+    kind: 'complete' | 'stream',
+    timestamp: string,
+    durationMs: number,
+    request: ProviderRequest,
+    rawRequest: unknown,
+    response?: ProviderResponse,
+    error?: unknown,
+  ): void {
+    if (!this.onCall) return;
+    const cache = summarizeCacheControls(rawRequest);
+    const raw = (response as { raw?: Record<string, unknown> } | undefined)?.raw;
+    const rawUsage = raw?.usage as Record<string, unknown> | undefined;
+    const cacheCreation = rawUsage?.cache_creation as Record<string, unknown> | undefined;
+    const finite = (value: unknown): number | undefined =>
+      typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+    const text = (value: unknown): string | undefined =>
+      typeof value === 'string' && value.length > 0 ? value : undefined;
+    try {
+      this.onCall({
+        timestamp,
+        kind,
+        durationMs,
+        model: request.model,
+        messages: request.messages.length,
+        inputTokens: response?.usage.inputTokens ?? 0,
+        outputTokens: response?.usage.outputTokens ?? 0,
+        cacheReadTokens: response?.usage.cacheReadTokens ?? 0,
+        cacheWriteTokens: response?.usage.cacheCreationTokens ?? 0,
+        cacheWrite5mTokens: finite(cacheCreation?.ephemeral_5m_input_tokens),
+        cacheWrite1hTokens: finite(cacheCreation?.ephemeral_1h_input_tokens),
+        cacheWriteBucketsAuthoritative: cacheCreation !== undefined,
+        inferenceGeo: text(rawUsage?.inference_geo) ?? text(raw?.inference_geo),
+        serviceTier: text(rawUsage?.service_tier) ?? text(raw?.service_tier),
+        cacheBreakpoints: cache.count,
+        cacheTtls: cache.ttls,
+        stopReason: response?.stopReason,
+        error: error instanceof Error ? error.message : error ? String(error) : undefined,
+      });
+    } catch {
+      // A dashboard observer is never allowed to affect provider traffic.
+    }
+  }
+
   private refusalRawRequest(response: ProviderResponse, rawRequest: unknown): unknown {
     const raw = (response as { raw?: { stop_reason?: string } }).raw;
     return raw?.stop_reason === 'refusal' ? rawRequest : undefined;
@@ -155,22 +206,28 @@ export class LoggingAnthropicAdapter extends AnthropicAdapter {
     const wrapped = this.captureRawRequest(options, sink);
     try {
       const response = await super.complete(effective, wrapped);
+      const timestamp = new Date().toISOString();
+      const durationMs = Date.now() - t0;
       this.log({
         type: 'call', kind: 'complete',
-        timestamp: new Date().toISOString(), durationMs: Date.now() - t0,
-        requestSummary: this.requestSummary(request),
+        timestamp, durationMs,
+        requestSummary: this.requestSummary(request, sink.rawRequest),
         rawRequest: this.refusalRawRequest(response, sink.rawRequest),
         rawResponse: (response as { raw?: unknown }).raw ?? null,
       });
+      this.observeCall('complete', timestamp, durationMs, request, sink.rawRequest, response);
       return response;
     } catch (err) {
+      const timestamp = new Date().toISOString();
+      const durationMs = Date.now() - t0;
       this.log({
         type: 'error', kind: 'complete',
-        timestamp: new Date().toISOString(), durationMs: Date.now() - t0,
-        requestSummary: this.requestSummary(request),
+        timestamp, durationMs,
+        requestSummary: this.requestSummary(request, sink.rawRequest),
         rawRequest: sink.rawRequest,
         error: err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : String(err),
       });
+      this.observeCall('complete', timestamp, durationMs, request, sink.rawRequest, undefined, err);
       throw err;
     }
   }
@@ -186,22 +243,28 @@ export class LoggingAnthropicAdapter extends AnthropicAdapter {
     const wrapped = this.captureRawRequest(options, sink);
     try {
       const response = await super.stream(effective, callbacks, wrapped);
+      const timestamp = new Date().toISOString();
+      const durationMs = Date.now() - t0;
       this.log({
         type: 'call', kind: 'stream',
-        timestamp: new Date().toISOString(), durationMs: Date.now() - t0,
-        requestSummary: this.requestSummary(request),
+        timestamp, durationMs,
+        requestSummary: this.requestSummary(request, sink.rawRequest),
         rawRequest: this.refusalRawRequest(response, sink.rawRequest),
         rawResponse: (response as { raw?: unknown }).raw ?? null,
       });
+      this.observeCall('stream', timestamp, durationMs, request, sink.rawRequest, response);
       return response;
     } catch (err) {
+      const timestamp = new Date().toISOString();
+      const durationMs = Date.now() - t0;
       this.log({
         type: 'error', kind: 'stream',
-        timestamp: new Date().toISOString(), durationMs: Date.now() - t0,
-        requestSummary: this.requestSummary(request),
+        timestamp, durationMs,
+        requestSummary: this.requestSummary(request, sink.rawRequest),
         rawRequest: sink.rawRequest,
         error: err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : String(err),
       });
+      this.observeCall('stream', timestamp, durationMs, request, sink.rawRequest, undefined, err);
       throw err;
     }
   }

package/src/modules/fleet-module.ts

@@ -29,9 +29,10 @@ import type {
   ToolCall,
   ToolResult,
 } from '@animalabs/agent-framework';
+import { formatZonedDateTime, resolveTimeZone } from '@animalabs/agent-framework';
 import { spawn as spawnProcess, type ChildProcess } from 'node:child_process';
 import { connect as netConnect, type Socket } from 'node:net';
-import { existsSync, mkdirSync, unlinkSync, openSync, closeSync, appendFileSync } from 'node:fs';
+import { existsSync, mkdirSync, unlinkSync, openSync, closeSync, appendFileSync, realpathSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
 import { type IncomingCommand, type WireEvent, matchesSubscription } from './fleet-types.js';
 import { loadRecipe } from '../recipe.js';
@@ -81,6 +82,8 @@ interface FleetEventSubscription {
 // ---------------------------------------------------------------------------
 
 export interface FleetModuleConfig {
+  /** IANA zone for wall-clock timestamps returned by fleet tools. */
+  timeZone?: string;
   /** Default subscription sent to children at handshake (default: ['*']). */
   defaultSubscription?: string[];
   /** Max events to retain per child for peek (default: 500). */
@@ -255,6 +258,7 @@ export class FleetModule implements Module {
       sigtermEscalationMs: config.sigtermEscalationMs ?? 5_000,
       childIndexPath: config.childIndexPath ?? process.argv[1] ?? '',
       childRuntimePath: config.childRuntimePath ?? process.execPath,
+      timeZone: resolveTimeZone(config.timeZone),
     };
 
     this.autoStartChildren = config.autoStart ?? [];
@@ -1014,7 +1018,12 @@ export class FleetModule implements Module {
       {
         detached: true,
         stdio: startupFd !== null ? ['ignore', startupFd, startupFd] : 'ignore',
-        env: { ...process.env, ...input.env, DATA_DIR: dataDir },
+        env: {
+          ...process.env,
+          ...input.env,
+          AGENT_TIMEZONE: this.config.timeZone,
+          DATA_DIR: dataDir,
+        },
       },
     );
     proc.unref();
@@ -1095,9 +1104,9 @@ export class FleetModule implements Module {
       name: c.name,
       status: c.status,
       pid: c.pid,
-      startedAt: c.startedAt,
-      exitedAt: c.exitedAt,
-      lastEventAt: c.lastEventAt,
+      startedAt: formatZonedDateTime(c.startedAt, this.config.timeZone),
+      exitedAt: c.exitedAt === null ? null : formatZonedDateTime(c.exitedAt, this.config.timeZone),
+      lastEventAt: c.lastEventAt === null ? null : formatZonedDateTime(c.lastEventAt, this.config.timeZone),
       eventCount: c.events.length,
     }));
     return { success: true, data: list };
@@ -1120,9 +1129,10 @@ export class FleetModule implements Module {
       socketPath: c.socketPath,
       pid: c.pid,
       status: c.status,
-      startedAt: c.startedAt,
-      exitedAt: c.exitedAt,
-      lastEventAt: c.lastEventAt,
+      startedAt: formatZonedDateTime(c.startedAt, this.config.timeZone),
+      exitedAt: c.exitedAt === null ? null : formatZonedDateTime(c.exitedAt, this.config.timeZone),
+      lastEventAt: c.lastEventAt === null ? null : formatZonedDateTime(c.lastEventAt, this.config.timeZone),
+      timeZone: this.config.timeZone,
       exitCode: c.exitCode,
       exitReason: c.exitReason,
       eventCount: c.events.length,
@@ -1202,9 +1212,11 @@ export class FleetModule implements Module {
    * entries derived from `children[]`, which are absolute post-load).
    */
   private matchesAllowlist(recipe: string, resolved: string): boolean {
+    const canonicalResolved = existsSync(resolved) ? realpathSync(resolved) : resolved;
     for (const entry of this.allowlist) {
       if (entry === '*') return true;
-      if (entry === recipe || entry === resolved) return true;
+      const canonicalEntry = !entry.includes('*') && existsSync(entry) ? realpathSync(entry) : entry;
+      if (entry === recipe || entry === resolved || canonicalEntry === canonicalResolved) return true;
       if (entry.endsWith('*') && !entry.slice(0, -1).includes('*')) {
         const prefix = entry.slice(0, -1);
         if (recipe.startsWith(prefix) || resolved.startsWith(prefix)) return true;

package/src/modules/mcpl-admin-module.ts

@@ -33,6 +33,7 @@ import type {
   AgentFramework,
   McplServerConfig,
 } from '@animalabs/agent-framework';
+import { resolveTimeZone } from '@animalabs/agent-framework';
 import {
   DEFAULT_CONFIG_PATH,
   DEFAULT_AGENT_OVERLAY_PATH,
@@ -44,6 +45,8 @@ import {
 } from '../mcpl-config.js';
 
 export interface McplAdminModuleConfig {
+  /** IANA zone propagated to newly deployed stdio servers. */
+  timeZone?: string;
   /** Path to the agent overlay file. Default: `mcpl-servers.agent.json` in cwd. */
   overlayPath?: string;
   /** Path to the human-owned server config file (read-only here). */
@@ -64,10 +67,12 @@ export class McplAdminModule implements Module {
   private framework: AgentFramework | null = null;
   private overlayPath: string;
   private configPath: string;
+  private timeZone: string;
 
   constructor(config?: McplAdminModuleConfig) {
     this.overlayPath = config?.overlayPath ?? DEFAULT_AGENT_OVERLAY_PATH;
     this.configPath = config?.configPath ?? DEFAULT_CONFIG_PATH;
+    this.timeZone = resolveTimeZone(config?.timeZone);
   }
 
   /** Post-creation wiring (called from index.ts, mirrors ActivityModule.setFramework). */
@@ -275,6 +280,7 @@ export class McplAdminModule implements Module {
     saveAgentOverlay(this.overlayPath, overlay);
 
     const config = resolveOverlayEntry(id, entry, this.overlayPath) as unknown as McplServerConfig;
+    config.env = { ...(config.env ?? {}), AGENT_TIMEZONE: this.timeZone };
 
     const alreadyLoaded = framework.listMcplServers().some(s => s.id === id);
     try {