@animalabs/agent-framework 0.7.2 → 0.7.4

package/dist/src/framework.js

@@ -1787,6 +1787,11 @@ export class AgentFramework {
                 context_budget_tokens: { type: 'number', description: 'Total input context budget, including the reserved response allowance.' },
                 tail_tokens: { type: 'number', description: 'Recent raw context retained verbatim.' },
                 transition_pace_tokens: { type: 'number', description: 'Maximum ordinary KV re-read/perturbation per compile while converging.' },
+                immediate: {
+                    type: 'boolean',
+                    description: 'With a context_budget_tokens DECREASE: apply it immediately instead of a paced descent — ' +
+                        'the whole fold-down and its KV re-read land on the next compile, and any in-flight descent is cancelled.',
+                },
                 same_round_think_text_policy: {
                     type: 'string',
                     enum: ['public', 'private'],
@@ -3105,7 +3110,26 @@ export class AgentFramework {
             await this.routeConversationIncoming(event, metadata);
             return;
         }
-        const id = this.addMessage('user', event.content, metadata);
+        // Addressed-while-closed invitation — parity with the push-event path
+        // (channels.publish surfaces like portal-mcpl deliver mentions here).
+        const incomingContent = [...event.content];
+        {
+            const invitation = this.buildClosedChannelInvitation({
+                serverId: event.serverId,
+                channelId: event.channelId,
+                messageId: event.messageId,
+                authorName: event.author?.name || 'Someone',
+                guildName: typeof event.metadata?.guildName === 'string' && event.metadata.guildName
+                    ? event.metadata.guildName
+                    : undefined,
+                tags: event.tags,
+            });
+            if (invitation) {
+                incomingContent.push(invitation.block);
+                Object.assign(metadata, invitation.metadataPatch);
+            }
+        }
+        const id = this.addMessage('user', incomingContent, metadata);
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
         if (event.triggerInference) {
             const addressed = isAddressedMessage(event.tags, event.metadata);
@@ -3352,6 +3376,60 @@ export class AgentFramework {
             }
         }
     }
+    /**
+     * Build the addressed-while-CLOSED channel invitation block, shared by the
+     * push-event and channels/incoming ingest paths. Until 2026-07-27 only push
+     * events (discord-mcpl mentions) carried it; channels.publish surfaces
+     * (portal-mcpl) delivered bare mentions with no guidance and no route — an
+     * explicit-prose agent's natural plain reply bounced with nowhere to go
+     * (Rhys's first portal mention: a 2,320-char reply stranded).
+     *
+     * Wording: option 1 teaches the `>>` destination prefix, which delivers for
+     * BOTH legacy (host-inferred) and explicit prose-routing agents. The
+     * previous "simply write your reply as normal text" was a false promise
+     * under explicit routing (the metadata flags it set had no consumers).
+     *
+     * Human-readable names wherever the surface provided them — a mind reading
+     * this should see WHO addressed it WHERE, not a wall of snowflake ids. Raw
+     * ids remain only inside the tool-argument instructions, where they are the
+     * literal values to pass.
+     */
+    buildClosedChannelInvitation(opts) {
+        if (!this.channelRegistry)
+            return null;
+        if (!opts.tags?.includes('chat:addressed'))
+            return null;
+        if (this.channelRegistry.isChannelOpen(opts.channelId))
+            return null;
+        const descriptor = this.channelRegistry.getDescriptor(opts.channelId);
+        const maxBackscroll = descriptor?.capabilities?.history?.maxMessages ?? 0;
+        const label = opts.channelLabel ?? descriptor?.label;
+        const channelLabel = label ? `#${label}` : `"${opts.channelId}"`;
+        const place = opts.guildName ? `${channelLabel} in "${opts.guildName}"` : channelLabel;
+        const block = {
+            type: 'text',
+            text: `\n[Channel invitation] ${opts.authorName} addressed you in ${place} — ` +
+                `a channel you haven't joined. You're seeing this one message; you won't receive more from it unless you join. ` +
+                `Your options:\n` +
+                `1. Reply without joining — write your reply this turn prefixed with ">>${channelLabel}"; it will be delivered there.\n` +
+                `2. Join the channel — call channel_open with channelId "${opts.channelId}" and serverId "${opts.serverId}"` +
+                (maxBackscroll > 0
+                    ? `; to also read recent history, add backscroll (a number up to ${maxBackscroll}) and beforeMessageId "${opts.messageId}".\n`
+                    : `.\n`) +
+                `3. Stay out — call channel_decline with channelId "${opts.channelId}", serverId "${opts.serverId}", ` +
+                `and messageId "${opts.messageId}" (optionally set acknowledge to an emoji like 👀 so ${opts.authorName} isn't left hanging).\n` +
+                `Doing nothing is also fine.`,
+        };
+        return {
+            block,
+            metadataPatch: {
+                channelInvitation: true,
+                channelOpen: false,
+                channelId: opts.channelId,
+                invitationMessageId: opts.messageId,
+            },
+        };
+    }
     /**
      * Convert an MCPL push event to a context message.
      */
@@ -3378,44 +3456,21 @@ export class AgentFramework {
             metadata.channelId = triggerChannel.channelId;
         }
         const content = [...event.content];
-        const addressedWhileClosed = triggerChannel &&
-            event.tags?.includes('chat:addressed') &&
-            this.channelRegistry &&
-            !this.channelRegistry.isChannelOpen(triggerChannel.channelId);
-        if (addressedWhileClosed) {
-            const descriptor = this.channelRegistry.getDescriptor(triggerChannel.channelId);
-            const messageId = typeof event.origin?.messageId === 'string'
-                ? event.origin.messageId
-                : event.eventId;
-            const maxBackscroll = descriptor?.capabilities?.history?.maxMessages ?? 0;
-            // Resolve human-readable names from the event origin wherever the
-            // surface provided them — a mind reading this should see WHO addressed
-            // it WHERE, not a wall of snowflake ids. Raw ids remain only inside the
-            // tool-argument instructions, where they are the literal values to pass.
+        if (triggerChannel) {
             const origin = (event.origin ?? {});
-            const authorName = typeof origin.authorName === 'string' && origin.authorName ? origin.authorName : 'Someone';
-            const channelLabel = triggerChannel.label ? `#${triggerChannel.label}` : `"${triggerChannel.channelId}"`;
-            const place = typeof origin.guildName === 'string' && origin.guildName
-                ? `${channelLabel} in "${origin.guildName}"`
-                : channelLabel;
-            content.push({
-                type: 'text',
-                text: `\n[Channel invitation] ${authorName} addressed you in ${place} — ` +
-                    `a channel you haven't joined. You're seeing this one message; you won't receive more from it unless you join. ` +
-                    `Your options:\n` +
-                    `1. Reply without joining — simply write your reply as normal text this turn; it will be delivered to ${channelLabel}.\n` +
-                    `2. Join the channel — call channel_open with channelId "${triggerChannel.channelId}" and serverId "${event.serverId}"` +
-                    (maxBackscroll > 0
-                        ? `; to also read recent history, add backscroll (a number up to ${maxBackscroll}) and beforeMessageId "${messageId}".\n`
-                        : `.\n`) +
-                    `3. Stay out — call channel_decline with channelId "${triggerChannel.channelId}", serverId "${event.serverId}", ` +
-                    `and messageId "${messageId}" (optionally set acknowledge to an emoji like 👀 so ${authorName} isn't left hanging).\n` +
-                    `Doing nothing is also fine.`,
+            const invitation = this.buildClosedChannelInvitation({
+                serverId: event.serverId,
+                channelId: triggerChannel.channelId,
+                channelLabel: triggerChannel.label,
+                messageId: typeof origin.messageId === 'string' ? origin.messageId : event.eventId,
+                authorName: typeof origin.authorName === 'string' && origin.authorName ? origin.authorName : 'Someone',
+                guildName: typeof origin.guildName === 'string' && origin.guildName ? origin.guildName : undefined,
+                tags: event.tags,
             });
-            metadata.channelInvitation = true;
-            metadata.channelOpen = false;
-            metadata.channelId = triggerChannel.channelId;
-            metadata.invitationMessageId = messageId;
+            if (invitation) {
+                content.push(invitation.block);
+                Object.assign(metadata, invitation.metadataPatch);
+            }
         }
         const id = this.addMessage('user', content, metadata);
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:push-event' });
@@ -3913,6 +3968,20 @@ export class AgentFramework {
         });
         this.eventGate?.onInferenceStarted(agent.name);
         this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
+        // Typing indicator, started at TURN START. It says "attending", which is
+        // true from the moment the turn is accepted — but it used to start inside
+        // driveStream, i.e. only after module gatherContext + MCPL beforeInference
+        // RPCs + the full context compile + stream initiation. All of that read as
+        // dead air to whoever just messaged the agent (30+ s during the 2026-07
+        // mythos compile regression; still seconds of hooks+compile after).
+        // Same channel choice as driveStream's own startTyping (which stays, is
+        // idempotent per channel, and owns the 7s refresh); the catch below stops
+        // it on the no-driveStream failure paths (e.g. a compile refusal).
+        const earlyTypingChannel = agent.proseRouting === 'explicit'
+            ? trigger?.channelId ?? null
+            : this.turnLocusPins.get(agent.name) ?? null;
+        if (earlyTypingChannel)
+            this.channelRegistry?.startTyping(earlyTypingChannel);
         try {
             const requestSnapshot = this.captureInferenceToolSnapshot(agent);
             const allTools = this.getToolsForAgent(agent.name, requestSnapshot);
@@ -3956,6 +4025,10 @@ export class AgentFramework {
             this.activeStreams.set(agent.name, handle);
         }
         catch (error) {
+            // The early typing indicator has no driveStream `finally` on this path —
+            // a hook/compile/stream-setup failure must not leave "typing…" stuck.
+            // (Retries below restart it; stopTyping is idempotent.)
+            this.channelRegistry?.stopTyping();
             const err = error instanceof Error ? error : new Error(String(error));
             this.emitTrace({
                 type: 'inference:failed',
@@ -7243,6 +7316,10 @@ export class AgentFramework {
                     if (input.same_round_think_text_policy !== undefined) {
                         patch.sameRoundThinkTextPolicy = input.same_round_think_text_policy;
                     }
+                    // Immediate budget decrease: skip the paced descent; the next
+                    // compile plans straight at the new budget (one-shot fold-down).
+                    if (input.immediate !== undefined)
+                        patch.immediate = Boolean(input.immediate);
                     // Route extension-owned keys to their modules; apply the core patch
                     // only when it touches core keys (an extension-only update must not
                     // disturb a converging budget transition).