@animalabs/agent-framework 0.6.3 → 0.6.5

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;
 
@@ -174,6 +181,16 @@ export type ErrorAction =
   | { retry: true; delayMs: number }
   | { retry: false; emit?: ProcessEvent };
 
+/**
+ * Terminal result for a framework-driven ephemeral agent run.
+ */
+export interface AgentSettleResult {
+  stopReason: 'completed' | 'turn_ended' | 'exhausted';
+  speech: string;
+  toolCallsCount: number;
+  error?: string;
+}
+
 /**
  * Framework state exposed to policies.
  */