@animalabs/agent-framework 0.5.4 → 0.5.7

package/src/gate/event-gate.ts

@@ -330,6 +330,20 @@ 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.
+  private sleepUntil = 0;
+  private sleepNote: string | undefined;
+  private sleepSuppressed = 0;
+
+  // Privileged users who may wake the agent through sleep. Hot-reloaded from
+  // privilegedUsersPath on change.
+  private privilegedUsersPath: string | undefined;
+  private privilegedUserIds = new Set<string>();
+  private privilegedMtime = 0;
+  private lastPrivilegedCheck = 0;
+
   // Dependency-injected callbacks
   private emitTrace: (event: TraceEventLike) => void;
   private addMessageFn: (participant: string, content: Array<{ type: 'text'; text: string }>, metadata?: Record<string, unknown>) => unknown;
@@ -342,6 +356,7 @@ export class EventGate {
   constructor(opts: {
     configPath: string;
     initialConfig?: GateConfig;
+    privilegedUsersPath?: string;
     emitTrace: (event: TraceEventLike) => void;
     addMessage: (participant: string, content: Array<{ type: 'text'; text: string }>, metadata?: Record<string, unknown>) => unknown;
     requestInference: (agentName: string, reason: string, source: string) => void;
@@ -350,11 +365,13 @@ export class EventGate {
     now?: () => number;
   }) {
     this.configPath = opts.configPath;
+    this.privilegedUsersPath = opts.privilegedUsersPath;
     this.emitTrace = opts.emitTrace;
     this.addMessageFn = opts.addMessage;
     this.requestInferenceFn = opts.requestInference;
     this.getAgentNamesFn = opts.getAgentNames;
     this.now = opts.now ?? (() => Date.now());
+    this.loadPrivileged();
 
     // Seed or reconcile the on-disk config.
     //
@@ -597,6 +614,35 @@ export class EventGate {
   evaluate(info: GateEventInfo): GateDecision {
     this.reloadIfChanged();
 
+    // Sleep suppression: while asleep, drop EXTERNAL wakes. Two things still
+    // 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).
+    if (this.sleepUntil > this.now()) {
+      this.reloadPrivilegedIfChanged();
+      const isHeartbeat =
+        info.metadata?.source === 'heartbeat' || info.serverId === 'heartbeat';
+      const authorId = this.extractAuthorId(info.metadata);
+      const privileged = authorId !== null && this.privilegedUserIds.has(authorId);
+      if (!isHeartbeat && !privileged) {
+        this.sleepSuppressed++;
+        this.totalEvaluations++;
+        this.emitTrace({
+          type: 'gate:decision',
+          eventType: info.eventType,
+          serverId: info.serverId || undefined,
+          channelId: info.channelId || undefined,
+          matchedPolicy: 'asleep',
+          trigger: false,
+          behavior: 'skip',
+          timestamp: this.now(),
+        });
+        return { trigger: false, policyName: 'asleep', behavior: 'skip' };
+      }
+      // Privileged author — fall through to normal policy evaluation.
+    }
+
     const policy = this.matchPolicy(info);
     const decision = this.computeDecision(policy, info);
 
@@ -927,9 +973,93 @@ export class EventGate {
   // Tool: gate:status
   // =========================================================================
 
+  // =========================================================================
+  // Sleep
+  // =========================================================================
+
+  /** Begin (or extend) a sleep window of `seconds`. Returns the wake time. */
+  setSleep(seconds: number, note?: string): { until: number } {
+    const ms = Math.max(0, Math.floor(seconds * 1000));
+    this.sleepUntil = this.now() + ms;
+    this.sleepNote = note;
+    this.sleepSuppressed = 0;
+    this.reloadPrivilegedIfChanged();
+    this.emitTrace({
+      type: 'gate:decision',
+      eventType: 'sleep:set',
+      matchedPolicy: 'asleep',
+      trigger: false,
+      behavior: 'skip',
+      timestamp: this.now(),
+    });
+    return { until: this.sleepUntil };
+  }
+
+  /** End sleep immediately. Returns true if the agent was asleep. */
+  clearSleep(): boolean {
+    const wasAsleep = this.sleepUntil > this.now();
+    this.sleepUntil = 0;
+    this.sleepNote = undefined;
+    return wasAsleep;
+  }
+
+  /** Current sleep state, or null if awake. */
+  getSleepState(): { until: number; remainingMs: number; note?: string; suppressed: number } | null {
+    const remainingMs = this.sleepUntil - this.now();
+    if (remainingMs <= 0) return null;
+    return { until: this.sleepUntil, remainingMs, note: this.sleepNote, suppressed: this.sleepSuppressed };
+  }
+
+  /** Author id from an event's metadata, across the discord ingest shapes. */
+  private extractAuthorId(metadata?: Record<string, unknown>): string | null {
+    if (!metadata) return null;
+    const author = metadata.author as { id?: unknown } | undefined;
+    if (author && author.id != null) return String(author.id);
+    if (metadata.authorId != null) return String(metadata.authorId);
+    return null;
+  }
+
+  /** Load the privileged-users file (bare array or { userIds: [...] }). */
+  private loadPrivileged(): void {
+    if (!this.privilegedUsersPath) return;
+    try {
+      if (!existsSync(this.privilegedUsersPath)) {
+        this.privilegedUserIds = new Set();
+        this.privilegedMtime = 0;
+        return;
+      }
+      this.privilegedMtime = statSync(this.privilegedUsersPath).mtimeMs;
+      const raw = JSON.parse(readFileSync(this.privilegedUsersPath, 'utf8'));
+      const ids = Array.isArray(raw) ? raw : Array.isArray(raw?.userIds) ? raw.userIds : [];
+      this.privilegedUserIds = new Set(ids.map((x: unknown) => String(x)));
+    } catch (err) {
+      this.configErrors.push(
+        `Failed to load privileged-users file: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /** Throttled mtime-based reload of the privileged-users file. */
+  private reloadPrivilegedIfChanged(): void {
+    if (!this.privilegedUsersPath) return;
+    const now = this.now();
+    if (now - this.lastPrivilegedCheck < RELOAD_THROTTLE_MS) return;
+    this.lastPrivilegedCheck = now;
+    try {
+      if (!existsSync(this.privilegedUsersPath)) {
+        if (this.privilegedUserIds.size > 0) this.privilegedUserIds = new Set();
+        return;
+      }
+      const mtime = statSync(this.privilegedUsersPath).mtimeMs;
+      if (mtime !== this.privilegedMtime) this.loadPrivileged();
+    } catch {
+      /* leave the last-known set in place on a transient stat/read error */
+    }
+  }
+
   getToolDefinition(): ToolDefinition {
     return {
-      name: 'gate:status',
+      name: 'gate_status',
       description: 'Show the current EventGate configuration, per-policy match counts, debounce state, and any config errors.',
       inputSchema: {
         type: 'object',
@@ -976,7 +1106,20 @@ export class EventGate {
     const byEventType: Record<string, { triggered: number; skipped: number }> = {};
     for (const [k, v] of this.defaultByEventType) byEventType[k] = { ...v };
 
+    const sleepState = this.getSleepState();
+
     return {
+      ...(sleepState
+        ? {
+            sleep: {
+              until: sleepState.until,
+              remainingMs: sleepState.remainingMs,
+              note: sleepState.note,
+              suppressed: sleepState.suppressed,
+              privilegedCount: this.privilegedUserIds.size,
+            },
+          }
+        : {}),
       configPath: this.configPath,
       configSource: this.configSource,
       lastReloadTimestamp: this.lastReloadTimestamp,

package/src/gate/types.ts

@@ -129,6 +129,13 @@ export interface GateOptions {
   configPath?: string;
   /** Initial config, seeded to gate.json if the file doesn't exist. */
   config?: GateConfig;
+  /**
+   * Path to a JSON file listing user ids that may wake the agent even while
+   * it is asleep (`sleep` tool). The file is either a bare array of id
+   * strings or `{ "userIds": [...] }`. Hot-reloaded on change. When unset or
+   * missing, no one bypasses sleep.
+   */
+  privilegedUsersPath?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -202,4 +209,14 @@ export interface GateStatus {
     skipped: number;
     byEventType: Record<string, { triggered: number; skipped: number }>;
   };
+  /** Present when the agent is currently asleep (sleep tool). */
+  sleep?: {
+    until: number;
+    remainingMs: number;
+    note?: string;
+    /** How many wake events have been suppressed during the current sleep. */
+    suppressed: number;
+    /** Count of privileged user ids that may wake through sleep. */
+    privilegedCount: number;
+  };
 }

package/src/index.ts

@@ -63,6 +63,18 @@ export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior
 // MCPL channel registry (exposed for modules that need channel-level operations)
 export { ChannelRegistry } from './mcpl/index.js';
 
+// Per-channel conversation routing
+export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './mcpl/index.js';
+export type {
+  ConversationRouterConfig,
+  ConversationBinding,
+  RoutingDecision,
+  IncomingMessageFacts,
+  BindRule,
+  TriggerRule,
+  ChannelKind,
+} from './mcpl/index.js';
+
 // Re-export commonly used types from dependencies
 export type { ContextManager, ContextStrategy, TokenBudget } from '@animalabs/context-manager';
 export { PassthroughStrategy, AutobiographicalStrategy, KnowledgeStrategy } from '@animalabs/context-manager';

package/src/mcpl/channel-registry.ts

@@ -174,6 +174,43 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
       required: [],
     },
   },
+  {
+    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.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        content: {
+          type: 'string',
+          description: 'Your private thought / reasoning (optional; not sent anywhere).',
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'skip_reply',
+    description:
+      'End your turn WITHOUT sending anything to any channel or surface. Use when you have ' +
+      'read the messages but deliberately choose not to reply right now — ambient chatter, ' +
+      'nothing to add, or you are waiting. Any plain text you wrote this turn stays private ' +
+      'and is NOT posted. To reply instead, just write plain text (no tool call).',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        reason: {
+          type: 'string',
+          description: 'Optional private note on why you are not replying (not sent anywhere).',
+        },
+      },
+      required: [],
+    },
+  },
 ];
 
 // ============================================================================
@@ -183,6 +220,20 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
 interface ChannelRegistryOptions {
   /** Callback to determine whether an incoming message should trigger inference. */
   shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
+  /**
+   * Called when a text-only turn's speech could NOT be delivered to its
+   * conversational locus — no locus, an unregistered channel, a missing
+   * server, or the server reporting `delivered: false`. The host wires this
+   * to drop a `[discord-send-failed]` marker into chronicle so the failure is
+   * visible to the agent (and operator) rather than silently lost. Must not
+   * itself trigger inference (avoid wake loops).
+   */
+  onRouteFailure?: (info: {
+    conversationId: string;
+    channelId: string | null;
+    reason: string;
+    textLen: number;
+  }) => void;
 }
 
 // ============================================================================
@@ -201,6 +252,12 @@ export class ChannelRegistry {
     op?: 'start' | 'stop',
   ) => void;
   private shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
+  private onRouteFailure?: (info: {
+    conversationId: string;
+    channelId: string | null;
+    reason: string;
+    textLen: number;
+  }) => void;
 
   /** Registered channels, keyed by `{serverId}:{channelId}`. */
   private channels = new Map<string, ChannelEntry>();
@@ -246,6 +303,7 @@ export class ChannelRegistry {
     this.emitTraceFn = emitTraceFn;
     this.sendTypingFn = options?.sendTypingFn;
     this.shouldTriggerInference = options?.shouldTriggerInference;
+    this.onRouteFailure = options?.onRouteFailure;
   }
 
   /**
@@ -372,6 +430,43 @@ export class ChannelRegistry {
       this.defaultPublishMessageId = message.messageId;
       this.defaultPublishThreadId = message.threadId;
 
+      // Lazy-register the channel if we've never seen it. A channel can deliver
+      // an incoming message before its channels/register (boot enumeration) or
+      // channels/changed (post-boot create / View-permission grant) round-trip
+      // lands — or the registration event can be missed entirely (e.g. the bot
+      // gains visibility in a way that fires neither `channelCreate` nor a
+      // View-permission transition). Without a registry entry, routeSpeech()
+      // can't resolve this channel as an outbound locus and the agent's reply
+      // is silently dropped, even though this very message proves the channel
+      // is reachable. The inbound message carries enough to make it publishable,
+      // so register it here; a later authoritative channels/register or
+      // channels/changed will overwrite this descriptor with the richer one.
+      const incomingKey = `${serverId}:${message.channelId}`;
+      if (!this.channels.has(incomingKey)) {
+        const channelLabel =
+          typeof message.metadata?.channelName === 'string' && message.metadata.channelName
+            ? (message.metadata.channelName as string)
+            : message.channelId;
+        this.channels.set(incomingKey, {
+          serverId,
+          descriptor: {
+            id: message.channelId,
+            type: serverId,
+            label: channelLabel,
+            direction: 'bidirectional',
+            address: message.threadId ? { threadId: message.threadId } : undefined,
+            metadata: { lazyRegistered: true },
+          },
+          open: true,
+        });
+        this.emitTraceFn({
+          type: 'mcpl:channel-lazy-registered',
+          serverId,
+          channelId: message.channelId,
+          label: channelLabel,
+        });
+      }
+
       // Determine whether to trigger inference
       let triggerInference = true;
       if (this.shouldTriggerInference) {
@@ -536,6 +631,14 @@ export class ChannelRegistry {
     return this.defaultPublishChannel;
   }
 
+  /**
+   * Get the descriptor for a channel by its channelId (first match across
+   * servers). Used by the conversation router for DM classification.
+   */
+  getDescriptor(channelId: string): ChannelDescriptor | undefined {
+    return this.findChannelEntry(channelId)?.descriptor;
+  }
+
   /**
    * Get all open channels.
    */
@@ -577,6 +680,12 @@ export class ChannelRegistry {
       case 'channel_publish':
         return this.handleToolPublish(input as { channelId: string; content: string });
 
+      case 'think':
+        return this.handleToolThink(input as { content?: string });
+
+      case 'skip_reply':
+        return this.handleToolSkipReply(input as { reason?: string });
+
       default:
         return { success: false, error: `Unknown channel tool: ${toolName}`, isError: true };
     }
@@ -730,6 +839,11 @@ export class ChannelRegistry {
   // Private: Channel Lookup
   // ==========================================================================
 
+  /** Server id owning a registered channel (by descriptor id), or null. */
+  getChannelServerId(channelId: string): string | null {
+    return this.findChannelEntry(channelId)?.serverId ?? null;
+  }
+
   /**
    * Find a channel entry by channelId (searches across all servers).
    * Returns the first match.
@@ -874,6 +988,113 @@ export class ChannelRegistry {
     }
   }
 
+  /**
+   * Handle the synthesized `think` tool — a private reasoning scratchpad. It
+   * sends nothing, and (unlike before) does NOT silence the turn: trailing
+   * plain text is still routed as the reply. The thought stays in the agent's
+   * own context/chronicle. To deliberately not reply, the agent uses skip_reply.
+   */
+  private handleToolThink(input: { content?: string }): ToolResult {
+    return {
+      success: true,
+      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,
+      },
+    };
+  }
+
+  /**
+   * Handle the synthesized `skip_reply` tool — the deliberate "stay silent"
+   * signal. A no-op as far as any surface is concerned (sends nothing); its
+   * effect is that the framework's output routing treats this as a silencing
+   * tool, so any trailing prose this turn is NOT posted. Replaces the old
+   * overloaded use of `think` for staying silent.
+   */
+  private handleToolSkipReply(input: { reason?: string }): ToolResult {
+    return {
+      success: true,
+      data: {
+        skipped: true,
+        note: 'Ended the turn without replying — nothing was sent to any channel.',
+        reason: typeof input?.reason === 'string' ? input.reason : undefined,
+      },
+    };
+  }
+
+  /**
+   * Host-owned output routing (see forking-knowledge-miner LOCUS-ROUTING-DESIGN).
+   * Publish the agent's plain-text speech to the current conversational locus
+   * (the most recent incoming channel, tracked cross-surface here in the host).
+   * Called by the framework on a text-only turn — replaces the per-surface
+   * sticky auto-post that used to live in discord-mcpl. Returns null when there
+   * is no locus / the channel or its server can't be resolved (in which case
+   * the speech simply stays in chronicle + module surfaces).
+   */
+  async routeSpeech(
+    conversationId: string,
+    text: string,
+  ): 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
+    // reply never reached the human, instead of it vanishing silently.
+    const fail = (channelId: string | null, reason: string): null => {
+      console.error(`[routeSpeech] ${conversationId}: ${reason} — speech NOT routed (${text.length} chars stay in chronicle)`);
+      this.emitTraceFn({
+        type: 'mcpl:speech-route-failed',
+        channelId: channelId ?? '',
+        reason,
+        textLen: text.length,
+      });
+      this.onRouteFailure?.({ conversationId, channelId, reason, textLen: text.length });
+      return null;
+    };
+
+    const channelId = this.defaultPublishChannel;
+    if (!channelId) {
+      return fail(null, 'no locus (defaultPublishChannel null)');
+    }
+
+    const entry = this.findChannelEntry(channelId);
+    if (!entry) {
+      return fail(channelId, `no registered channel for locus "${channelId}"`);
+    }
+
+    const server = this.serverRegistry.getServer(entry.serverId);
+    if (!server) {
+      return fail(channelId, `server "${entry.serverId}" not found`);
+    }
+
+    const publishParams: ChannelsPublishParams = {
+      conversationId,
+      channelId,
+      content: [{ type: 'text', text }],
+    };
+    const result = await server.sendChannelsPublish(publishParams);
+    const delivered = (result as { delivered?: boolean } | undefined)?.delivered ?? true;
+
+    // The server accepted the publish RPC but reported the message was not
+    // actually delivered (e.g. missing Send Messages permission). Previously
+    // this returned `{ delivered: true }`, masking the failure. Surface it.
+    if (delivered === false) {
+      return fail(channelId, `server "${entry.serverId}" reported delivered:false for "${channelId}"`);
+    }
+
+    console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${channelId} (server=${entry.serverId}, delivered=${delivered})`);
+    this.emitTraceFn({
+      type: 'mcpl:speech-routed',
+      serverId: entry.serverId,
+      channelId,
+      delivered,
+      textLen: text.length,
+    });
+
+    return { delivered, channelId };
+  }
+
   private async handleToolPublish(input: { channelId?: string; content?: string; text?: string }): Promise<ToolResult> {
     // Resolve content: accept both `content` and `text` (backward compat)
     const messageText = input.content ?? input.text;