@animalabs/connectome-host 0.3.10 → 0.5.0

package/src/modules/subscription-gc-module.ts

@@ -21,7 +21,9 @@
  *
  * Config (recipe `modules.subscriptionGc`): `defaultLimitChars` (20000),
  * `serverId` (`discord`), `toolPrefix` (`mcpl--<serverId>`). The agent can
- * override per channel at runtime with `set_channel_idle_limit`.
+ * override per channel at runtime through `agent_settings` (field
+ * `channel_idle_limits`); other modules pin channels open through the
+ * internal `pin_channel_idle_limit` tool.
  */
 
 import type {
@@ -49,7 +51,14 @@ export interface SubscriptionGcConfig {
 type LimitOverride = number | 'off';
 
 interface GcState {
+  /** Agent-set per-channel limits. Cleared by agent_settings reset. */
   overrides: Record<string, LimitOverride>;
+  /** System pins (never auto-close), set by other modules via
+   *  pin_channel_idle_limit — e.g. ChannelModeModule's debounced mode.
+   *  These encode mode invariants, not agent preferences, so
+   *  agent_settings reset leaves them alone; only unpinning (a mode
+   *  change) clears them. A pin wins over any override. */
+  pins: Record<string, true>;
   /** Ambient chars accrued per channel since the last activation. */
   counters: Record<string, number>;
 }
@@ -67,7 +76,7 @@ export class SubscriptionGcModule implements Module {
   private readonly defaultLimitChars: number;
   private readonly serverId: string;
 
-  private state: GcState = { overrides: {}, counters: {} };
+  private state: GcState = { overrides: {}, pins: {}, counters: {} };
 
   constructor(config: SubscriptionGcConfig = {}) {
     this.defaultLimitChars =
@@ -81,8 +90,12 @@ export class SubscriptionGcModule implements Module {
     this.ctx = ctx;
     const saved = ctx.getState<Partial<GcState>>();
     if (saved) {
+      // Pre-pins state stored ChannelMode's programmatic 'off' pins in
+      // `overrides`; they stay there as agent-level overrides and get
+      // re-asserted as pins on the next mode change.
       this.state = {
         overrides: saved.overrides ?? {},
+        pins: saved.pins ?? {},
         counters: saved.counters ?? {},
       };
     }
@@ -112,37 +125,16 @@ export class SubscriptionGcModule implements Module {
     this.ctx = null;
   }
 
+  /** No agent-visible tools — idle limits live inside the framework's
+   *  `agent_settings` tool via getAgentSettingsExtension() below (same
+   *  consolidation as the reasoning controls). The former tools remain
+   *  ROUTABLE though undeclared (module tool routing is prefix-based), so
+   *  agent muscle memory keeps working. ChannelModeModule holds channels
+   *  open via the internal `subscription-gc--pin_channel_idle_limit` tool
+   *  — a separate layer from agent overrides, so agent_settings reset
+   *  can't break debounced mode's invariant. */
   getTools(): ToolDefinition[] {
-    return [
-      {
-        name: 'set_channel_idle_limit',
-        description:
-          'Set how many characters of ambient (non-mention, non-DM) traffic a ' +
-          'subscribed channel may emit between your activations before it is ' +
-          'auto-closed. `limit` is a number of characters, "default" to ' +
-          `use the global default (${this.defaultLimitChars}), or "off" to ` +
-          'never auto-close this channel.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            channelId: { type: 'string', description: 'Discord channel ID' },
-            limit: {
-              type: 'string',
-              description: 'A character count (e.g. "20000"), "default", or "off".',
-            },
-          },
-          required: ['channelId', 'limit'],
-        },
-      },
-      {
-        name: 'list_channel_idle_limits',
-        description:
-          'Show the auto-close configuration: the global default limit, ' +
-          'per-channel overrides, and the current since-last-activation ambient ' +
-          'character counts per channel.',
-        inputSchema: { type: 'object', properties: {} },
-      },
-    ];
+    return [];
   }
 
   async handleToolCall(call: ToolCall): Promise<ToolResult> {
@@ -181,6 +173,28 @@ export class SubscriptionGcModule implements Module {
         this.persistNow();
         return ok(`Idle limit for ${channelId} set to ${desc}.`);
       }
+      case 'pin_channel_idle_limit': {
+        // Internal (module-to-module) verb: hold a channel open regardless of
+        // agent-level overrides. Not part of the agent settings surface.
+        const channelId = input.channelId;
+        if (typeof channelId !== 'string' || channelId.length === 0) {
+          return { success: false, error: 'channelId is required', isError: true };
+        }
+        if (typeof input.pinned !== 'boolean') {
+          return { success: false, error: 'pinned must be a boolean', isError: true };
+        }
+        if (input.pinned) {
+          this.state.pins[channelId] = true;
+        } else {
+          delete this.state.pins[channelId];
+        }
+        this.persistNow();
+        return ok(
+          input.pinned
+            ? `Channel ${channelId} pinned open (never auto-close).`
+            : `Channel ${channelId} unpinned; its agent override or the default limit applies again.`,
+        );
+      }
       case 'list_channel_idle_limits':
         return {
           success: true,
@@ -188,14 +202,128 @@ export class SubscriptionGcModule implements Module {
           data: {
             defaultLimitChars: this.defaultLimitChars,
             overrides: this.state.overrides,
+            pins: Object.keys(this.state.pins),
             counters: this.state.counters,
           },
         };
       default:
-        return { success: false, error: `Unknown tool: ${call.name}`, isError: true };
+        return {
+          success: false,
+          error:
+            `Unknown tool: ${call.name}. Idle-limit controls live in agent_settings ` +
+            `(field channel_idle_limits).`,
+          isError: true,
+        };
     }
   }
 
+  /**
+   * Declare idle limits as an agent_settings extension: the framework merges
+   * the field into the agent_settings tool and routes get/update/reset back
+   * here. Same pattern as SettingsModule's reasoning fields. Update semantics
+   * mirror the (undeclared but still routable) set_channel_idle_limit tool:
+   * per entry, a positive number sets an override, "off" disables auto-close
+   * for the channel, and "default"/null clears back to the global default.
+   * Entries not mentioned in a patch are left untouched, and a patch applies
+   * all-or-nothing: it is validated in full before any entry takes effect.
+   *
+   * `get` additionally reports read-only companions (the framework merges
+   * ext.get() into the response but only routes declared `keys` on update):
+   * `channel_idle_default`, live `channel_idle_counters`, and
+   * `channel_idle_pinned` — system pins held by other modules, which sit
+   * above these overrides and are not touched by update or reset.
+   */
+  getAgentSettingsExtension(): {
+    properties: Record<string, unknown>;
+    keys: string[];
+    get(agentName: string): Record<string, unknown>;
+    update(agentName: string, patch: Record<string, unknown>): Record<string, unknown>;
+    reset(agentName: string, keys?: string[]): Record<string, unknown>;
+  } {
+    return {
+      properties: {
+        channel_idle_limits: {
+          type: 'object',
+          description:
+            'Per-channel ambient auto-close budgets, as {"<channelId>": value}: ' +
+            'a positive number of characters, "off" (never auto-close this ' +
+            'channel), or "default"/null (clear the override). Channels not ' +
+            `listed use the global default (${this.defaultLimitChars} chars of ` +
+            'ambient traffic between your activations before auto-close). ' +
+            'Patches merge per entry; unmentioned channels are untouched. ' +
+            'get also reports the read-only channel_idle_default, ' +
+            'channel_idle_counters (ambient chars since your last activation), ' +
+            'and channel_idle_pinned (channels held open by a channel mode; ' +
+            'not affected by update or reset — change the channel mode instead).',
+        },
+      },
+      keys: ['channel_idle_limits'],
+      get: () => this.settingsSnapshot(),
+      update: (_agentName, patch) => {
+        const raw = patch.channel_idle_limits;
+        if (raw === undefined) return this.settingsSnapshot();
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+          throw new Error(
+            'channel_idle_limits must be an object mapping channel ids to a ' +
+            'positive number, "off", or "default"/null',
+          );
+        }
+        // All-or-nothing: validate the full patch into a staging copy and
+        // swap only if every entry passes. Mutating live state per-entry
+        // would leave earlier entries active (limitFor reads the map
+        // directly, and any later flush persists them) after a failure the
+        // agent was told was rejected.
+        const staged = { ...this.state.overrides };
+        for (const [channelId, value] of Object.entries(raw as Record<string, unknown>)) {
+          if (channelId.length === 0) throw new Error('channel id must be non-empty');
+          const numeric =
+            typeof value === 'number'
+              ? value
+              : typeof value === 'string' && /^\d+$/.test(value.trim())
+                ? Number(value.trim())
+                : NaN;
+          if (value === 'default' || value === null) {
+            delete staged[channelId];
+          } else if (value === 'off') {
+            staged[channelId] = 'off';
+          } else if (Number.isFinite(numeric) && numeric > 0) {
+            staged[channelId] = Math.round(numeric);
+          } else {
+            throw new Error(
+              `channel_idle_limits[${JSON.stringify(channelId)}] must be a positive ` +
+              'number, "off", or "default"/null (no entries were applied)',
+            );
+          }
+        }
+        this.state.overrides = staged;
+        this.persistNow();
+        return this.settingsSnapshot();
+      },
+      reset: (_agentName, keys) => {
+        // Clears agent overrides only. Pins are mode invariants owned by
+        // other modules (ChannelMode's debounced mode), not agent
+        // preferences — a blanket `agent_settings reset` must not silently
+        // reopen a debounced channel to auto-close.
+        const all = !keys || keys.length === 0;
+        if (all || keys?.includes('channel_idle_limits')) {
+          this.state.overrides = {};
+          this.persistNow();
+        }
+        return this.settingsSnapshot();
+      },
+    };
+  }
+
+  /** agent_settings view: the writable overrides plus read-only status. */
+  private settingsSnapshot(): Record<string, unknown> {
+    return {
+      channel_idle_limits: { ...this.state.overrides },
+      channel_idle_default: this.defaultLimitChars,
+      channel_idle_counters: { ...this.state.counters },
+      channel_idle_pinned: Object.keys(this.state.pins),
+    };
+  }
+
   async onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
     const ambient = this.extractAmbient(event);
     if (!ambient || ambient.chars <= 0) return {};
@@ -232,7 +360,7 @@ export class SubscriptionGcModule implements Module {
                     `[subscription-gc] Auto-closed channel ${channelId}: it emitted ` +
                     `over ${limit} characters of ambient traffic since your last activation without ` +
                     `engagement. Direct addresses there still reach you. Reopen with channel_open, ` +
-                    `or raise/disable its limit with set_channel_idle_limit.`,
+                    `or raise/disable its limit via agent_settings (field channel_idle_limits).`,
                 },
               ],
             },
@@ -254,6 +382,7 @@ export class SubscriptionGcModule implements Module {
   // ── internals ──
 
   private limitFor(channelId: string): number {
+    if (this.state.pins[channelId]) return Infinity;
     const o = this.state.overrides[channelId];
     if (o === 'off') return Infinity;
     if (typeof o === 'number') return o;