@animalabs/agent-framework 0.7.2 → 0.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",

package/src/agent.ts

@@ -270,7 +270,11 @@ export class Agent {
 
     if (patch.contextBudgetTokens !== undefined) {
       const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
-      if (patch.contextBudgetTokens >= live) {
+      if (patch.contextBudgetTokens >= live || patch.immediate) {
+        // Increases are always immediate. Decreases take this path only with
+        // the explicit `immediate` flag: the next compile plans straight at
+        // the new budget — one-shot fold-down, KV invalidation paid this
+        // turn — and any in-flight descent is cancelled.
         nextContextBudget = patch.contextBudgetTokens;
         nextContextTarget = undefined;
         if (this.getHotContextSettings()) hotPatch.preparedWindowTokens = null;
@@ -298,6 +302,7 @@ export class Agent {
     }
     for (const [key, value] of Object.entries(patch)) {
       if (key === 'sameRoundThinkTextPolicy') continue;
+      if (key === 'immediate') continue; // a mode for this apply, never a persisted setting
       if (value !== undefined) (this.runtimeSettingsOverrides as Record<string, unknown>)[key] = value;
     }
     if (patch.sameRoundThinkTextPolicy !== undefined) {
@@ -706,6 +711,31 @@ export class Agent {
    * Called by framework when stream completes.
    */
   addAssistantResponse(content: ContentBlock[]): void {
+    // A turn whose entire output is thinking blocks produced NOTHING: no
+    // speech, no tool call. That is what a refusal looks like on the wire —
+    // the provider returns signed thinking (often with empty text, the
+    // fable-5 hidden-CoT packaging) and no content. Persisting it records an
+    // action that never happened, and two such records landing adjacent are
+    // actively toxic: formatters merge consecutive same-role messages
+    // (membrane `mergeConsecutiveRoles`), producing one assistant message
+    // carrying signed thinking from two different responses, which the
+    // provider cannot verify — 400 "`thinking` or `redacted_thinking` blocks
+    // in the latest assistant message cannot be modified", unrecoverable by
+    // retry (labclaude, 2026-07-27: hard down ~4h on exactly this pair).
+    //
+    // Refused turns are surfaced by the refusal path (stderr, failures.log,
+    // the [inference-failed] notice); the store does not also need a
+    // content-free artifact of them. Loud, never silent.
+    if (content.length > 0 && content.every(
+      (b) => b.type === 'thinking' || b.type === 'redacted_thinking',
+    )) {
+      console.error(
+        `[assistant-persist] agent=${this.name}: refusing to store a thinking-only assistant ` +
+        `message (${content.length} block(s), no text and no tool_use) — the turn produced no ` +
+        `output. See the refusal/inference-failed record for why.`,
+      );
+      return;
+    }
     this.contextManager.addMessage(this.name, content);
   }
 

package/src/code-execution/py-runner.ts

@@ -404,10 +404,15 @@ export class PyRunner {
 }
 
 /**
- * Map framework tool names to python identifiers: `--` becomes `__`.
- * Names that still aren't valid identifiers, or that collide after
- * sanitization, are skipped loudly — a skipped tool is unreachable from
- * scripts (the exact-name tools[...] dict is built from this same list).
+ * Map framework tool names to python identifiers: `--` (the framework's
+ * prefix separator) becomes `__`, and every remaining character that is not
+ * valid in a python identifier becomes `_` (fleet reality: module and server
+ * ids contain single hyphens — `mcpl-admin`, `dog-events` — found live on
+ * the first canary run, 2026-07-26). A leading digit gets a `_` prefix.
+ *
+ * Names that sanitize to nothing, or that collide after sanitization, are
+ * skipped loudly — a skipped tool is unreachable from scripts (the
+ * exact-name tools[...] dict is built from this same list).
  */
 export function buildInjectedTools(
   toolNames: string[],
@@ -416,9 +421,10 @@ export function buildInjectedTools(
   const seen = new Map<string, string>();
   const injected: InjectedTool[] = [];
   for (const toolName of toolNames) {
-    const pyName = toolName.replace(/--/g, '__');
+    let pyName = toolName.replace(/--/g, '__').replace(/[^A-Za-z0-9_]/g, '_');
+    if (/^[0-9]/.test(pyName)) pyName = '_' + pyName;
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(pyName)) {
-      log(`[pytc] tool '${toolName}' skipped: '${pyName}' is not a valid python identifier`);
+      log(`[pytc] tool '${toolName}' skipped: cannot derive a python identifier`);
       continue;
     }
     const existing = seen.get(pyName);

package/src/code-execution/tool-definition.ts

@@ -23,8 +23,10 @@ export function buildCodeExecutionToolDefinition(opts?: {
     description:
       'Run Python code that can call your other tools programmatically. ' +
       'Every tool you have is available inside the script as an async Python function: ' +
-      "the function name is the tool name with '--' replaced by '__' " +
-      "(e.g. tool 'mcpl--discord--fetch_history' is the function mcpl__discord__fetch_history). " +
+      "the function name is the tool name with '--' replaced by '__' and any other " +
+      "non-identifier character replaced by '_' " +
+      "(e.g. tool 'mcpl--discord--fetch_history' is the function mcpl__discord__fetch_history, " +
+      "and tool 'mcpl--dog-events--status' is mcpl__dog_events__status). " +
       'Each function takes a single dict of arguments and returns a string — the same text ' +
       'the tool would have returned to you directly; parse structured results with json.loads. ' +
       "An exact-name lookup dict is also available: tools['mcpl--discord--fetch_history']({...}). " +

package/src/framework.ts

@@ -2210,6 +2210,12 @@ 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'],
@@ -3754,7 +3760,27 @@ export class AgentFramework {
       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 as string)
+          : 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) {
@@ -4037,6 +4063,67 @@ 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.
+   */
+  private buildClosedChannelInvitation(opts: {
+    serverId: string;
+    channelId: string;
+    channelLabel?: string;
+    messageId: string;
+    authorName: string;
+    guildName?: string;
+    tags?: string[];
+  }): { block: ContentBlock; metadataPatch: Record<string, unknown> } | null {
+    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: ContentBlock = {
+      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.
    */
@@ -4070,45 +4157,21 @@ export class AgentFramework {
     }
 
     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 ?? {}) as Record<string, unknown>;
-      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);
@@ -4643,6 +4706,21 @@ 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);
@@ -4700,6 +4778,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',
@@ -8459,6 +8541,7 @@ export class AgentFramework {
         tail_tokens?: unknown;
         transition_pace_tokens?: unknown;
         same_round_think_text_policy?: unknown;
+        immediate?: unknown;
         settings?: unknown;
       } & Record<string, unknown>;
       const extensions = this.collectAgentSettingsExtensions();
@@ -8490,6 +8573,9 @@ export class AgentFramework {
           if (input.same_round_think_text_policy !== undefined) {
             patch.sameRoundThinkTextPolicy = input.same_round_think_text_policy as AgentRuntimeSettingsPatch['sameRoundThinkTextPolicy'];
           }
+          // 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).

package/src/types/agent.ts

@@ -151,6 +151,18 @@ export interface AgentRuntimeSettingsPatch {
   tailTokens?: number;
   transitionPaceTokens?: number;
   sameRoundThinkTextPolicy?: SameRoundThinkTextPolicy;
+  /**
+   * Apply a `contextBudgetTokens` DECREASE immediately instead of starting a
+   * paced descent: the next compile plans straight at the new budget and the
+   * whole fold-down (and its KV invalidation) is paid on that one turn. Also
+   * cancels any in-flight descent. No effect on increases (already immediate)
+   * or on other keys. A MODE for this apply, not a setting — never persisted.
+   *
+   * This is the emergency lever: when window content must shrink NOW
+   * (refusal streaks, over-wall wedges), a converging descent is the wrong
+   * tool and used to be the only one (mythos, 2026-07-26).
+   */
+  immediate?: boolean;
 }
 
 export interface AgentRuntimeSettingsSnapshot {