@animalabs/agent-framework 0.6.5 → 0.6.6

package/dist/src/mcpl/channel-registry.js

@@ -6,7 +6,7 @@
  *
  * Responsibilities:
  * - Register/unregister channel descriptors from MCPL servers
- * - Auto-open channels on registration
+ * - Reconcile actual channel state to Chronicle-backed desired state
  * - Route incoming messages to the processing queue
  * - Manage typing indicator timers (7s interval for Discord compatibility)
  * - Expose synthesized tools: channel_list, channel_open, channel_close, channel_publish
@@ -16,6 +16,7 @@
 // Typing indicator interval (Discord typing lasts ~10s, so 7s keeps it alive)
 // ============================================================================
 const TYPING_INTERVAL_MS = 7_000;
+const CHANNEL_LIFECYCLE_LOG_ID = 'mcpl/channel-lifecycle';
 function shallowEqualRecord(a, b) {
     if (a === b)
         return true;
@@ -78,15 +79,45 @@ const CHANNEL_TOOL_DEFINITIONS = [
     },
     {
         name: 'channel_open',
-        description: 'Open a channel to start receiving messages',
+        description: 'Open a channel to start receiving its ordinary ongoing traffic. The MCPL ' +
+            'integration performs its own subscribe/join/attach operation. Optionally request ' +
+            'history preceding the message that invited you into the channel.',
         inputSchema: {
             type: 'object',
             properties: {
                 channelId: { type: 'string', description: 'ID of the channel to open' },
+                serverId: { type: 'string', description: 'Owning MCPL server; required only when channelId is ambiguous.' },
+                backscroll: {
+                    type: 'number',
+                    description: 'Number of earlier messages to return while opening (0-500; default 0).',
+                },
+                beforeMessageId: {
+                    type: 'string',
+                    description: 'Anchor message from the closed-channel notice; it is excluded from backscroll.',
+                },
             },
             required: ['channelId'],
         },
     },
+    {
+        name: 'channel_decline',
+        description: 'Deliberately remain closed after being addressed in a closed channel. Optionally ' +
+            'post a public acknowledgment through the MCPL integration. Acknowledgment is ' +
+            'opt-in; omitting it declines silently.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                channelId: { type: 'string', description: 'Channel from the invitation notice.' },
+                serverId: { type: 'string', description: 'Owning MCPL server from the invitation notice.' },
+                messageId: { type: 'string', description: 'Triggering message to acknowledge.' },
+                acknowledge: {
+                    type: 'string',
+                    description: 'Optional surface value such as 👀. Omit for a silent decline.',
+                },
+            },
+            required: ['channelId', 'messageId'],
+        },
+    },
     {
         name: 'channel_close',
         description: 'Close a channel to stop receiving messages',
@@ -94,6 +125,7 @@ const CHANNEL_TOOL_DEFINITIONS = [
             type: 'object',
             properties: {
                 channelId: { type: 'string', description: 'ID of the channel to close' },
+                serverId: { type: 'string', description: 'Owning MCPL server; required only when channelId is ambiguous.' },
             },
             required: ['channelId'],
         },
@@ -160,6 +192,7 @@ export class ChannelRegistry {
     onRouteFailure;
     homeChannelResolver;
     activeChannelResolver;
+    store;
     /** Registered channels, keyed by `{serverId}:{channelId}`. */
     channels = new Map();
     /** Most recent incoming channel ID — used for speech routing / default publish. */
@@ -172,12 +205,11 @@ export class ChannelRegistry {
     /** Per-channel typing metadata — carried on the 7s refresh so the target
      *  server keeps getting the same routing hints (e.g. Zulip topic). */
     typingMetadata = new Map();
-    /**
-     * Per-server channel auto-open policy. Populated by the framework from
-     * each McplServerConfig at connect time; default ('auto') applies when
-     * unset.
-     */
-    subscriptionPolicies = new Map();
+    /** Chronicle-projected desired lifecycle state, keyed by server + channel. */
+    desiredStates = new Map();
+    /** One-time migration inputs from the retired recipe auto-open policy. */
+    legacyPolicies = new Map();
+    migratedLegacyPolicies = new Set();
     constructor(serverRegistry, featureSetManager, pushEventFn, emitTraceFn, options) {
         this.serverRegistry = serverRegistry;
         this.featureSetManager = featureSetManager;
@@ -188,13 +220,16 @@ export class ChannelRegistry {
         this.onRouteFailure = options?.onRouteFailure;
         this.homeChannelResolver = options?.homeChannelResolver;
         this.activeChannelResolver = options?.activeChannelResolver;
+        this.store = options?.store;
+        this.initializeLifecycleStore();
     }
     /**
-     * Set the channel auto-open policy for a server. Called by the framework
-     * when each MCPL server is registered.
+     * Supply a legacy recipe policy for one-time migration into Chronicle.
      */
     setSubscriptionPolicy(serverId, policy) {
-        this.subscriptionPolicies.set(serverId, policy);
+        // Backward-compatible recipe ingestion only. The policy is consumed once
+        // to seed Chronicle, then never applied to newly discovered channels.
+        this.legacyPolicies.set(serverId, policy);
     }
     // ==========================================================================
     // Handler Methods (called from framework.ts wireMcplEvents)
@@ -202,7 +237,7 @@ export class ChannelRegistry {
     /**
      * Handle `channels/register` from a server.
      *
-     * Registers each channel descriptor in the map and auto-opens them.
+     * Registers descriptors and reconciles them to durable desired state.
      */
     async handleRegister(serverId, params, responder) {
         const registeredIds = [];
@@ -215,12 +250,14 @@ export class ChannelRegistry {
             });
             registeredIds.push(channel.id);
         }
-        // Respond before auto-opening — the server blocks on this response and
+        // Respond before reconciliation — the server blocks on this response and
         // can't process channels/open until it arrives.
         const result = { registered: registeredIds };
         responder?.respond(result);
-        // Auto-open all registered channels
-        await this.autoOpenChannels(serverId, params.channels);
+        // One-time migration from the retired recipe policy, then reconcile the
+        // server to Chronicle-backed desired state.
+        this.migrateLegacyPolicy(serverId, params.channels);
+        await this.reconcileChannels(serverId, params.channels);
         this.emitTraceFn({
             type: 'mcpl:channels-register',
             serverId,
@@ -231,7 +268,7 @@ export class ChannelRegistry {
     /**
      * Handle `channels/changed` notification from a server.
      *
-     * Processes added (register + auto-open), removed (delete + stop typing),
+     * Processes added (register + reconcile), removed (delete + stop typing),
      * and updated (replace descriptor) channels.
      */
     async handleChanged(serverId, params) {
@@ -253,7 +290,7 @@ export class ChannelRegistry {
                 }
             }
         }
-        // Process added channels (register + auto-open)
+        // Process added channels (register + reconcile durable desired state)
         if (params.added) {
             for (const channel of params.added) {
                 const key = `${serverId}:${channel.id}`;
@@ -263,7 +300,7 @@ export class ChannelRegistry {
                     open: false,
                 });
             }
-            await this.autoOpenChannels(serverId, params.added);
+            await this.reconcileChannels(serverId, params.added);
         }
         this.emitTraceFn({
             type: 'mcpl:channels-changed',
@@ -323,6 +360,13 @@ export class ChannelRegistry {
                     label: channelLabel,
                 });
             }
+            else {
+                // A server sending channels/incoming is authoritative evidence that
+                // the transport is actually open. This repairs transient status only;
+                // durable desired state still changes exclusively through lifecycle
+                // operations.
+                this.channels.get(incomingKey).open = true;
+            }
             // Determine whether to trigger inference
             let triggerInference = true;
             if (this.shouldTriggerInference) {
@@ -374,8 +418,9 @@ export class ChannelRegistry {
         });
     }
     /**
-     * Ensure a channel is registered AND open so it can serve as an outbound
-     * routing locus, lazy-registering it if unseen and opening it if closed.
+     * Ensure a channel is registered so it can serve as an outbound routing
+     * locus. A push event from a closed channel must never mutate lifecycle
+     * state: direct-address events are intentionally usable without subscribing.
      *
      * Mirrors the lazy-registration inside handleIncoming(), but for channels
      * that only ever arrive as push/events rather than channels/incoming — the
@@ -385,15 +430,11 @@ export class ChannelRegistry {
      * silently dropped even though the inbound message proves the channel is
      * reachable (item-3 redux, DM sub-case). Idempotent: a later authoritative
      * channels/register or channels/changed overwrites this descriptor with the
-     * richer one; re-opening an already-open channel is a no-op.
+     * richer one.
      */
     ensureChannelRegistered(serverId, channelId, label) {
         const existing = this.findChannelEntry(channelId);
         if (existing) {
-            if (!existing.open) {
-                existing.open = true;
-                this.emitTraceFn({ type: 'mcpl:channel-opened', serverId: existing.serverId, channelId });
-            }
             return;
         }
         const key = `${serverId}:${channelId}`;
@@ -406,7 +447,7 @@ export class ChannelRegistry {
                 direction: 'bidirectional',
                 metadata: { lazyRegistered: true },
             },
-            open: true,
+            open: false,
         });
         this.emitTraceFn({
             type: 'mcpl:channel-lazy-registered',
@@ -519,6 +560,12 @@ export class ChannelRegistry {
     getDescriptor(channelId) {
         return this.findChannelEntry(channelId)?.descriptor;
     }
+    isChannelOpen(channelId) {
+        return this.findChannelEntry(channelId)?.open === true;
+    }
+    getDesiredState(serverId, channelId) {
+        return this.desiredStates.get(this.lifecycleKey(serverId, channelId));
+    }
     /**
      * Get all open channels.
      */
@@ -551,6 +598,8 @@ export class ChannelRegistry {
                 return this.handleToolOpen(input);
             case 'channel_close':
                 return this.handleToolClose(input);
+            case 'channel_decline':
+                return this.handleToolDecline(input);
             case 'channel_publish':
                 return this.handleToolPublish(input);
             case 'think':
@@ -626,7 +675,7 @@ export class ChannelRegistry {
                 this.defaultPublishThreadId = undefined;
             }
         }
-        this.subscriptionPolicies.delete(serverId);
+        // Desired state and migration markers deliberately survive disconnects.
     }
     /**
      * Stop all typing intervals and clear all channel registrations.
@@ -645,59 +694,137 @@ export class ChannelRegistry {
         this.defaultPublishThreadId = undefined;
     }
     // ==========================================================================
-    // Private: Auto-open channels
+    // Private: Durable desired state and reconciliation
     // ==========================================================================
-    async autoOpenChannels(serverId, channels) {
-        const server = this.serverRegistry.getServer(serverId);
-        if (!server)
+    lifecycleKey(serverId, channelId) {
+        return `${serverId}\u0000${channelId}`;
+    }
+    initializeLifecycleStore() {
+        if (!this.store)
             return;
-        const policy = this.subscriptionPolicies.get(serverId) ?? 'auto';
-        if (policy === 'manual') {
-            this.emitTraceFn({
-                type: 'mcpl:channels-auto-open-skipped',
-                serverId,
-                reason: 'manual',
-                count: channels.length,
-            });
+        try {
+            this.store.registerState({ id: CHANNEL_LIFECYCLE_LOG_ID, strategy: 'append_log' });
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !error.message.includes('State already exists')) {
+                throw error;
+            }
+        }
+        const raw = this.store.getStateJson(CHANNEL_LIFECYCLE_LOG_ID);
+        if (!Array.isArray(raw))
             return;
+        for (const item of raw) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const event = item;
+            if (typeof event.serverId !== 'string')
+                continue;
+            if (event.kind === 'desired-state' &&
+                typeof event.channelId === 'string' &&
+                (event.desired === 'open' || event.desired === 'closed')) {
+                this.desiredStates.set(this.lifecycleKey(event.serverId, event.channelId), event.desired);
+            }
+            else if (event.kind === 'legacy-policy-migrated') {
+                this.migratedLegacyPolicies.add(event.serverId);
+            }
         }
-        const allowList = Array.isArray(policy) ? new Set(policy) : null;
-        let opened = 0;
+    }
+    appendLifecycleEvent(event) {
+        this.store?.appendToStateJson(CHANNEL_LIFECYCLE_LOG_ID, event);
+    }
+    setDesiredState(serverId, channelId, desired, source) {
+        const key = this.lifecycleKey(serverId, channelId);
+        if (this.desiredStates.get(key) === desired)
+            return;
+        this.desiredStates.set(key, desired);
+        this.appendLifecycleEvent({
+            kind: 'desired-state',
+            serverId,
+            channelId,
+            desired,
+            source,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Consume the old recipe policy exactly once. It seeds Chronicle for
+     * existing deployments, but is not an ongoing admission policy: channels
+     * discovered later use their server bootstrap preference, otherwise closed.
+     */
+    migrateLegacyPolicy(serverId, channels) {
+        if (this.migratedLegacyPolicies.has(serverId))
+            return;
+        const policy = this.legacyPolicies.get(serverId) ?? 'manual';
+        const allowList = Array.isArray(policy) ? new Set(policy) : undefined;
         for (const channel of channels) {
-            if (allowList && !allowList.has(channel.id))
+            if (this.getDesiredState(serverId, channel.id))
                 continue;
+            const desired = channel.initiallyOpen === true ||
+                policy === 'auto' || allowList?.has(channel.id)
+                ? 'open'
+                : 'closed';
+            this.setDesiredState(serverId, channel.id, desired, 'legacy-recipe-migration');
+        }
+        this.migratedLegacyPolicies.add(serverId);
+        this.appendLifecycleEvent({
+            kind: 'legacy-policy-migrated',
+            serverId,
+            source: Array.isArray(policy) ? 'allow-list' : policy,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    ensureInitialDesiredState(serverId, channel) {
+        if (this.getDesiredState(serverId, channel.id))
+            return;
+        this.setDesiredState(serverId, channel.id, channel.initiallyOpen === true ? 'open' : 'closed', channel.initiallyOpen === true ? 'server-bootstrap' : 'default-closed');
+    }
+    async reconcileChannels(serverId, channels) {
+        const server = this.serverRegistry.getServer(serverId);
+        if (!server)
+            return;
+        for (const channel of channels) {
+            this.ensureInitialDesiredState(serverId, channel);
             const key = `${serverId}:${channel.id}`;
+            const desired = this.getDesiredState(serverId, channel.id);
+            const entry = this.channels.get(key);
+            if (desired !== 'open') {
+                try {
+                    await server.sendChannelsClose({ channelId: channel.id });
+                    if (entry)
+                        entry.open = false;
+                }
+                catch (err) {
+                    this.emitTraceFn({
+                        type: 'mcpl:channel-reconcile-failed',
+                        serverId,
+                        channelId: channel.id,
+                        desired,
+                        error: err.message,
+                    });
+                }
+                continue;
+            }
             try {
                 await server.sendChannelsOpen({
+                    channelId: channel.id,
                     type: channel.type,
                     address: channel.address,
                 });
-                const entry = this.channels.get(key);
-                if (entry) {
+                if (entry)
                     entry.open = true;
-                }
-                opened++;
             }
             catch (err) {
+                if (entry)
+                    entry.open = false;
                 this.emitTraceFn({
-                    type: 'mcpl:channel-open-failed',
+                    type: 'mcpl:channel-reconcile-failed',
                     serverId,
                     channelId: channel.id,
+                    desired,
                     error: err.message,
                 });
             }
         }
-        // Surface the common typo failure mode: allow-list set but nothing
-        // matched. Without this trace a one-char typo in a channel id looks
-        // identical to "MCPL didn't register the channel".
-        if (allowList && opened === 0 && channels.length > 0) {
-            this.emitTraceFn({
-                type: 'mcpl:channels-allow-list-empty',
-                serverId,
-                allowList: [...allowList],
-                registered: channels.map(c => c.id),
-            });
-        }
     }
     // ==========================================================================
     // Private: Typing notification
@@ -734,6 +861,22 @@ export class ChannelRegistry {
         }
         return undefined;
     }
+    resolveToolChannelEntry(channelId, serverId) {
+        const matches = [...this.channels.values()].filter((entry) => entry.descriptor.id === channelId && (!serverId || entry.serverId === serverId));
+        if (matches.length === 0) {
+            return {
+                error: serverId
+                    ? `Channel not found: ${channelId} on server ${serverId}`
+                    : `Channel not found: ${channelId}`,
+            };
+        }
+        if (matches.length > 1) {
+            return {
+                error: `Channel id is ambiguous across MCPL servers: ${channelId}. Include serverId.`,
+            };
+        }
+        return { entry: matches[0] };
+    }
     /**
      * Find the composite key for a channel by its channelId.
      */
@@ -757,6 +900,7 @@ export class ChannelRegistry {
                 label: entry.descriptor.label,
                 direction: entry.descriptor.direction,
                 open: entry.open,
+                desired: this.getDesiredState(entry.serverId, entry.descriptor.id) ?? 'unknown',
                 serverId: entry.serverId,
             });
         }
@@ -766,20 +910,23 @@ export class ChannelRegistry {
         };
     }
     async handleToolOpen(input) {
-        const entry = this.findChannelEntry(input.channelId);
+        const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId);
+        const entry = resolved.entry;
         if (!entry) {
             return {
                 success: false,
-                error: `Channel not found: ${input.channelId}`,
+                error: resolved.error,
                 isError: true,
             };
         }
-        if (entry.open) {
+        const alreadyDesiredOpen = this.getDesiredState(entry.serverId, input.channelId) === 'open';
+        if (entry.open && alreadyDesiredOpen && !input.backscroll) {
             return {
                 success: true,
                 data: { channelId: input.channelId, status: 'already open' },
             };
         }
+        this.setDesiredState(entry.serverId, input.channelId, 'open', 'agent-tool');
         const server = this.serverRegistry.getServer(entry.serverId);
         if (!server) {
             return {
@@ -789,14 +936,27 @@ export class ChannelRegistry {
             };
         }
         try {
-            await server.sendChannelsOpen({
+            const history = input.backscroll
+                ? {
+                    limit: Math.max(0, Math.min(500, Math.floor(input.backscroll))),
+                    ...(input.beforeMessageId ? { beforeMessageId: input.beforeMessageId } : {}),
+                }
+                : undefined;
+            const result = await server.sendChannelsOpen({
+                channelId: entry.descriptor.id,
                 type: entry.descriptor.type,
                 address: entry.descriptor.address,
+                ...(history ? { history } : {}),
             });
             entry.open = true;
             return {
                 success: true,
-                data: { channelId: input.channelId, status: 'opened' },
+                data: {
+                    channelId: input.channelId,
+                    status: alreadyDesiredOpen ? 'reconciled' : 'opened',
+                    ...(result.history ? { history: result.history } : {}),
+                    ...(result.historyTruncated ? { historyTruncated: true } : {}),
+                },
             };
         }
         catch (err) {
@@ -808,20 +968,24 @@ export class ChannelRegistry {
         }
     }
     async handleToolClose(input) {
-        const entry = this.findChannelEntry(input.channelId);
+        const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId);
+        const entry = resolved.entry;
         if (!entry) {
             return {
                 success: false,
-                error: `Channel not found: ${input.channelId}`,
+                error: resolved.error,
                 isError: true,
             };
         }
-        if (!entry.open) {
+        const alreadyDesiredClosed = this.getDesiredState(entry.serverId, input.channelId) === 'closed';
+        if (!entry.open && alreadyDesiredClosed) {
             return {
                 success: true,
                 data: { channelId: input.channelId, status: 'already closed' },
             };
         }
+        this.setDesiredState(entry.serverId, input.channelId, 'closed', 'agent-tool');
+        this.stopTyping(input.channelId);
         const server = this.serverRegistry.getServer(entry.serverId);
         if (!server) {
             return {
@@ -833,7 +997,6 @@ export class ChannelRegistry {
         try {
             await server.sendChannelsClose({ channelId: input.channelId });
             entry.open = false;
-            this.stopTyping(input.channelId);
             return {
                 success: true,
                 data: { channelId: input.channelId, status: 'closed' },
@@ -847,6 +1010,69 @@ export class ChannelRegistry {
             };
         }
     }
+    async handleToolDecline(input) {
+        const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId);
+        const entry = resolved.entry;
+        if (!entry) {
+            return { success: false, error: resolved.error, isError: true };
+        }
+        if (entry.open || this.getDesiredState(entry.serverId, input.channelId) === 'open') {
+            return {
+                success: false,
+                error: `Channel is already open: ${input.channelId}. Use channel_close to leave it.`,
+                isError: true,
+            };
+        }
+        // The lifecycle decision is authoritative even if the optional public
+        // acknowledgment cannot be rendered by the surface.
+        this.setDesiredState(entry.serverId, input.channelId, 'closed', 'invitation-declined');
+        let acknowledged = false;
+        let representation;
+        let acknowledgmentError;
+        if (input.acknowledge) {
+            const server = this.serverRegistry.getServer(entry.serverId);
+            if (!server) {
+                acknowledgmentError = `Server not found: ${entry.serverId}`;
+            }
+            else {
+                try {
+                    const result = await server.sendChannelsAcknowledge({
+                        channelId: input.channelId,
+                        messageId: input.messageId,
+                        intent: 'seen-not-opening',
+                        value: input.acknowledge,
+                    });
+                    acknowledged = result.acknowledged;
+                    representation = result.representation;
+                    if (!acknowledged) {
+                        acknowledgmentError = result.reason ??
+                            'The channel integration could not post the acknowledgment.';
+                    }
+                }
+                catch (error) {
+                    acknowledgmentError = error.message;
+                }
+            }
+        }
+        this.appendLifecycleEvent({
+            kind: 'invitation-declined',
+            serverId: entry.serverId,
+            channelId: input.channelId,
+            messageId: input.messageId,
+            acknowledgment: representation ?? input.acknowledge,
+            timestamp: new Date().toISOString(),
+        });
+        return {
+            success: true,
+            data: {
+                channelId: input.channelId,
+                status: 'remained closed',
+                acknowledged,
+                ...(representation ? { representation } : {}),
+                ...(acknowledgmentError ? { acknowledgmentError } : {}),
+            },
+        };
+    }
     /**
      * Handle the synthesized `think` tool — a private reasoning scratchpad. It
      * sends nothing, and (unlike before) does NOT silence the turn: trailing
@@ -874,6 +1100,12 @@ export class ChannelRegistry {
     handleToolSkipReply(input) {
         return {
             success: true,
+            // The note says "ended the turn" — make it TRUE. Without endTurn the
+            // framework resumes the stream after the tool result, and a model with
+            // nothing to say (told its turn already ended) just calls skip_reply
+            // 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,
             data: {
                 skipped: true,
                 note: 'Ended the turn without replying — nothing was sent to any channel.',