@animalabs/agent-framework 0.6.6 → 0.6.8

package/src/gate/event-gate.ts

@@ -72,6 +72,10 @@ interface PendingEvent {
    *  of a message the agent may have long since handled. */
   inContext: boolean;
   channelId?: string;
+  /** Human-readable channel name (e.g. Discord channel name) when the event's
+   *  metadata carries one — batched-wake lines render this instead of the raw
+   *  composite channel id. */
+  channelLabel?: string;
 }
 
 interface DebounceState {
@@ -1029,6 +1033,10 @@ export class EventGate {
       timestamp: Date.now(),
       inContext: info.eventType === 'mcpl:channel-incoming' || info.eventType === 'mcpl:push-event',
       channelId: info.channelId || undefined,
+      channelLabel:
+        typeof info.metadata?.channelName === 'string' && info.metadata.channelName
+          ? (info.metadata.channelName as string)
+          : undefined,
     };
 
     const existing = this.debounceTimers.get(policy.name);
@@ -1087,15 +1095,19 @@ export class EventGate {
 
     const lines: string[] = quoted.map(e => `- [${e.policyName}] (${e.eventType}): ${e.content}`);
     if (referenced.length > 0) {
-      const byChannel = new Map<string, { count: number; oldest: number }>();
+      const byChannel = new Map<string, { count: number; oldest: number; label?: string }>();
       for (const e of referenced) {
         const key = e.channelId ?? '(unknown channel)';
-        const entry = byChannel.get(key) ?? { count: 0, oldest: e.timestamp };
+        const entry = byChannel.get(key) ?? { count: 0, oldest: e.timestamp, label: e.channelLabel };
         entry.count += 1;
         entry.oldest = Math.min(entry.oldest, e.timestamp);
+        entry.label = entry.label ?? e.channelLabel;
         byChannel.set(key, entry);
       }
-      for (const [channel, { count, oldest }] of byChannel) {
+      for (const [channelId, { count, oldest, label }] of byChannel) {
+        // Prefer the human-readable name; keep the id parenthesized so the
+        // agent can still address tools that want the composite id.
+        const channel = label ? `#${label} (${channelId})` : channelId;
         const age = Math.round((Date.now() - oldest) / 1000);
         lines.push(
           `- ${count} message${count > 1 ? 's' : ''} in ${channel} ` +

package/src/index.ts

@@ -91,3 +91,23 @@ export type { ContextManager, ContextStrategy, TokenBudget } from '@animalabs/co
 export { PassthroughStrategy, AutobiographicalStrategy, KnowledgeStrategy } from '@animalabs/context-manager';
 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
+export {
+  DiscordAwarenessOutbox,
+  DEFAULT_DISCORD_AWARENESS_EMOJI,
+  defaultDiscordAwarenessOutboxPath,
+  extractDiscordAwarenessRefs,
+} from './recovery/discord-awareness-outbox.js';
+export type {
+  DiscordAwarenessBatch,
+  DiscordAwarenessEntry,
+  DiscordAwarenessOperation,
+  DiscordAwarenessRef,
+  DiscordSuppressionInterval,
+} from './recovery/discord-awareness-outbox.js';
+export { createOfflineRecoveryBranch } from './recovery/offline-branch.js';
+export type {
+  OfflineRecoveryBranchOptions,
+  OfflineRecoveryBranchResult,
+} from './recovery/offline-branch.js';

package/src/mcpl/channel-registry.ts

@@ -228,10 +228,10 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
     name: 'think',
     description:
       'Reason privately. The content stays in your own context and is NOT sent to any ' +
-      'channel or surface. This does NOT end or silence your turn: if you also write ' +
-      'plain text this turn, that text is still posted as your reply. Use think() purely ' +
-      'to work things out before (or instead of) speaking. To deliberately NOT reply this ' +
-      'turn, call skip_reply instead.',
+      'channel or surface. Same-round routing of ordinary text beside think() depends on ' +
+      'your current same_round_think_text_policy; inspect or change it with agent_settings. ' +
+      'Use think() purely to work things out before (or instead of) speaking. To deliberately ' +
+      'NOT reply this turn, call skip_reply instead.',
     inputSchema: {
       type: 'object' as const,
       properties: {
@@ -356,8 +356,10 @@ export class ChannelRegistry {
    *  server keeps getting the same routing hints (e.g. Zulip topic). */
   private typingMetadata = new Map<string, Record<string, unknown>>();
 
-  /** Chronicle-projected desired lifecycle state, keyed by server + channel. */
-  private desiredStates = new Map<string, DesiredChannelState>();
+  /** Chronicle-projected desired lifecycle state, keyed by server + channel.
+   *  Provenance is kept so reconcile can tell a pure default (nobody ever
+   *  decided) from a real decision (agent-tool, invitation-declined, …). */
+  private desiredStates = new Map<string, { state: DesiredChannelState; source: string }>();
 
   /** One-time migration inputs from the retired recipe auto-open policy. */
   private legacyPolicies = new Map<string, 'auto' | 'manual' | string[]>();
@@ -779,7 +781,7 @@ export class ChannelRegistry {
   }
 
   getDesiredState(serverId: string, channelId: string): DesiredChannelState | undefined {
-    return this.desiredStates.get(this.lifecycleKey(serverId, channelId));
+    return this.desiredStates.get(this.lifecycleKey(serverId, channelId))?.state;
   }
 
   /**
@@ -976,7 +978,7 @@ export class ChannelRegistry {
       ) {
         this.desiredStates.set(
           this.lifecycleKey(event.serverId, event.channelId),
-          event.desired,
+          { state: event.desired, source: typeof event.source === "string" ? event.source : "unknown" },
         );
       } else if (event.kind === 'legacy-policy-migrated') {
         this.migratedLegacyPolicies.add(event.serverId);
@@ -995,8 +997,8 @@ export class ChannelRegistry {
     source: string,
   ): void {
     const key = this.lifecycleKey(serverId, channelId);
-    if (this.desiredStates.get(key) === desired) return;
-    this.desiredStates.set(key, desired);
+    if (this.desiredStates.get(key)?.state === desired) return;
+    this.desiredStates.set(key, { state: desired, source });
     this.appendLifecycleEvent({
       kind: 'desired-state',
       serverId,
@@ -1036,7 +1038,16 @@ export class ChannelRegistry {
   }
 
   private ensureInitialDesiredState(serverId: string, channel: ChannelDescriptor): void {
-    if (this.getDesiredState(serverId, channel.id)) return;
+    const existing = this.desiredStates.get(this.lifecycleKey(serverId, channel.id));
+    if (existing) {
+      // A server upgrading its descriptor to initiallyOpen may lift a pure
+      // default — 'default-closed' means nobody ever decided. Real decisions
+      // (agent-tool, invitation-declined, legacy migration, …) always stick.
+      if (channel.initiallyOpen === true && existing.state === 'closed' && existing.source === 'default-closed') {
+        this.setDesiredState(serverId, channel.id, 'open', 'server-bootstrap');
+      }
+      return;
+    }
     this.setDesiredState(
       serverId,
       channel.id,
@@ -1393,12 +1404,14 @@ export class ChannelRegistry {
   private handleToolThink(input: { content?: string }): ToolResult {
     return {
       success: true,
+      // Same echo-avoidance as skip_reply: the thought text is already in the
+      // tool_use block; don't duplicate it in the result.
       data: {
         noted: true,
         note:
-          'Thought recorded (private — not sent anywhere). This did NOT silence your turn: ' +
-          'write plain text to reply, or call skip_reply to end the turn without replying.',
-        content: typeof input?.content === 'string' ? input.content : undefined,
+          'Thought recorded (private — not sent anywhere). Same-round text routing depends on ' +
+          'your current same_round_think_text_policy; use agent_settings get to inspect it, or ' +
+          'call skip_reply to end the turn without replying.',
       },
     };
   }
@@ -1419,10 +1432,12 @@ export class ChannelRegistry {
       // again: observed as a 40+ round skip_reply loop on Fable 5, burning a
       // round-trip + ~70 tokens per iteration until something kills the turn.
       endTurn: true,
+      // Deliberately terse: the agent's `reason` is already in the tool_use
+      // block — echoing it back doubled every skip turn's footprint (observed
+      // on Fable: ~60% of skip_reply result bytes were verbatim input echo).
       data: {
         skipped: true,
-        note: 'Ended the turn without replying — nothing was sent to any channel.',
-        reason: typeof input?.reason === 'string' ? input.reason : undefined,
+        note: 'Turn ended; nothing sent.',
       },
     };
   }

package/src/mcpl/server-connection.ts

@@ -69,6 +69,13 @@ interface PendingRequest {
   timer?: ReturnType<typeof setTimeout>;
 }
 
+interface RequestOptions {
+  /** Override the connection-wide timeout for this request only. */
+  timeoutMs?: number;
+  /** Surface a late response even when it carries no checkpoint state. */
+  surfaceOrphanedResponse?: boolean;
+}
+
 /**
  * McplServerConnection manages a single JSON-RPC 2.0 connection to an
  * MCPL server over stdio. Use the static `connect()` factory to create
@@ -107,13 +114,20 @@ export class McplServerConnection extends EventEmitter {
 
   private nextRequestId = 1;
   private pendingRequests = new Map<string | number, PendingRequest>();
+  /** Metadata retained after selected request deadlines so a late response is
+   * observable even though its original promise has already been rejected. */
+  private orphanedRequests = new Map<string | number, { method: string }>();
   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;
+  // Event buffering: control-plane traffic can be released independently from
+  // inference-bearing data-plane traffic. This lets a server finish its own
+  // registration (and answer host tools/call requests) while startup/reconnect
+  // reconciliation keeps agent wakes behind a durable barrier.
+  private controlPlaneReady = false;
+  private dataPlaneReady = false;
   private bufferedEvents: Array<{ event: string; args: unknown[] }> = [];
 
   // Reconnect state (adapted from Anarchid/agent-framework@mcpl-module-proto)
@@ -162,26 +176,87 @@ export class McplServerConnection extends EventEmitter {
    * the caller has attached listeners via wireMcplEvents).
    */
   ready(): void {
-    this.readyFlag = true;
-    for (const { event, args } of this.bufferedEvents) {
-      super.emit(event, ...args);
+    this.controlPlaneReady = true;
+    this.dataPlaneReady = true;
+    const pending = this.bufferedEvents;
+    this.bufferedEvents = [];
+    for (const { event, args } of pending) {
+      // Re-enter the gate for every buffered item. A control handler (notably
+      // tools/list_changed) may install a newer data-plane barrier while this
+      // snapshot is being flushed; later data items must observe that pause.
+      this.emit(event, ...args);
     }
+  }
+
+  /**
+   * Release only server-establishment and lifecycle/control traffic. Responses
+   * to host requests are never event-buffered, so tools/list and tools/call
+   * responses remain live as well. Inference-bearing requests stay queued in
+   * their original relative order until {@link ready} is called.
+   */
+  readyControlPlane(): void {
+    this.controlPlaneReady = true;
+    const pending = this.bufferedEvents;
+    const deferred: Array<{ event: string; args: unknown[] }> = [];
     this.bufferedEvents = [];
+    for (const item of pending) {
+      if (McplServerConnection.isControlPlaneEvent(item.event)) {
+        super.emit(item.event, ...item.args);
+      } else {
+        deferred.push(item);
+      }
+    }
+    // Data events emitted by control handlers while the snapshot was flushing
+    // were appended to the new buffer. Preserve their order behind older data.
+    this.bufferedEvents = [...deferred, ...this.bufferedEvents];
+  }
+
+  /**
+   * Close the data plane synchronously while leaving an already-released
+   * control plane live. Used before reconnect adoption and list-change
+   * reconciliation so no new inference event can beat barrier installation.
+   */
+  pauseDataPlane(): void {
+    this.dataPlaneReady = false;
   }
 
   /**
-   * Override emit to buffer server→host events until ready() is called.
-   * Lifecycle events ('close', 'error', 'reconnect') always pass through.
+   * Override emit to buffer server→host events until the corresponding plane
+   * is ready. Lifecycle events always pass through so reconnect can install a
+   * new data-plane gate before the fresh transport is exposed.
    */
   override emit(event: string | symbol, ...args: unknown[]): boolean {
     const name = typeof event === 'string' ? event : '';
-    if (this.readyFlag || name === 'close' || name === 'error' || name === 'reconnect') {
+    if (
+      McplServerConnection.isLifecycleEvent(name)
+      || (McplServerConnection.isControlPlaneEvent(name)
+        ? this.controlPlaneReady
+        : this.dataPlaneReady)
+    ) {
       return super.emit(event, ...args);
     }
     this.bufferedEvents.push({ event: name, args });
     return true;
   }
 
+  private static isControlPlaneEvent(event: string): boolean {
+    return event === 'stderr'
+      || event === 'scope-elevate'
+      || event === 'channels-register'
+      || event === 'channels-changed'
+      || event === 'feature-sets-changed'
+      || event === 'tools-list-changed'
+      || event === 'connect-failed'
+      || event === 'reconnect-failed'
+      || event === 'orphaned-response';
+  }
+
+  private static isLifecycleEvent(event: string): boolean {
+    return event === 'close'
+      || event === 'error'
+      || event === 'reconnect';
+  }
+
   // ==========================================================================
   // Static factory
   // ==========================================================================
@@ -473,6 +548,26 @@ export class McplServerConnection extends EventEmitter {
     return this.sendRequest('tools/call', params) as Promise<McpToolCallResult>;
   }
 
+  /**
+   * Send a tools/call with a mandatory request-local deadline. This is used by
+   * durable external-side-effect accounting, whose safety bound must remain in
+   * force even when the server's general requestTimeoutMs is configured as 0.
+   */
+  sendToolsCallWithDeadline(
+    name: string,
+    args: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<McpToolCallResult> {
+    const params: Record<string, unknown> = { name, arguments: args };
+    const mandatoryTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? Math.max(1, Math.floor(timeoutMs))
+      : 1;
+    return this.sendRequest('tools/call', params, {
+      timeoutMs: mandatoryTimeoutMs,
+      surfaceOrphanedResponse: true,
+    }) as Promise<McpToolCallResult>;
+  }
+
   // ==========================================================================
   // Lifecycle
   // ==========================================================================
@@ -497,6 +592,7 @@ export class McplServerConnection extends EventEmitter {
       pending.reject(new Error(`Connection to MCPL server "${this.id}" closed while awaiting response for ${pending.method} (id=${id})`));
     }
     this.pendingRequests.clear();
+    this.orphanedRequests.clear();
 
     // Tear down the transport (kills the child / closes the socket). The
     // transport's own 'close' event is short-circuited by `this.closed` in
@@ -508,6 +604,27 @@ export class McplServerConnection extends EventEmitter {
     this.emit('close');
   }
 
+  /**
+   * Tear down a live transport after an awareness-accounting failure without
+   * disabling configured auto-reconnect. The normal transport close handler
+   * rejects requests, emits lifecycle state, and schedules the next bounded
+   * reconnect attempt. With reconnect disabled this leaves the server closed.
+   */
+  async reconnectAfterFailure(): Promise<void> {
+    this.pauseDataPlane();
+    if (this.closed) {
+      this.scheduleReconnect();
+      return;
+    }
+    if (this.transport) {
+      await this.transport.close();
+      return;
+    }
+    this.closed = true;
+    this.emit('close');
+    this.scheduleReconnect();
+  }
+
   /**
    * Schedule a background reconnection attempt.
    *
@@ -551,16 +668,17 @@ export class McplServerConnection extends EventEmitter {
         this.hostCapabilities,
       );
 
-      // Adopt the new transport. Listeners were attached to external consumers
-      // on the first wire, so mark ready immediately (re-wire re-binds the
-      // transport-level handlers below).
+      // Close the data plane before the new transport can emit. The reconnect
+      // lifecycle event bypasses buffering; its framework listener installs the
+      // awareness barrier synchronously, then releases control traffic needed
+      // to establish the server while data remains held.
+      this.pauseDataPlane();
       this.transport = transport;
       this.capabilities = capabilities;
       this.closed = false;
       this.nextRequestId = 1;
       this.pendingRequests.clear();
       this.wireTransport(transport);
-      this.readyFlag = true;
 
       console.error(`MCPL server "${this.id}" reconnected successfully`);
       this.reconnectAttempts = 0;
@@ -588,7 +706,11 @@ export class McplServerConnection extends EventEmitter {
    * 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> {
+  private sendRequest(
+    method: string,
+    params: Record<string, unknown>,
+    options: RequestOptions = {},
+  ): Promise<unknown> {
     if (this.closed) {
       return Promise.reject(new Error(`Cannot send request: connection to "${this.id}" is closed`));
     }
@@ -603,18 +725,22 @@ export class McplServerConnection extends EventEmitter {
 
     return new Promise((resolve, reject) => {
       const pending: PendingRequest = { resolve, reject, method };
-      if (this.requestTimeoutMs > 0) {
+      const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+      if (timeoutMs > 0) {
         pending.timer = setTimeout(() => {
           this.pendingRequests.delete(id);
+          if (options.surfaceOrphanedResponse) {
+            this.orphanedRequests.set(id, { method });
+          }
           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.`,
+            `within ${timeoutMs}ms — the server may be hung. The response ` +
+            `outcome is unknown: the request was abandoned locally but was not ` +
+            `cancelled, so the tool may still have completed server-side; verify ` +
+            `state before retrying; a blind retry of a stateful/side-effecting ` +
+            `tool may duplicate it.`,
           ));
-        }, this.requestTimeoutMs);
+        }, timeoutMs);
         // Don't hold the event loop open for the watchdog alone.
         pending.timer.unref?.();
       }
@@ -722,23 +848,31 @@ export class McplServerConnection extends EventEmitter {
     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.
+      // was removed from pendingRequests. A late STATEFUL result must be
+      // surfaced because dropping it silently diverges the checkpoint tree.
+      // Selected side-effecting calls are also surfaced even without state so
+      // their outcome-unknown receipt remains visible. We cannot safely
+      // re-inject either result because the original dispatch context is gone.
+      const orphaned = this.orphanedRequests.get(response.id);
+      this.orphanedRequests.delete(response.id);
       const result = response.result;
       if (result && typeof result === 'object') {
         const r = result as { state?: unknown; checkpoint?: unknown };
-        if (r.state !== undefined || r.checkpoint !== undefined) {
+        if (orphaned || r.state !== undefined || r.checkpoint !== undefined) {
           this.emit('orphaned-response', {
             id: response.id,
+            method: orphaned?.method,
             hadState: r.state !== undefined,
             hadCheckpoint: r.checkpoint !== undefined,
           });
         }
+      } else if (orphaned) {
+        this.emit('orphaned-response', {
+          id: response.id,
+          method: orphaned.method,
+          hadState: false,
+          hadCheckpoint: false,
+        });
       }
       return; // Orphaned response — ignore
     }
@@ -805,6 +939,7 @@ export class McplServerConnection extends EventEmitter {
           );
         }
         this.pendingRequests.clear();
+        this.orphanedRequests.clear();
 
         this.emit('close', info.code ?? null, info.signal ?? null);