@animalabs/agent-framework 0.6.2 → 0.6.4

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;
 
@@ -56,6 +63,13 @@ export interface FrameworkConfig {
   /** Interval for periodic store sync in milliseconds (default: 1000ms, 0 to disable) */
   syncIntervalMs?: number;
 
+  /**
+   * Interval for queued context-maintenance polling in milliseconds
+   * (default: 5000ms, 0 to disable). Each pass refreshes the agent's live tool
+   * definitions, then advances pending compression/indexing work.
+   */
+  maintenanceIntervalMs?: number;
+
   /** Process logging configuration (default: disabled) */
   processLogging?: ProcessLoggingConfig;
 
@@ -92,6 +106,43 @@ export interface FrameworkConfig {
   conversations?: ConversationRouterConfig;
 }
 
+/** One agent's outcome within a periodic context-maintenance pass. */
+export interface ContextMaintenanceAgentRun {
+  agentName: string;
+  startedAt: number;
+  finishedAt?: number;
+  ticks: number;
+  readyBefore: boolean;
+  readyAfter?: boolean;
+  pendingBefore?: string;
+  pendingAfter?: string;
+  progressBefore?: Record<string, unknown>;
+  progressAfter?: Record<string, unknown>;
+  error?: string;
+}
+
+/** A bounded periodic context-maintenance pass. */
+export interface ContextMaintenanceRun {
+  id: number;
+  startedAt: number;
+  finishedAt?: number;
+  agents: ContextMaintenanceAgentRun[];
+}
+
+/** Debug-safe maintenance state. Contains counts and errors, never messages. */
+export interface ContextMaintenanceSnapshot {
+  intervalMs: number;
+  ticksPerPass: number;
+  current: ContextMaintenanceRun | null;
+  history: ContextMaintenanceRun[];
+  agents: Array<{
+    agentName: string;
+    ready: boolean;
+    pending?: string;
+    progress?: Record<string, unknown>;
+  }>;
+}
+
 /**
  * Policy for deciding when to run inference.
  */

package/src/types/trace.ts

@@ -321,6 +321,22 @@ export type TraceEvent =
       hadState: boolean;
       /** True when the dropped response carried a server-managed `checkpoint`. */
       hadCheckpoint: boolean;
+    })
+
+  // Ops / fleet observability. Everything the framework's opsAlert() escalates
+  // (refusals, hard-down, MCPL unreachable, …) mirrored onto the trace bus so
+  // authorized observers see alerts on the same wire as the rest of the
+  // agent's internal life. Discord (CONNECTOME_OPS_WEBHOOK) is one sink of
+  // this stream, not a separate system. See connectome docs/observability.md.
+  | (TraceEventBase & {
+      type: 'ops:alert';
+      /** Alert kind — open set: 'refusal' | 'hard-down' | 'mcpl-down' | … */
+      kind: string;
+      /** Agent name, or a server/component id for non-agent alerts (e.g. mcpl-down). */
+      agentName: string;
+      message: string;
+      /** Kind-specific structured payload (mirrors the failures.log record). */
+      data?: Record<string, unknown>;
     });
 
 /**