@animalabs/agent-framework 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",

package/src/agent.ts

@@ -47,7 +47,9 @@ export class Agent {
   /** Refusal auto-rewind policy (see AgentConfig.refusalHandling). */
   readonly refusalHandling: AgentConfig['refusalHandling'];
   /** Prompt-cache TTL forwarded to the provider (see AgentConfig.cacheTtl). */
-  readonly cacheTtl: AgentConfig['cacheTtl'];
+  readonly cacheTtl: NonNullable<AgentConfig['cacheTtl']>;
+  /** Provider-specific request parameters forwarded unchanged by Membrane. */
+  readonly providerParams?: Record<string, unknown>;
 
   private _state: AgentState = { status: 'idle' };
   private _inferenceStartedAt = 0;
@@ -75,7 +77,8 @@ export class Agent {
     this.temperature = config.temperature;
     this.thinking = config.thinking;
     this.refusalHandling = config.refusalHandling;
-    this.cacheTtl = config.cacheTtl;
+    this.cacheTtl = config.cacheTtl ?? '1h';
+    this.providerParams = config.providerParams;
     this.maxStreamTokens = config.maxStreamTokens ?? 150_000;
     this.contextBudgetTokens = config.contextBudgetTokens;
     this.contextManager = contextManager;
@@ -217,6 +220,7 @@ export class Agent {
         ...(this.thinking !== undefined && { thinking: this.thinking }),
       },
       tools: tools.length > 0 ? tools : undefined,
+      ...(this.providerParams && { providerParams: this.providerParams }),
       assistantParticipant: this.name,
     };
 
@@ -357,7 +361,8 @@ export class Agent {
       },
       tools: availableTools.length > 0 ? availableTools : undefined,
       promptCaching: true,
-      ...(this.cacheTtl !== undefined && { cacheTtl: this.cacheTtl }),
+      cacheTtl: this.cacheTtl,
+      ...(this.providerParams && { providerParams: this.providerParams }),
       assistantParticipant: this.name,
     };
   }

package/src/framework.ts

@@ -79,6 +79,7 @@ import type {
   ChannelsIncomingParams,
 } from './mcpl/types.js';
 import type { ContextInjection } from '@animalabs/context-manager';
+import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
 
 const FRAMEWORK_STATE_ID = 'framework/state';
 const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
