@animalabs/agent-framework 0.6.0 → 0.6.3

package/src/gate/event-gate.ts

@@ -344,12 +344,16 @@ export class EventGate {
   private defaultSkipped = 0;
   private defaultByEventType = new Map<string, { triggered: number; skipped: number }>();
 
-  // Sleep state (set via the `sleep` tool). Passive: evaluate() suppresses
-  // non-privileged wakes while now() < sleepUntil. No timer — after expiry the
-  // next event evaluates normally.
+  // Sleep state (set via the `sleep` tool). evaluate() suppresses non-privileged
+  // wakes while now() < sleepUntil. A self-wake timer (sleepTimer) fires an
+  // inference when the window expires, so `sleep(N)` means "wake me in N
+  // seconds" rather than merely lifting suppression and waiting for an external
+  // event.
   private sleepUntil = 0;
   private sleepNote: string | undefined;
   private sleepSuppressed = 0;
+  private sleepTimer: ReturnType<typeof setTimeout> | null = null;
+  private sleepAgent: string | undefined;
 
   // Privileged users who may wake the agent through sleep. Hot-reloaded from
   // privilegedUsersPath on change.
@@ -1098,6 +1102,18 @@ export class EventGate {
     }
   }
 
+  /** Live inference-gating snapshot for diagnostics (e.g. a SIGUSR2 dump).
+   *  A non-empty `inferring` with a stale timestamp + growing `bufferedEvents`
+   *  is the signature of the wake-wedge: an agent stuck mid-"inference" so all
+   *  incoming events buffer and never trigger. */
+  inferenceDiagnostics(): { inferring: string[]; bufferedEvents: number; sleepUntil: number } {
+    return {
+      inferring: [...this.inferring],
+      bufferedEvents: this.inferenceBuffer.length,
+      sleepUntil: this.sleepUntil,
+    };
+  }
+
   // =========================================================================
   // Inference buffer cap
   // =========================================================================
