@animalabs/agent-framework 0.6.0 → 0.6.3

package/src/types/framework.ts

@@ -56,6 +56,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 +99,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/module.ts

@@ -36,6 +36,15 @@ export interface Module {
   /** Unique name, used for tool namespacing and state storage */
   readonly name: string;
 
+  /**
+   * Per-module budget (ms) for gatherContext() before the framework skips this
+   * module's injection for the turn (fail-open). Defaults to the registry-wide
+   * default (15s) when omitted. Declare a larger budget when gatherContext
+   * does real work — e.g. sequential LLM calls with provider backoff — so the
+   * injection isn't silently dropped every turn.
+   */
+  readonly contextTimeoutMs?: number;
+
   /**
    * Start the module.
    * Called when the framework starts or when the module is added.
@@ -101,9 +110,52 @@ export interface ModuleContext {
 
   /**
    * Set persistent state for this module.
+   *
+   * This rewrites the module's full state object every call — appropriate for
+   * small, bounded state only. For accumulating collections (registries,
+   * corpora, histories) use a log state (`registerLogState`/`appendToLog`)
+   * instead: a setState of an ever-growing object makes every persisted record
+   * proportional to accumulated content, i.e. O(n²) aggregate disk.
    */
   setState<T>(state: T): void;
 
+  /**
+   * Register an auxiliary append-log state for this module, stored as
+   * `modules/<module>/<name>`. Idempotent — safe to call on every start().
+   * Items are appended with `appendToLog` (one O(item) record per append) and
+   * point-edited with `editLogItem`; Chronicle's append_log snapshot cadence
+   * handles consolidation. `name` must not be 'state' (reserved for the main
+   * snapshot state) and must not contain '/'.
+   */
+  registerLogState(
+    name: string,
+    opts?: { deltaSnapshotEvery?: number; fullSnapshotEvery?: number }
+  ): void;
+
+  /**
+   * Append one item to a log state registered via registerLogState.
+   * Record size is O(item), independent of accumulated log length.
+   */
+  appendToLog<T>(name: string, item: T): void;
+
+  /**
+   * Overwrite the item at `index` in a log state. Indices are stable —
+   * appends assign the next index and nothing is ever removed.
+   */
+  editLogItem<T>(name: string, index: number, item: T): void;
+
+  /**
+   * Read the full contents of a log state (empty array if never written).
+   * Intended for one-shot reconstruction at start(); keep hot-path reads
+   * against the in-memory copy.
+   */
+  getLog<T>(name: string): T[];
+
+  /**
+   * Number of items in a log state (0 if never written).
+   */
+  getLogLength(name: string): number;
+
   /**
    * Process queue for pushing events from external listeners.
    * @deprecated Use pushEvent() instead — it also emits process:received traces.

package/src/types/trace.ts

@@ -60,6 +60,13 @@ export type TraceEvent =
       type: 'inference:exhausted';
       agentName: string;
       error: string;
+      /** Whether membrane classified the failure as retryable (observability). */
+      retryable?: boolean;
+      /**
+       * The membrane error type (e.g. 'invalid_request', 'auth', 'context_length').
+       * The poison-history breaker fires only on 'invalid_request'.
+       */
+      errorType?: string;
     })
 
   // Streaming inference lifecycle
@@ -270,6 +277,66 @@ export type TraceEvent =
       type: 'mcpl:conversation-disposed';
       agentName: string;
       channelId?: string;
+    })
+
+  // MCPL server connection lifecycle (spawn / handshake / reconnect health).
+  // Previously these outcomes were visible only on the host process's own
+  // stderr, so a server that lost the boot handshake race just went missing.
+  | (TraceEventBase & {
+      type: 'mcpl:server-connect-failed';
+      serverId: string;
+      error: string;
+      /** Ordinal of the failed attempt: 0 is the initial connect, N is the Nth background retry. */
+      attempt: number;
+      /** True when a background reconnect loop will keep retrying. */
+      willRetry: boolean;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:server-reconnected';
+      serverId: string;
+      /** How many attempts the reconnect loop needed (1 = first retry succeeded). */
+      attempts: number;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:server-closed';
+      serverId: string;
+      /** Child process exit code, or null when killed by signal / closed explicitly. */
+      code: number | null;
+      /** Signal that terminated the child, if any. */
+      signal: string | null;
+      /** True when a background reconnect loop will revive the connection. */
+      willReconnect: boolean;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:server-error';
+      serverId: string;
+      error: string;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:orphaned-response';
+      serverId: string;
+      /** The JSON-RPC id of the late response whose pending request already timed out. */
+      responseId: string | number;
+      /** True when the dropped response carried host-managed `state`. */
+      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>;
     });
 
 /**