@@ -374,6 +375,8 @@ export class AgentFramework {
 
   // Session-level token usage tracking (always-on)
   private usageTracker: UsageTracker;
+  /** Presentation-only wall-clock zone; persistence remains UTC/epoch. */
+  private readonly timeZone: string;
 
   private constructor(
     store: JsStore,
@@ -384,7 +387,8 @@ export class AgentFramework {
     syncIntervalMs: number,
     maintenanceIntervalMs: number,
     processLoggingPersist: boolean,
-    processLoggingBroadcast: boolean
+    processLoggingBroadcast: boolean,
+    timeZone: string,
   ) {
     this.store = store;
     this.ownsStore = ownsStore;
@@ -395,6 +399,7 @@ export class AgentFramework {
     this.maintenanceIntervalMs = maintenanceIntervalMs;
     this.processLoggingPersist = processLoggingPersist;
     this.processLoggingBroadcast = processLoggingBroadcast;
+    this.timeZone = timeZone;
     this.queue = new ProcessQueueImpl();
     this.usageTracker = new UsageTracker({
       emitTrace: (e: UsageUpdatedEvent) => this.emitTrace({ ...e }),
@@ -485,7 +490,8 @@ export class AgentFramework {
       config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS,
       config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS,
       processLoggingPersist,
-      processLoggingBroadcast
+      processLoggingBroadcast,
+      resolveTimeZone(config.timeZone),
     );
 
     // Restore persisted usage data (if any) from prior session
@@ -5764,7 +5770,16 @@ export class AgentFramework {
 
     console.error(`[sleep] agent=${agentName} seconds=${seconds} announce=${announce} until=${new Date(until).toISOString()}`);
     // endTurn: the agent stops here and goes idle for the duration.
-    finish({ success: true, data: { sleepingFor: human, until }, endTurn: true });
+    finish({
+      success: true,
+      data: {
+        sleepingFor: human,
+        until,
+        untilLocal: formatZonedDateTime(until, this.timeZone),
+        timeZone: this.timeZone,
+      },
+      endTurn: true,
+    });
   }
 
   /** Aggregate the event-tag vocabulary: reserved chat:* core + each connected

package/src/index.ts

@@ -7,6 +7,7 @@ export { Agent } from './agent.js';
 export type { StartStreamResult } from './agent.js';
 export { ProcessQueueImpl } from './queue.js';
 export { ModuleRegistry } from './module-registry.js';
+export { formatZonedDateTime, formatZonedTime, isValidTimeZone, resolveTimeZone } from './timezone.js';
 
 // Built-in modules
 export * from './modules/index.js';

package/src/modules/discord/index.ts

@@ -41,6 +41,7 @@ import type {
   ListChannelsInput,
   FetchHistoryInput,
 } from './types.js';
+import { formatZonedDateTime, resolveTimeZone } from '../../timezone.js';
 
 // Re-export event types for consumers who want to handle them
 export type { DiscordMessageEvent, DiscordEditEvent, DiscordDeleteEvent } from './types.js';
@@ -99,6 +100,7 @@ export class DiscordModule implements Module {
   readonly name = 'discord';
 
   private config: DiscordModuleConfig;
+  private readonly timeZone: string;
   private ctx: ModuleContext | null = null;
   private client: DiscordClientInterface;
   private state: DiscordModuleState = {
@@ -126,6 +128,7 @@ export class DiscordModule implements Module {
   constructor(client: DiscordClientInterface, config: DiscordModuleConfig) {
     this.client = client;
     this.config = { ...DEFAULT_CONFIG, ...config };
+    this.timeZone = resolveTimeZone(config.timeZone);
   }
 
   async start(ctx: ModuleContext): Promise<void> {
@@ -1190,7 +1193,7 @@ export class DiscordModule implements Module {
           authorId: m.authorId,
           isBot: m.isBot,
           content: m.content,
-          timestamp: m.timestamp.toISOString(),
+          timestamp: formatZonedDateTime(m.timestamp, this.timeZone),
           replyTo: m.replyTo,
         })),
       },

package/src/modules/discord/types.ts

@@ -9,6 +9,9 @@ import type { ContentBlock } from '@animalabs/membrane';
 // ============================================================================
 
 export interface DiscordModuleConfig {
+  /** IANA zone for timestamps returned to the agent by fetch_history. */
+  timeZone?: string;
+
   /** Discord bot token */
   token: string;
 

package/src/modules/health/index.ts

@@ -24,8 +24,12 @@ import type { Module, ModuleContext } from '../../types/module.js';
 import type { ToolDefinition, ToolCall, ToolResult, ProcessEvent } from '../../types/events.js';
 import type { EventResponse, ProcessState } from '../../types/module.js';
 import type { AgentFramework } from '../../framework.js';
+import { formatZonedDateTime, resolveTimeZone } from '../../timezone.js';
 
 export interface HealthModuleConfig {
+  /** IANA zone for timestamps returned by the snapshot tool. */
+  timeZone?: string;
+
   /**
    * Default number of recent inferences to summarize when the tool is
    * called without an explicit limit. Default: 20.
@@ -70,6 +74,7 @@ export class HealthModule implements Module {
 
   constructor(config: HealthModuleConfig = {}) {
     this.config = {
+      timeZone: resolveTimeZone(config.timeZone),
       defaultLookback: config.defaultLookback ?? 20,
       subagentStateId: config.subagentStateId ?? 'modules/subagent/state',
     };
@@ -162,10 +167,20 @@ export class HealthModule implements Module {
     const recent = this.framework.queryInferenceLogs({ limit: lookback });
     const recentEntries = recent.entries ?? [];
 
+    // Presentation-boundary guard: queryInferenceLogs casts raw persisted
+    // JSON without validation, so a legacy/corrupt record can carry a missing
+    // or non-numeric timestamp. formatZonedDateTime throws on invalid dates
+    // (correctly — misuse should be loud), but one bad record must not sink
+    // the whole snapshot: degrade to the raw value (or null) instead.
+    const safeZoned = (ts: unknown): unknown =>
+      typeof ts === 'number' && Number.isFinite(ts)
+        ? formatZonedDateTime(ts, this.config.timeZone)
+        : ts ?? null;
+
     const projectSummary = (e: typeof recentEntries[number]) => {
       const s = e.summary ?? e.entry;
       return {
-        timestamp: s.timestamp,
+        timestamp: safeZoned(s.timestamp),
         agentName: s.agentName,
         success: s.success,
         error: s.error,
@@ -224,8 +239,8 @@ export class HealthModule implements Module {
               name: sa.name,
               type: sa.type,
               status: sa.status,
-              startedAt: startedAt > 0 ? new Date(startedAt).toISOString() : null,
-              lastActivityAt: lastActivityAt > 0 ? new Date(lastActivityAt).toISOString() : null,
+              startedAt: startedAt > 0 ? formatZonedDateTime(startedAt, this.config.timeZone) : null,
+              lastActivityAt: lastActivityAt > 0 ? formatZonedDateTime(lastActivityAt, this.config.timeZone) : null,
               runtimeSeconds: startedAt > 0 ? Math.floor((now - startedAt) / 1000) : null,
               silentSeconds: lastActivityAt > 0 ? Math.floor((now - lastActivityAt) / 1000) : null,
               toolCallsCount: sa.toolCallsCount,
@@ -244,7 +259,8 @@ export class HealthModule implements Module {
     const modules = this.ctx ? this.listModulesViaContext() : [];
 
     return {
-      timestamp: new Date().toISOString(),
+      timestamp: formatZonedDateTime(Date.now(), this.config.timeZone),
+      timeZone: this.config.timeZone,
       window: {
         lookback,
         inferencesInWindow: recentEntries.length,

package/src/timezone.ts

@@ -0,0 +1,90 @@
+/**
+ * Agent-visible wall-clock formatting.
+ *
+ * Persistence and protocol timestamps should remain epoch milliseconds or UTC
+ * ISO strings.  These helpers are only for presentation boundaries where a
+ * timestamp is rendered into an agent's context or a tool result.
+ */
+
+export function isValidTimeZone(timeZone: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone }).format(new Date(0));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveTimeZone(configured?: string): string {
+  const candidate = configured?.trim()
+    || process.env.AGENT_TIMEZONE?.trim()
+    || Intl.DateTimeFormat().resolvedOptions().timeZone
+    || 'UTC';
+  if (!isValidTimeZone(candidate)) {
+    throw new Error(`Invalid IANA time zone: ${JSON.stringify(candidate)}`);
+  }
+  return candidate;
+}
+
+type ZonedParts = {
+  year: string;
+  month: string;
+  day: string;
+  hour: string;
+  minute: string;
+  second: string;
+};
+
+function zonedParts(date: Date, timeZone: string): ZonedParts {
+  const parts = new Intl.DateTimeFormat('en-CA', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hourCycle: 'h23',
+  }).formatToParts(date);
+  const get = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((part) => part.type === type)?.value ?? '';
+  return {
+    year: get('year'),
+    month: get('month'),
+    day: get('day'),
+    hour: get('hour'),
+    minute: get('minute'),
+    second: get('second'),
+  };
+}
+
+/** RFC3339-style local time with an explicit numeric offset and IANA zone. */
+export function formatZonedDateTime(value: Date | number | string, timeZone: string): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) throw new Error(`Invalid date: ${String(value)}`);
+  const zone = resolveTimeZone(timeZone);
+  const p = zonedParts(date, zone);
+
+  // Reinterpret the displayed wall-clock components as UTC to recover the
+  // offset that applied at this exact instant (including DST transitions).
+  const displayedAsUtc = Date.UTC(
+    Number(p.year), Number(p.month) - 1, Number(p.day),
+    Number(p.hour), Number(p.minute), Number(p.second),
+  );
+  const instantAtWholeSecond = Math.floor(date.getTime() / 1000) * 1000;
+  const offsetMinutes = Math.round((displayedAsUtc - instantAtWholeSecond) / 60_000);
+  const sign = offsetMinutes < 0 ? '-' : '+';
+  const absoluteOffset = Math.abs(offsetMinutes);
+  const offset = `${sign}${String(Math.floor(absoluteOffset / 60)).padStart(2, '0')}:${String(absoluteOffset % 60).padStart(2, '0')}`;
+  const millis = String(date.getUTCMilliseconds()).padStart(3, '0');
+
+  return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}.${millis}${offset} [${zone}]`;
+}
+
+/** Compact wall-clock time for provenance headers. */
+export function formatZonedTime(value: Date | number | string, timeZone: string): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) throw new Error(`Invalid date: ${String(value)}`);
+  const p = zonedParts(date, resolveTimeZone(timeZone));
+  return `${p.hour}:${p.minute}`;
+}

package/src/types/agent.ts

@@ -48,7 +48,7 @@ export interface AgentConfig {
 
   /**
    * Prompt-cache TTL forwarded to the provider (Anthropic `cache_control.ttl`).
-   * '5m' (provider default) or '1h'. When unset, Membrane's default applies.
+   * '5m' or '1h'. Defaults to '1h'.
    *
    * Why you'd set '1h': for persistent agents whose conversational cadence is
    * slower than 5 minutes, the default TTL expires between turns and the full
@@ -57,10 +57,14 @@ export interface AgentConfig {
    * chatty-but-not-rapid agent pays the write premium over and over. With '1h'
    * the write happens once per idle-hour and subsequent turns hit cache reads;
    * in practice cache writes can dominate spend for slow-cadence agents.
-   * Keep '5m' (or unset) for high-frequency loops with sub-5-minute cadence,
+   * Set '5m' explicitly for high-frequency loops with sub-5-minute cadence,
    * where the cheaper write premium wins.
    */
   cacheTtl?: '5m' | '1h';
+
+  /** Provider-specific request parameters (for example Responses reasoning
+   * and server-side compaction settings). */
+  providerParams?: Record<string, unknown>;
   /**
    * Extended thinking config. When `enabled: true`, the agent runs with
    * Anthropic's native extended thinking; responses include `thinking` blocks

package/src/types/framework.ts

@@ -32,6 +32,13 @@ export interface ProcessLoggingConfig {
  * Configuration for the agent framework.
  */
 export interface FrameworkConfig {
+  /**
+   * IANA zone used only when rendering wall-clock times for the agent.
+   * Stored/protocol timestamps remain epoch/UTC. Defaults to AGENT_TIMEZONE,
+   * then the process zone.
+   */
+  timeZone?: string;
+
   /** Path to Chronicle store */
   storePath?: string;