@animalabs/agent-framework 0.23.2 → 0.24.0

package/src/gate/event-gate.ts

@@ -14,6 +14,7 @@
 import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { GateScript } from './gate-script.js';
+import { MAX_TIMER_MS } from '../deadline-timer.js';
 import { safeSlice } from '../safe-slice.js';
 
 import type { ToolDefinition } from '../types/events.js';
@@ -602,6 +603,9 @@ export class EventGate {
   private sleepSuppressed = 0;
   private sleepTimer: ReturnType<typeof setTimeout> | null = null;
   private sleepAgent: string | undefined;
+  // From dispose() to the next resumeSleep(): no sleep or self-wake timer is
+  // armed, though a turn a failed stop() left running can still ask for one.
+  private disposed = false;
 
   // Self-wake timers per agent (skip_reply's wake_in_seconds). Unlike sleep,
   // a self-wake suppresses NOTHING — it means "if nothing else wakes me by
@@ -1048,11 +1052,13 @@ export class EventGate {
     // rouse the agent — its own heartbeat (an internal clock, not an outside
     // interruption: each tick lets the agent reconsider and optionally `wake`)
     // and a privileged user's ping. The event always enters context regardless
-    // (the gate only governs inference triggering).
+    // (the gate only governs inference triggering). The heartbeat is the
+    // server the host knows as `heartbeat`, the server id the silent-heartbeat
+    // marker requires too: a `source` in an event's metadata is the server's
+    // own word, which any server can give.
     if (this.sleepUntil > this.now()) {
       this.reloadPrivilegedIfChanged();
-      const isHeartbeat =
-        info.metadata?.source === 'heartbeat' || info.serverId === 'heartbeat';
+      const isHeartbeat = info.serverId === 'heartbeat';
       const authorId = this.extractAuthorId(info.metadata);
       const privileged = authorId !== null && this.privilegedUserIds.has(authorId);
       if (!isHeartbeat && !privileged) {
@@ -1733,9 +1739,9 @@ export class EventGate {
     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);
+    // tick or an incoming message). Cancelled by clearSleep()/`wake`, and by
+    // dispose(), after which start() arms it again (resumeSleep).
+    this.armSleepWake();
     this.reloadPrivilegedIfChanged();
     this.emitTrace({
       type: 'gate:decision',
@@ -1748,6 +1754,48 @@ export class EventGate {
     return { until: this.sleepUntil };
   }
 
+  /**
+   * Arm timers again for a lifecycle that starts after a stop(), and the
+   * sleep's wake first: dispose() clears its timer and keeps the sleep. A
+   * sleep still ahead wakes the agent at its end; one that ended while
+   * stopped wakes it now, since that wake is what the agent asked for. With
+   * no sleep, wakeFromSleep does nothing.
+   */
+  resumeSleep(): void {
+    this.disposed = false;
+    if (this.sleepUntil > this.now()) this.armSleepWake();
+    else this.wakeFromSleep('sleep-expired');
+  }
+
+  /**
+   * Arm the sleep's wake for its end by the gate's own clock. One timer holds
+   * at most MAX_TIMER_MS, about 24.8 days, so a longer sleep waits in steps,
+   * and wakeFromSleep reads the clock as each one fires. Nothing is armed
+   * while the gate is disposed: resumeSleep() arms it at the next start().
+   */
+  private armSleepWake(): void {
+    if (this.sleepTimer) { clearTimeout(this.sleepTimer); this.sleepTimer = null; }
+    if (this.disposed) return;
+    const remaining = Math.max(0, this.sleepUntil - this.now());
+    this.sleepTimer = setTimeout(() => this.wakeFromSleep('sleep-expired'), Math.min(remaining, MAX_TIMER_MS));
+  }
+
+  /**
+   * `agentName` is gone, as a conversation fork's end or an ephemeral run's
+   * removes one: its pending self-wake is cancelled, and a sleep it set ends.
+   * The gate's sleep holds back every agent's wakes, so nobody is asleep once
+   * its agent is gone, and neither wake would reach a name that no longer
+   * exists. A sleep another agent set, or one set with no agent, stays.
+   */
+  agentGone(agentName: string): void {
+    const selfWake = this.selfWakeTimers.get(agentName);
+    if (selfWake) {
+      clearTimeout(selfWake);
+      this.selfWakeTimers.delete(agentName);
+    }
+    if (this.sleepUntil !== 0 && this.sleepAgent === agentName) this.clearSleep();
+  }
+
   // =========================================================================
   // Self-wake (skip_reply wake_in_seconds)
   // =========================================================================
@@ -1759,8 +1807,11 @@ export class EventGate {
    * Cancelled by the agent's next turn start (see onInferenceStarted):
    * the semantics are "if nothing else wakes me by then, wake me".
    */
-  armSelfWake(agentName: string, seconds: number, source = 'skip_reply'): { inMs: number } {
+  armSelfWake(agentName: string, seconds: number, source = 'skip_reply'): { inMs: number; armed: boolean } {
     const ms = Math.max(1_000, Math.min(3_600_000, Math.floor(seconds * 1000)));
+    // A stopped framework's late turn arms no timer (disposed). A self-wake
+    // doesn't outlive a stop, as dispose() clearing the pending ones says.
+    if (this.disposed) return { inMs: ms, armed: false };
     const prev = this.selfWakeTimers.get(agentName);
     if (prev) clearTimeout(prev);
     const timer = setTimeout(() => {
@@ -1801,7 +1852,7 @@ export class EventGate {
       behavior: 'skip',
       timestamp: this.now(),
     });
-    return { inMs: ms };
+    return { inMs: ms, armed: true };
   }
 
   /** End sleep immediately. Returns true if the agent was asleep. */
@@ -1819,11 +1870,20 @@ export class EventGate {
    * 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.
+   * `wake`). A timer that fires before the sleep's end by the gate's clock
+   * arms the rest: a step of a sleep longer than one timer holds, a timer that
+   * fires early (Node's can, by a millisecond), or a clock set back.
    */
   private wakeFromSleep(reason: string): void {
-    this.sleepTimer = null;
-    if (this.sleepUntil === 0 || this.sleepUntil > this.now()) return;
+    // The timer that called it has fired; from resumeSleep(), for a sleep
+    // already over, one may still be armed, and it goes, so no stale step of
+    // it can fire later.
+    if (this.sleepTimer) { clearTimeout(this.sleepTimer); this.sleepTimer = null; }
+    if (this.sleepUntil === 0) return;
+    if (this.sleepUntil > this.now()) {
+      this.armSleepWake();
+      return;
+    }
     const note = this.sleepNote;
     const agent = this.sleepAgent;
     this.sleepUntil = 0;
@@ -2001,6 +2061,13 @@ export class EventGate {
       clearTimeout(timer);
     }
     this.selfWakeTimers.clear();
+    // The sleep stays, with its note and agent, and its timer goes: fired
+    // after a stop(), its wake reached a framework that had stopped, and the
+    // timer held the process until the sleep's end. The next start() arms it
+    // again (resumeSleep). Until then nothing arms one, nor a self-wake: a
+    // turn a failed stop() left running can still call sleep or skip_reply.
+    if (this.sleepTimer) { clearTimeout(this.sleepTimer); this.sleepTimer = null; }
+    this.disposed = true;
     this.rateLimitBuckets.clear();
     this.passiveSampleCounters.clear();
     this.rateLimitDenied.clear();

package/src/held-writes.ts

@@ -25,9 +25,9 @@ export function heldWriteId(id: MessageId): string | undefined {
 
 /**
  * Whether a row matches `filter` as context-manager's queryMessages matches a
- * stored one. That's its MessageStore's private matchesFilter at 0.14.1, which
- * the package doesn't export, so the rule is copied here, and a test compares
- * the two on the same rows. A row matches the external source, one of the
+ * stored one. That's its MessageStore's private matchesFilter, the same at
+ * 0.14.1, 0.16.0, 0.17.1 and 0.18.0, which the package doesn't export, so the rule is copied
+ * here, and a test compares the two on the same rows. A row matches the external source, one of the
  * external ids (an empty list filters nothing), the participant, and each
  * metadata path, dot-separated, by strict equality.
  */
@@ -57,3 +57,17 @@ function valueAt(value: unknown, path: string): unknown {
   }
   return value;
 }
+
+/**
+ * A row as a module's context answers it: marked `heldFromResidents` when it
+ * carries the stamp a tune-out puts on a message it holds from the residents
+ * (`metadata.tuneOut`). Every resident's viewFilter leaves a stamped row out
+ * of its compiled view (framework.ts, createAgent), and a tool boundary
+ * stores a stamped write without injecting it into the live turn, so a
+ * marked row is one the store keeps and no resident is shown
+ * (ModuleMessage.heldFromResidents says where its text can still reach
+ * one). Any other row comes back as it is.
+ */
+export function asModuleRow<T extends Pick<StoredMessage, 'metadata'>>(row: T): T & { heldFromResidents?: true } {
+  return (row.metadata as { tuneOut?: unknown } | undefined)?.tuneOut ? { ...row, heldFromResidents: true } : row;
+}

package/src/index.ts

@@ -59,23 +59,9 @@ export type {
 // Usage tracking
 export { UsageTracker } from './usage/index.js';
 
-// Client-side programmatic tool calling (code_execution): exposed so external
-// tooling can drive the python runtime the way the framework does (protocol
-// harnesses, runtime smoke tests).
-export {
-  PyRunner,
-  buildInjectedTools,
-  buildCodeExecutionToolDefinition,
-  CODE_EXECUTION_TOOL_NAME,
-  PYTHON_RUNTIME_SOURCE,
-} from './code-execution/index.js';
-export type {
-  InjectedTool,
-  ExecResult,
-  PyRunnerOptions,
-  ScriptToolCallHandler,
-  ScriptToolResult,
-} from './code-execution/index.js';
+// Client-side programmatic tool calling (code_execution): the tool's name,
+// and its definition as an agent reads it.
+export { buildCodeExecutionToolDefinition, CODE_EXECUTION_TOOL_NAME } from './code-execution/index.js';
 export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent } from './usage/index.js';
 
 // EventGate
@@ -84,9 +70,12 @@ export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior
 
 // MCPL channel registry (exposed for modules that need channel-level operations)
 export { ChannelRegistry } from './mcpl/index.js';
+export type { PublishRefusalReason } from './mcpl/index.js';
 
-// Where each accepted inbound item came from (`metadata.inboundSource`)
-export { INBOUND_SOURCE_KEY, readInboundSource, conversationKey } from './mcpl/index.js';
+// Where each accepted inbound item came from (`metadata.inboundSource`), and
+// the digest its delivered and stored bodies are stamped with
+// (`metadata.sourceBodyDigest`, `metadata.storedBodyDigest`)
+export { INBOUND_SOURCE_KEY, readInboundSource, conversationKey, sourceBodyDigest } from './mcpl/index.js';
 export type {
   InboundSource,
   InboundChannelSource,
@@ -150,18 +139,35 @@ export { PassthroughStrategy, AutobiographicalStrategy, KnowledgeStrategy } from
 export type { KnowledgeConfig, PhaseType } from '@animalabs/context-manager';
 export type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock } from '@animalabs/membrane';
 
-// Offline outage recovery and branch-independent Discord awareness markers
+// Offline outage recovery and the Discord awareness-mark ledger
 export {
   DiscordAwarenessOutbox,
+  DiscordAwarenessRefusal,
   DEFAULT_DISCORD_AWARENESS_EMOJI,
   defaultDiscordAwarenessOutboxPath,
   extractDiscordAwarenessRefs,
+  isPermanentDiscordReactionFailure,
+  selectDiscordAwarenessRefs,
 } from './recovery/discord-awareness-outbox.js';
 export type {
+  DiscordAwarenessAction,
   DiscordAwarenessBatch,
-  DiscordAwarenessEntry,
-  DiscordAwarenessOperation,
+  DiscordAwarenessBatchStatus,
+  DiscordAwarenessBatchView,
+  DiscordAwarenessRetractView,
+  DiscordAwarenessView,
+  DiscordAwarenessCancelReceipt,
+  DiscordAwarenessMarks,
+  DiscordAwarenessOutcome,
+  DiscordAwarenessPrepareInput,
+  DiscordAwarenessReactionState,
+  DiscordAwarenessImportedUnsent,
   DiscordAwarenessRef,
+  DiscordAwarenessRequest,
+  DiscordAwarenessRetractReceipt,
+  DiscordAwarenessRetirement,
+  DiscordAwarenessScope,
+  DiscordAwarenessSettlement,
   DiscordSuppressionInterval,
 } from './recovery/discord-awareness-outbox.js';
 // Live operator surgery (rollback / suppress) and its durable action log
@@ -170,7 +176,9 @@ export type {
   OperatorLogEntry,
   OperatorLogInput,
   OperatorRequester,
+  SurgeryMarkerFacts,
   SurgeryMarkerReceipt,
+  SurgeryMarksPreview,
 } from './operator-log.js';
 export { createOfflineRecoveryBranch } from './recovery/offline-branch.js';
 export type {