@@ -1121,11 +1137,17 @@ export class EventGate {
   // =========================================================================
 
   /** Begin (or extend) a sleep window of `seconds`. Returns the wake time. */
-  setSleep(seconds: number, note?: string): { until: number } {
+  setSleep(seconds: number, note?: string, agentName?: string): { until: number } {
     const ms = Math.max(0, Math.floor(seconds * 1000));
     this.sleepUntil = this.now() + ms;
     this.sleepNote = note;
+    this.sleepAgent = agentName;
     this.sleepSuppressed = 0;
+    // Arm the self-wake: when the window elapses, clear sleep and request an
+    // inference so the agent resumes on its own (not dependent on a heartbeat
+    // tick or an incoming message). Cancelled by clearSleep()/`wake`.
+    if (this.sleepTimer) clearTimeout(this.sleepTimer);
+    this.sleepTimer = setTimeout(() => this.wakeFromSleep('sleep-expired'), ms);
     this.reloadPrivilegedIfChanged();
     this.emitTrace({
       type: 'gate:decision',
@@ -1143,9 +1165,39 @@ export class EventGate {
     const wasAsleep = this.sleepUntil > this.now();
     this.sleepUntil = 0;
     this.sleepNote = undefined;
+    this.sleepAgent = undefined;
+    if (this.sleepTimer) { clearTimeout(this.sleepTimer); this.sleepTimer = null; }
     return wasAsleep;
   }
 
+  /**
+   * Self-wake handler: fired by the sleepTimer when a sleep window elapses.
+   * Clears the sleep state and requests an inference so the agent wakes on its
+   * own — this is what makes `sleep(N)` a real "wake me in N seconds" rather
+   * than just a suppression window. No-op if sleep was already cleared (via
+   * `wake`) or re-armed to a later time by a fresh `sleep` call.
+   */
+  private wakeFromSleep(reason: string): void {
+    this.sleepTimer = null;
+    if (this.sleepUntil === 0 || this.sleepUntil > this.now()) return;
+    const note = this.sleepNote;
+    const agent = this.sleepAgent;
+    this.sleepUntil = 0;
+    this.sleepNote = undefined;
+    this.sleepAgent = undefined;
+    this.emitTrace({
+      type: 'gate:decision',
+      eventType: 'sleep:expired',
+      matchedPolicy: 'asleep',
+      trigger: true,
+      behavior: 'always',
+      timestamp: this.now(),
+    });
+    const detail = note ? `${reason}: ${note}` : reason;
+    const targets = agent ? [agent] : this.getAgentNamesFn();
+    for (const a of targets) this.requestInferenceFn(a, detail, 'sleep');
+  }
+
   /** Current sleep state, or null if awake. */
   getSleepState(): { until: number; remainingMs: number; note?: string; suppressed: number } | null {
     const remainingMs = this.sleepUntil - this.now();

package/src/index.ts

@@ -63,6 +63,16 @@ export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior
 // MCPL channel registry (exposed for modules that need channel-level operations)
 export { ChannelRegistry } from './mcpl/index.js';
 
+// MCPL server config (exposed for hosts that manage servers at runtime via
+// connectMcplServer / disconnectMcplServer / restartMcplServer)
+export type { McplServerConfig } from './mcpl/index.js';
+
+// MCPL client connection (exposed so external tooling — server playtests,
+// health probes, protocol harnesses — can dial an MCPL server exactly the
+// way the framework host does, over stdio or WebSocket)
+export { McplServerConnection } from './mcpl/index.js';
+export type { McplHostCapabilities } from './mcpl/index.js';
+
 // Per-channel conversation routing
 export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './mcpl/index.js';
 export type {

package/src/mcpl/channel-registry.ts

@@ -823,6 +823,25 @@ export class ChannelRegistry {
   // Lifecycle
   // ==========================================================================
 
+  /**
+   * Remove all channel state belonging to a single server. Called by the
+   * framework when an MCPL server is disconnected at runtime, so a dead
+   * server's channels don't linger and route speech into the void.
+   */
+  removeServer(serverId: string): void {
+    for (const [key, entry] of this.channels) {
+      if (entry.serverId !== serverId) continue;
+      this.channels.delete(key);
+      this.stopTyping(entry.descriptor.id);
+      if (this.defaultPublishChannel === entry.descriptor.id) {
+        this.defaultPublishChannel = null;
+        this.defaultPublishMessageId = null;
+        this.defaultPublishThreadId = undefined;
+      }
+    }
+    this.subscriptionPolicies.delete(serverId);
+  }
+
   /**
    * Stop all typing intervals and clear all channel registrations.
    */
@@ -1121,9 +1140,23 @@ export class ChannelRegistry {
    * is no locus / the channel or its server can't be resolved (in which case
    * the speech simply stays in chronicle + module surfaces).
    */
+  /** Resolve the outbound locus (fork HOME → this-turn's TRIGGERING channel →
+   *  process-global default). Public so a multi-segment caller can snapshot it
+   *  ONCE and pin every segment to it via routeSpeech's `overrideChannelId`. */
+  resolveLocus(conversationId: string): string | null {
+    const home = this.homeChannelResolver?.(conversationId);
+    return home ?? this.activeChannelResolver?.(conversationId) ?? this.defaultPublishChannel ?? null;
+  }
+
   async routeSpeech(
     conversationId: string,
     text: string,
+    /** Pin the outbound locus, skipping resolution. Callers delivering MULTIPLE
+     *  segments of ONE turn snapshot resolveLocus() once and pass it here, so a
+     *  new turn starting mid-dispatch (segments run after the agent is idle,
+     *  PR #32) can't overwrite the per-agent triggering channel between segments
+     *  and split one reply across channels. */
+    overrideChannelId?: string | null,
   ): Promise<{ delivered: boolean; channelId: string } | null> {
     // Surface a routing failure: emit a trace AND notify the host (which drops
     // a `[discord-send-failed]` marker into chronicle) so the agent learns her
@@ -1153,9 +1186,7 @@ export class ChannelRegistry {
     // Using the global for a fork or a concurrent trunk turn is the item-3 bug:
     // it tracks the most-recent inbound across ALL channels, so a reply lands
     // wherever a message last happened to arrive rather than where it belongs.
-    const home = this.homeChannelResolver?.(conversationId);
-    const channelId =
-      home ?? this.activeChannelResolver?.(conversationId) ?? this.defaultPublishChannel;
+    const channelId = overrideChannelId ?? this.resolveLocus(conversationId);
     if (!channelId) {
       // Reached only when the agent has no home, no active triggering channel,
       // AND no global inbound was ever seen.

package/src/mcpl/push-handler.ts

@@ -171,12 +171,16 @@ export class PushHandler {
       const reason = err instanceof McplFeatureSetError
         ? err.message
         : 'Feature set validation failed';
+      // Loud rejection — a rejected push event is an agent that silently
+      // never hears the message. (2026-07-09 diagnosability pass.)
+      console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=${reason}`);
       responder?.respond({ accepted: false, reason });
       return;
     }
 
     // 2. Deduplicate by eventId
     if (this.dedup.checkAndAdd(params.eventId)) {
+      console.error(`[push-event-rejected] server=${serverId} eventId=${params.eventId} reason=duplicate`);
       responder?.respond({ accepted: false, reason: 'duplicate' });
       return;
     }

package/src/mcpl/server-connection.ts

@@ -46,6 +46,13 @@ import { McplMethod } from './types.js';
  *  Spring Boot + JDA servers can take 5-10s to boot, so 30s is safe. */
 const INITIALIZE_TIMEOUT_MS = 30_000;
 
+/** Default per-request timeout in milliseconds (see McplServerConfig.requestTimeoutMs).
+ *  A live-but-wedged server (accepts requests, never answers, never closes its
+ *  transport) would otherwise freeze the awaiting agent turn forever — no
+ *  endTurn, no further wakes, zero errors anywhere. 60s is generous for real
+ *  tool work while still bounding the hang. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+
 /** MCP protocol version used in the initialize handshake. */
 const MCP_PROTOCOL_VERSION = '2024-11-05';
 
@@ -56,6 +63,8 @@ interface PendingRequest {
   resolve: (result: unknown) => void;
   reject: (error: Error) => void;
   method: string;
+  /** Per-request timeout timer; cleared on response/close/timeout. */
+  timer?: ReturnType<typeof setTimeout>;
 }
 
 /**
@@ -73,6 +82,9 @@ interface PendingRequest {
  * - `'feature-sets-changed'` — Server sent `featureSets/changed`
  * - `'error'`              — Connection-level error
  * - `'close'`              — Connection closed
+ * - `'connect-failed'`     — Initial connect failed; background retry scheduled
+ * - `'reconnect-failed'`   — A background reconnect attempt failed; next retry scheduled
+ * - `'reconnect'`          — Background reconnect succeeded
  */
 export class McplServerConnection extends EventEmitter {
   /** Unique server identifier from config. */
@@ -84,10 +96,20 @@ export class McplServerConnection extends EventEmitter {
   /** The active transport (stdio child or WebSocket). Null for a disconnected
    *  stub awaiting its first background reconnect. */
   private transport: McplTransport | null;
+
+  /** Whether the connection currently has a live transport. False for closed
+   *  connections and disconnected reconnect-stubs awaiting a retry. */
+  get isConnected(): boolean {
+    return !this.closed && this.transport !== null;
+  }
+
   private nextRequestId = 1;
   private pendingRequests = new Map<string | number, PendingRequest>();
   private closed = false;
 
+  /** Per-request timeout in ms (0 disables). See McplServerConfig.requestTimeoutMs. */
+  private requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
+
   // Event buffering: events emitted before ready() are queued, not lost
   private readyFlag = false;
   private bufferedEvents: Array<{ event: string; args: unknown[] }> = [];
@@ -97,7 +119,17 @@ export class McplServerConnection extends EventEmitter {
   private hostCapabilities: McplHostCapabilities | null = null;
   private reconnectEnabled = false;
   private reconnectIntervalMs = 5000;
+  private reconnectMaxIntervalMs = 300_000;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Consecutive failed connect attempts since the last successful handshake.
+   *  Drives the exponential backoff and is reported on reconnect events. */
+  private reconnectAttempts = 0;
+
+  /** Whether a background reconnect loop will revive this connection after a
+   *  drop. False once close() has been called (explicit close stops retrying). */
+  get willReconnect(): boolean {
+    return this.reconnectEnabled;
+  }
 
   /**
    * Private constructor. Use `McplServerConnection.connect()` instead.
@@ -167,6 +199,7 @@ export class McplServerConnection extends EventEmitter {
     const { transport, capabilities } = await McplServerConnection.handshake(config, hostCapabilities);
 
     const connection = new McplServerConnection(config.id, capabilities, transport);
+    connection.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
 
     // Store config for reconnection
     if (config.reconnect) {
@@ -174,6 +207,7 @@ export class McplServerConnection extends EventEmitter {
       connection.hostCapabilities = hostCapabilities;
       connection.reconnectEnabled = true;
       connection.reconnectIntervalMs = config.reconnectIntervalMs ?? 5000;
+      connection.reconnectMaxIntervalMs = config.reconnectMaxIntervalMs ?? 300_000;
     }
 
     return connection;
@@ -281,7 +315,12 @@ export class McplServerConnection extends EventEmitter {
 
       // Non-blocking start: create a disconnected stub that will reconnect in background
       console.error(`MCPL server "${config.id}" initial connect failed, will retry:`, (error as Error).message);
-      return McplServerConnection.createDisconnectedStub(config, hostCapabilities);
+      const stub = McplServerConnection.createDisconnectedStub(config, hostCapabilities);
+      // Surface the initial failure. The event is buffered by the emit()
+      // override until the host wires listeners and calls ready(), so it is
+      // not lost in the window before wireMcplEvents runs.
+      stub.emit('connect-failed', { error: (error as Error).message, attempt: 0 });
+      return stub;
     }
   }
 
@@ -297,10 +336,13 @@ export class McplServerConnection extends EventEmitter {
     // Null transport — the stub is closed until its first background reconnect.
     const stub = new McplServerConnection(config.id, null, null);
     stub.closed = true;
+    stub.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     stub.config = config;
     stub.hostCapabilities = hostCapabilities;
     stub.reconnectEnabled = true;
     stub.reconnectIntervalMs = config.reconnectIntervalMs ?? 5000;
+    stub.reconnectMaxIntervalMs = config.reconnectMaxIntervalMs ?? 300_000;
+    stub.reconnectAttempts = 1; // the initial connect already failed
 
     // Schedule background reconnect
     stub.scheduleReconnect();
@@ -441,6 +483,7 @@ export class McplServerConnection extends EventEmitter {
 
     // Reject all pending requests
     for (const [id, pending] of this.pendingRequests) {
+      if (pending.timer) clearTimeout(pending.timer);
       pending.reject(new Error(`Connection to MCPL server "${this.id}" closed while awaiting response for ${pending.method} (id=${id})`));
     }
     this.pendingRequests.clear();
@@ -457,14 +500,26 @@ export class McplServerConnection extends EventEmitter {
 
   /**
    * Schedule a background reconnection attempt.
+   *
+   * Delay grows exponentially with consecutive failures (base
+   * `reconnectIntervalMs`, doubling per failure, capped at
+   * `reconnectMaxIntervalMs`) with ±25% jitter so a fleet of servers that
+   * died together doesn't thundering-herd the same instant. The counter
+   * resets on a successful handshake, so a later disconnect starts over at
+   * the base interval.
    */
   private scheduleReconnect(): void {
     if (!this.reconnectEnabled || this.reconnectTimer) return;
 
+    const exponent = Math.max(0, Math.min(this.reconnectAttempts - 1, 30));
+    const uncapped = this.reconnectIntervalMs * 2 ** exponent;
+    const capped = Math.min(uncapped, this.reconnectMaxIntervalMs);
+    const delay = capped * (0.75 + Math.random() * 0.5);
+
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       this.attemptReconnect();
-    }, this.reconnectIntervalMs);
+    }, delay);
   }
 
   /**
@@ -476,6 +531,10 @@ export class McplServerConnection extends EventEmitter {
   private async attemptReconnect(): Promise<void> {
     if (!this.reconnectEnabled || !this.config || !this.hostCapabilities) return;
 
+    // Ordinal of this attempt: 0 was the initial connect, so the Nth retry
+    // reports attempt N (reconnectAttempts counts failures so far).
+    const attempt = Math.max(1, this.reconnectAttempts);
+
     try {
       const { transport, capabilities } = await McplServerConnection.handshake(
         this.config,
@@ -494,9 +553,12 @@ export class McplServerConnection extends EventEmitter {
       this.readyFlag = true;
 
       console.error(`MCPL server "${this.id}" reconnected successfully`);
-      this.emit('reconnect');
+      this.reconnectAttempts = 0;
+      this.emit('reconnect', { attempts: attempt });
     } catch (error) {
       console.error(`MCPL server "${this.id}" reconnect failed:`, (error as Error).message);
+      this.reconnectAttempts = attempt + 1;
+      this.emit('reconnect-failed', { error: (error as Error).message, attempt });
       this.scheduleReconnect();
     }
   }
@@ -508,6 +570,13 @@ export class McplServerConnection extends EventEmitter {
   /**
    * Send a JSON-RPC request and return a promise that resolves with the result
    * or rejects with a JSON-RPC error.
+   *
+   * Every request carries a timeout (default 60s, configurable via
+   * McplServerConfig.requestTimeoutMs, 0 disables): a live-but-stuck server
+   * that accepts a request and never answers rejects the pending promise with
+   * a descriptive error instead of freezing the caller forever. For tools/call
+   * the framework maps the rejection to an isError tool_result, so a hung tool
+   * surfaces as a normal tool error and the turn completes.
    */
   private sendRequest(method: string, params: Record<string, unknown>): Promise<unknown> {
     if (this.closed) {
@@ -523,7 +592,23 @@ export class McplServerConnection extends EventEmitter {
     };
 
     return new Promise((resolve, reject) => {
-      this.pendingRequests.set(id, { resolve, reject, method });
+      const pending: PendingRequest = { resolve, reject, method };
+      if (this.requestTimeoutMs > 0) {
+        pending.timer = setTimeout(() => {
+          this.pendingRequests.delete(id);
+          reject(new Error(
+            `MCPL server "${this.id}" did not respond to ${method} (id=${id}) ` +
+            `within ${this.requestTimeoutMs}ms — the server may be hung. ` +
+            `The request was abandoned; the connection remains open. Note the ` +
+            `tool may still have completed server-side (this is only a response ` +
+            `timeout, not a cancellation) — verify state before retrying, as a ` +
+            `blind retry of a stateful/side-effecting tool may duplicate it.`,
+          ));
+        }, this.requestTimeoutMs);
+        // Don't hold the event loop open for the watchdog alone.
+        pending.timer.unref?.();
+      }
+      this.pendingRequests.set(id, pending);
       this.transport!.writeLine(JSON.stringify(request));
     });
   }
@@ -626,10 +711,30 @@ export class McplServerConnection extends EventEmitter {
   private handleResponse(response: JsonRpcResponse): void {
     const pending = this.pendingRequests.get(response.id);
     if (!pending) {
+      // Orphaned response — the request already timed out (or was settled) and
+      // was removed from pendingRequests. Stateless late results are harmless to
+      // drop, but a late STATEFUL result carries a `state`/`checkpoint` the
+      // server has already advanced to: dropping it silently diverges the host's
+      // checkpoint tree from the server's, and every subsequent call then sends
+      // stale state. We can't safely re-inject it here (the dispatch context is
+      // gone), but we surface it so the divergence is greppable instead of
+      // invisible.
+      const result = response.result;
+      if (result && typeof result === 'object') {
+        const r = result as { state?: unknown; checkpoint?: unknown };
+        if (r.state !== undefined || r.checkpoint !== undefined) {
+          this.emit('orphaned-response', {
+            id: response.id,
+            hadState: r.state !== undefined,
+            hadCheckpoint: r.checkpoint !== undefined,
+          });
+        }
+      }
       return; // Orphaned response — ignore
     }
 
     this.pendingRequests.delete(response.id);
+    if (pending.timer) clearTimeout(pending.timer);
 
     if (response.error) {
       pending.reject(
@@ -682,6 +787,7 @@ export class McplServerConnection extends EventEmitter {
 
         // Reject all pending requests
         for (const [id, pending] of this.pendingRequests) {
+          if (pending.timer) clearTimeout(pending.timer);
           pending.reject(
             new Error(
               `MCPL server "${this.id}" disconnected unexpectedly (code=${info.code ?? 'n/a'}, signal=${info.signal ?? 'n/a'}, reason=${info.reason ?? 'unknown'}) while awaiting ${pending.method} (id=${id})`,

package/src/mcpl/types.ts

@@ -234,11 +234,29 @@ export interface McplServerConfig {
   reconnect?: boolean;
 
   /**
-   * Interval between reconnection attempts in milliseconds.
+   * Base interval between reconnection attempts in milliseconds.
+   * The actual delay doubles with each consecutive failure (with ±25% jitter)
+   * up to `reconnectMaxIntervalMs`, and resets after a successful handshake.
    * Default: 5000 (5 seconds).
    */
   reconnectIntervalMs?: number;
 
+  /**
+   * Ceiling for the exponential reconnect backoff in milliseconds.
+   * Default: 300000 (5 minutes).
+   */
+  reconnectMaxIntervalMs?: number;
+
+  /**
+   * Per-request timeout in milliseconds for outbound JSON-RPC requests
+   * (tools/call, tools/list, channels/*, hooks). A live-but-stuck server that
+   * accepts a request and never responds would otherwise freeze the awaiting
+   * agent turn forever; with the timeout the pending request rejects with a
+   * descriptive error, which the framework surfaces as a normal isError
+   * tool_result. Set 0 to disable. Default: 60000 (60 seconds).
+   */
+  requestTimeoutMs?: number;
+
   /**
    * Optional callback to filter which incoming channel messages should trigger
    * agent inference. Receives the text content and message metadata.

package/src/module-registry.ts

@@ -27,6 +27,25 @@ import type { Agent } from './agent.js';
 
 const MODULE_STATE_PREFIX = 'modules/';
 
+/**
+ * True when a registerState failure means "this state id already exists" —
+ * the one failure that is safe to swallow on an idempotent re-registration.
+ * Anything else (closed store, IO error) must propagate: swallowing it defers
+ * the real error to a later write with far worse context.
+ */
+export function isStateExistsError(err: unknown): boolean {
+  return err instanceof Error && err.message.includes('State already exists');
+}
+
+/**
+ * Hard ceiling for a single module's gatherContext budget, regardless of the
+ * `contextTimeoutMs` it declares. gatherContext runs on the critical path of
+ * every inference turn, so an unbounded self-declared budget would let one
+ * wedged module stall every agent. 30s is generous for legitimate work (e.g. a
+ * retrieval module's sequential LLM calls) while keeping the worst case bounded.
+ */
+const MAX_CONTEXT_TIMEOUT_MS = 30_000;
+
 /**
  * Registered speech handler.
  */
@@ -302,20 +321,44 @@ export class ModuleRegistry {
   /**
    * Gather context injections from all modules before inference.
    * Calls each module's gatherContext() in parallel with a per-module timeout.
-   * Fail-open: timed-out or erroring modules are skipped silently.
+   * Fail-open: timed-out or erroring modules are skipped (with a stderr line).
+   *
+   * The per-module budget is `module.contextTimeoutMs` when declared, else the
+   * `timeoutMs` default (15s). Modules whose gatherContext does real work —
+   * e.g. a retrieval module making sequential LLM calls with backoff — should
+   * declare a larger `contextTimeoutMs` rather than silently losing their
+   * injection every turn to the shared default. The declared value is clamped
+   * to MAX_CONTEXT_TIMEOUT_MS so no single module can hold every turn hostage.
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
    */
-  async gatherContext(agentName: string, timeoutMs = 5000): Promise<ContextInjection[]> {
+  async gatherContext(agentName: string, timeoutMs = 15_000): Promise<ContextInjection[]> {
     const injections: ContextInjection[] = [];
     const promises: Promise<void>[] = [];
 
     for (const module of this.modules.values()) {
       if (!module.gatherContext) continue;
 
+      // Clamp the per-module budget. A module declaring `contextTimeoutMs`
+      // legitimately needs more than the shared default (e.g. a retrieval
+      // module doing sequential LLM calls), but it must not be able to hold
+      // EVERY inference turn of EVERY agent hostage: the fail-open contract is
+      // "a wedged module never blocks inference for long", so cap the wait.
+      const budgetMs = Math.min(
+        module.contextTimeoutMs ?? timeoutMs,
+        MAX_CONTEXT_TIMEOUT_MS,
+      );
+      let timer: ReturnType<typeof setTimeout> | undefined;
       const promise = Promise.race([
         module.gatherContext(agentName).then(r => injections.push(...r)),
-        new Promise<void>((_, rej) => setTimeout(() => rej(new Error('timeout')), timeoutMs)),
-      ]).catch(err => console.error(`[${module.name}] gatherContext:`, err));
+        new Promise<void>((_, rej) => {
+          timer = setTimeout(
+            () => rej(new Error(`gatherContext timed out after ${budgetMs}ms`)),
+            budgetMs,
+          );
+        }),
+      ])
+        .catch(err => console.error(`[${module.name}] gatherContext:`, err))
+        .finally(() => clearTimeout(timer));
 
       promises.push(promise as Promise<void>);
     }
@@ -435,6 +478,72 @@ class ModuleContextImpl implements ModuleContext {
     this.store.setStateJson(this.stateId, fullState);
   }
 
+  /** Log-state names this context has registered (registerLogState is
+   *  contract-required in start(), so this is populated before any use). */
+  private registeredLogStates = new Set<string>();
+
+  private logStateId(name: string): string {
+    if (!name || name === 'state' || name.includes('/')) {
+      throw new Error(
+        `Invalid module log state name '${name}': must be non-empty, not 'state', and contain no '/'`
+      );
+    }
+    return `${MODULE_STATE_PREFIX}${this.moduleName}/${name}`;
+  }
+
+  /**
+   * Like logStateId, but only for names that went through registerLogState.
+   * Chronicle happily appends to an unregistered state — it just never gets a
+   * snapshot strategy, so every reconstruction replays the full op chain from
+   * record one. A forgotten registration or a typo'd name in one call site
+   * must be an immediate, attributable error, not a silent O(n²)-read trap.
+   */
+  private registeredLogStateId(name: string): string {
+    if (!this.registeredLogStates.has(name)) {
+      throw new Error(
+        `Module log state '${name}' is not registered for module '${this.moduleName}' — ` +
+        `call registerLogState('${name}') in start() before using it`
+      );
+    }
+    return this.logStateId(name);
+  }
+
+  registerLogState(
+    name: string,
+    opts?: { deltaSnapshotEvery?: number; fullSnapshotEvery?: number }
+  ): void {
+    const id = this.logStateId(name);
+    try {
+      this.store.registerState({
+        id,
+        strategy: 'append_log',
+        deltaSnapshotEvery: opts?.deltaSnapshotEvery ?? 100,
+        fullSnapshotEvery: opts?.fullSnapshotEvery ?? 20,
+      });
+    } catch (err) {
+      if (!isStateExistsError(err)) throw err;
+      // Already registered (previous run) — idempotent path.
+    }
+    this.registeredLogStates.add(name);
+  }
+
+  appendToLog<T>(name: string, item: T): void {
+    this.store.appendToStateJson(this.registeredLogStateId(name), item);
+  }
+
+  editLogItem<T>(name: string, index: number, item: T): void {
+    this.store.editStateItem(this.registeredLogStateId(name), index, Buffer.from(JSON.stringify(item)));
+  }
+
+  getLog<T>(name: string): T[] {
+    const data = this.store.getStateJson(this.registeredLogStateId(name));
+    return Array.isArray(data) ? (data as T[]) : [];
+  }
+
+  getLogLength(name: string): number {
+    return this.store.getStateLen(this.registeredLogStateId(name)) ?? 0;
+  }
+
   getModule<T extends Module>(name: string): T | null {
     return this.registry.getModule<T>(name);
   }

package/src/types/agent.ts

@@ -45,6 +45,22 @@ export interface AgentConfig {
   /** Per-agent context compile budget (input tokens). When unset, the
    *  ContextManager's built-in default (100k) applies. */
   contextBudgetTokens?: number;
+
+  /**
+   * Prompt-cache TTL forwarded to the provider (Anthropic `cache_control.ttl`).
+   * '5m' (provider default) or '1h'. When unset, Membrane's default applies.
+   *
+   * 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
+   * context is re-WRITTEN to cache on nearly every call. Cache writes carry a
+   * premium (1.25x base input for 5m, 2x for 1h) while reads cost 0.1x — so a
+   * 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,
+   * where the cheaper write premium wins.
+   */
+  cacheTtl?: '5m' | '1h';
   /**
    * Extended thinking config. When `enabled: true`, the agent runs with
    * Anthropic's native extended thinking; responses include `thinking` blocks
@@ -63,6 +79,28 @@ export interface AgentConfig {
      */
     display?: 'summarized' | 'omitted';
   };
+  /**
+   * How to handle a model content-policy refusal (`stop_reason: refusal`).
+   * When `autoRewind` is on, a refused turn triggers an automatic rewind: the
+   * framework redacts the triggering turn (the tool result or message that
+   * tripped the classifier), injects a metadata-only marker in its place (which
+   * carries none of the offending content, so it cannot itself re-trip), and
+   * re-runs — up to `maxRewinds` times before giving up. This keeps the agent
+   * on its own model (no fallback-model substitution) while self-healing around
+   * a poison turn. Default: off (a refusal just surfaces a marker + reaction).
+   */
+  refusalHandling?: {
+    /** Auto-rewind the triggering turn on refusal and retry. Default false. */
+    autoRewind?: boolean;
+    /** Max consecutive rewinds before giving up a turn. Default 3. */
+    maxRewinds?: number;
+    /**
+     * When the rewound turn is a *human* message (not a machine tool result),
+     * announce the withholding on the conversational surface (Discord) rather
+     * than dropping it silently. Default true.
+     */
+    announceHumanTurns?: boolean;
+  };
 }
 
 /**