@animalabs/agent-framework 0.10.0 → 0.11.0

package/dist/src/framework.js

@@ -331,6 +331,15 @@ const DEFAULT_SYNC_INTERVAL_MS = 1000;
 const DEFAULT_MAINTENANCE_INTERVAL_MS = 5000;
 /** Bound one pass so a large backlog yields to inference and other agents. */
 const MAINTENANCE_TICKS_PER_PASS = 8;
+const PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS = 65_000;
+const PROVIDER_ACCELERATION_MAX_COOLDOWN_MS = 10 * 60_000;
+const PROVIDER_ACCELERATION_JITTER_MS = 5_000;
+function isOrganizationAccelerationRateLimit(error) {
+    if (!(error instanceof MembraneError) || error.type !== 'rate_limit')
+        return false;
+    return (/organization(?:'s)?[^\n]{0,120}maximum(?:\s+usage)?\s+increase\s+rate/i.test(error.message) ||
+        /organization(?:'s)?[^\n]{0,120}acceleration(?:\s+limit)?/i.test(error.message));
+}
 /**
  * Extract fields the EventGate cares about from a ProcessEvent. The set of
  * event variants that carry `content`/`mount`/`paths`/`metadata` is open-ended
@@ -399,6 +408,13 @@ export class AgentFramework {
     maintenanceRunId = 0;
     currentMaintenanceRun = null;
     maintenanceHistory = [];
+    providerGates = new Map();
+    providerAccelerationCooldowns = new Map();
+    providerAccelerationRecoveries = new Map();
+    providerAccelerationLastRecovery = new Map();
+    providerAccelerationDefaultCooldownMs = PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS;
+    providerAccelerationJitterMs = PROVIDER_ACCELERATION_JITTER_MS;
+    providerAdmissionClosed = false;
     /** Last time we reported stale (busy-requeued) inference requests, per agent. */
     staleWarnAt = new Map();
     /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
@@ -897,6 +913,7 @@ export class AgentFramework {
             return;
         }
         this.running = true;
+        this.providerAdmissionClosed = false;
         this.loopPromise = this.runLoop();
         // Start periodic sync timer (if enabled)
         if (this.syncIntervalMs > 0) {
@@ -924,6 +941,7 @@ export class AgentFramework {
      */
     async stop() {
         this.running = false;
+        this.providerAdmissionClosed = true;
         this.queue.close();
         // Kill running code_execution scripts before cancelling streams: a
         // zombie script must not keep firing side-effectful tool calls into a
@@ -943,6 +961,8 @@ export class AgentFramework {
             record.runner.dispose();
         }
         this.backgroundScripts.clear();
+        // A stopped host must never hang behind its own cooldown.
+        this.cancelProviderAdmission();
         // Cancel all active streams
         for (const agent of this.agents.values()) {
             if (agent.state.status === 'streaming' ||
@@ -999,6 +1019,168 @@ export class AgentFramework {
      * schemas are absent. Passes never overlap; each agent gets a bounded drain
      * so maintenance cannot monopolize the framework event loop.
      */
+    providerGate(agentName) {
+        let gate = this.providerGates.get(agentName);
+        if (!gate) {
+            gate = { primaryDepth: 0, primaryPending: false, auxiliaryInFlight: 0,
+                auxiliaryWaiters: [], idleWaiters: [], deferredAuxiliary: 0 };
+            this.providerGates.set(agentName, gate);
+        }
+        return gate;
+    }
+    providerGateBlocked(agentName) {
+        const gate = this.providerGates.get(agentName);
+        return (gate?.primaryDepth ?? 0) > 0 || (gate?.primaryPending ?? false) ||
+            this.providerAccelerationCooldowns.has(agentName);
+    }
+    acquirePrimaryProviderGate(agentName) {
+        const gate = this.providerGate(agentName);
+        gate.primaryPending = false;
+        gate.primaryDepth++;
+    }
+    releasePrimaryProviderGate(agentName) {
+        const gate = this.providerGate(agentName);
+        gate.primaryDepth = Math.max(0, gate.primaryDepth - 1);
+        this.flushAuxiliaryAdmission(agentName);
+    }
+    flushAuxiliaryAdmission(agentName) {
+        const gate = this.providerGate(agentName);
+        if (gate.primaryDepth > 0 || gate.primaryPending || this.providerAccelerationCooldowns.has(agentName))
+            return;
+        for (const resolve of gate.auxiliaryWaiters.splice(0))
+            resolve();
+    }
+    async waitForAuxiliaryIdle(agentName) {
+        const gate = this.providerGate(agentName);
+        if (gate.auxiliaryInFlight === 0)
+            return;
+        await new Promise((resolve) => gate.idleWaiters.push(resolve));
+    }
+    async withAuxiliaryAdmission(agentName, run) {
+        const gate = this.providerGate(agentName);
+        if (this.providerGateBlocked(agentName)) {
+            gate.deferredAuxiliary++;
+            try {
+                await new Promise((resolve) => gate.auxiliaryWaiters.push(resolve));
+            }
+            finally {
+                gate.deferredAuxiliary = Math.max(0, gate.deferredAuxiliary - 1);
+            }
+        }
+        if (this.providerAdmissionClosed) {
+            throw new Error(`Provider admission closed while stopping (${agentName})`);
+        }
+        gate.auxiliaryInFlight++;
+        try {
+            return await run();
+        }
+        finally {
+            gate.auxiliaryInFlight = Math.max(0, gate.auxiliaryInFlight - 1);
+            if (gate.auxiliaryInFlight === 0)
+                for (const resolve of gate.idleWaiters.splice(0))
+                    resolve();
+        }
+    }
+    auxiliaryMembraneFor(agentName) {
+        const target = this.membrane;
+        return new Proxy(target, { get: (obj, prop, receiver) => {
+                const value = Reflect.get(obj, prop, receiver);
+                if (prop === 'complete' && typeof value === 'function') {
+                    return (...args) => this.withAuxiliaryAdmission(agentName, () => Reflect.apply(value, this.membrane, args));
+                }
+                return typeof value === 'function' ? value.bind(this.membrane) : value;
+            } });
+    }
+    accelerationCooldownMs(agentName, error) {
+        const base = error.retryAfterMs ?? this.providerAccelerationDefaultCooldownMs;
+        let hash = 0;
+        for (const ch of agentName)
+            hash = ((hash * 31) + ch.charCodeAt(0)) >>> 0;
+        const jitter = this.providerAccelerationJitterMs > 0 ? hash % (this.providerAccelerationJitterMs + 1) : 0;
+        return Math.min(PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, Math.max(1_000, base) + jitter);
+    }
+    sameInferenceRequest(a, b) {
+        return a.agentName === b.agentName && a.reason === b.reason && a.source === b.source &&
+            a.timestamp === b.timestamp && a.channelId === b.channelId;
+    }
+    holdProviderAcceleration(agent, error, trigger) {
+        if (this.ephemeralRuns.has(agent.name) || this.conversationAgentHomes.has(agent.name) || !isOrganizationAccelerationRateLimit(error))
+            return false;
+        const now = Date.now();
+        const delayMs = this.accelerationCooldownMs(agent.name, error);
+        const existing = this.providerAccelerationCooldowns.get(agent.name);
+        const held = existing?.heldRequests ?? [];
+        if (trigger && !held.some((r) => this.sameInferenceRequest(r, trigger)))
+            held.push(trigger);
+        if (existing)
+            clearTimeout(existing.timer);
+        const timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agent.name), delayMs);
+        timer.unref?.();
+        this.providerAccelerationCooldowns.set(agent.name, { startedAt: existing?.startedAt ?? now,
+            until: now + delayMs, timer, heldRequests: held, reason: error.message,
+            failures: (existing?.failures ?? 0) + 1 });
+        const gate = this.providerGate(agent.name);
+        gate.primaryPending = true;
+        this.providerAccelerationRecoveries.set(agent.name, { startedAt: existing?.startedAt ?? now,
+            failures: (existing?.failures ?? 0) + 1, heldRequests: held.length, reason: error.message });
+        console.error(`[provider-cooldown] agent=${agent.name} organization acceleration 429 — ` +
+            `holding primary/auxiliary for ${delayMs}ms; ${held.length} request(s) retained`);
+        return true;
+    }
+    releaseProviderAccelerationCooldown(agentName) {
+        const cooldown = this.providerAccelerationCooldowns.get(agentName);
+        if (!cooldown)
+            return;
+        clearTimeout(cooldown.timer);
+        this.providerAccelerationCooldowns.delete(agentName);
+        const recovery = this.providerAccelerationRecoveries.get(agentName);
+        if (recovery) {
+            recovery.releasedAt = Date.now();
+            recovery.heldRequests = cooldown.heldRequests.length;
+        }
+        const requests = cooldown.heldRequests.length > 0 ? cooldown.heldRequests : [{ agentName,
+                reason: 'provider-acceleration-retry', source: 'framework', timestamp: Date.now() }];
+        this.pendingRequests.push(...requests);
+        console.error(`[provider-cooldown] agent=${agentName} released after ${Date.now() - cooldown.startedAt}ms — ` +
+            `fresh compile queued with ${requests.length} retained request(s)`);
+    }
+    recordProviderAccelerationRecovery(agent, request, stopReason) {
+        const recovery = this.providerAccelerationRecoveries.get(agent.name);
+        if (!recovery?.releasedAt)
+            return;
+        this.providerAccelerationRecoveries.delete(agent.name);
+        const completedAt = Date.now();
+        const receipt = {
+            startedAt: recovery.startedAt,
+            releasedAt: recovery.releasedAt,
+            completedAt,
+            cooldownMs: recovery.releasedAt - recovery.startedAt,
+            waitedMs: completedAt - recovery.startedAt,
+            failures: recovery.failures,
+            heldRequests: recovery.heldRequests,
+            messageCount: request?.messages.length ?? 0,
+            toolCount: request?.tools?.length ?? 0,
+            stopReason,
+        };
+        this.providerAccelerationLastRecovery.set(agent.name, receipt);
+        // Operational receipt only: provider admission must never author resident memory.
+        console.error(`[provider-cooldown] recovered ${JSON.stringify({ agent: agent.name, ...receipt })}`);
+    }
+    cancelProviderAdmission() {
+        for (const cooldown of this.providerAccelerationCooldowns.values())
+            clearTimeout(cooldown.timer);
+        this.providerAccelerationCooldowns.clear();
+        this.providerAccelerationRecoveries.clear();
+        for (const gate of this.providerGates.values()) {
+            gate.primaryDepth = 0;
+            gate.primaryPending = false;
+            for (const resolve of gate.auxiliaryWaiters.splice(0))
+                resolve();
+            for (const resolve of gate.idleWaiters.splice(0))
+                resolve();
+        }
+        this.providerGates.clear();
+    }
     startQueuedMaintenance() {
         if (this.maintenancePass || !this.running)
             return;
@@ -1018,6 +1200,8 @@ export class AgentFramework {
             const cm = agent.getContextManager();
             const tools = this.getToolsForAgent(agent.name).filter((tool) => agent.canUseTool(tool.name));
             cm.setToolDefinitions(tools);
+            if (this.providerGateBlocked(agent.name))
+                return [];
             if (cm.isReady())
                 return [];
             const pending = cm.getPendingWork()?.description;
@@ -3104,7 +3288,9 @@ export class AgentFramework {
             store: this.store,
             namespace: `agents/${config.name}`,
             strategy: config.strategy ?? new PassthroughStrategy(),
-            membrane: this.membrane,
+            // Context Manager complete() calls are auxiliary work; the primary
+            // streaming agent keeps the original Membrane.
+            membrane: this.auxiliaryMembraneFor(config.name),
             debugLogContext: !!process.env.DEBUG_CONTEXT,
         });
         const agent = new Agent(config, contextManager, this.membrane);
@@ -3331,7 +3517,7 @@ export class AgentFramework {
                     // classifier-safe D-class from the 2026-07-24 ablation). It also
                     // updates lastAnnouncedLocus so the next turn's announce-on-change
                     // diffs against what the agent was actually last told.
-                    if (agent.proseRouting !== 'explicit' &&
+                    if ((agent.proseRouting === 'locus' || agent.proseRouting === 'hybrid') &&
                         !shouldEndTurn && !overBudget && currentState.stream) {
                         // Two signals qualify an injection to move the pin (n=6 + n=7):
                         //  - chat:addressed — someone explicitly spoke TO the agent
@@ -3734,6 +3920,9 @@ export class AgentFramework {
             isolate: true,
             // Strategy instances are stateful — never share the template's.
             strategy: router.strategyFactory?.() ?? new PassthroughStrategy(),
+            // Dynamic conversation forks retain the established provider policy in
+            // this bounded first slice. Provider cooldown ownership belongs to the
+            // persistent resident only; generation-unique forks must not leak gates.
             membrane: this.membrane,
             debugLogContext: !!process.env.DEBUG_CONTEXT,
         });
@@ -4067,7 +4256,8 @@ export class AgentFramework {
         // Clear pending (we'll re-add if inference doesn't run)
         this.pendingRequests = [];
         // Check each agent
-        for (const [agentName, requests] of requestsByAgent) {
+        for (const [agentName, groupedRequests] of requestsByAgent) {
+            let requests = groupedRequests;
             const agent = this.agents.get(agentName);
             if (!agent) {
                 // Agent not found — request is orphaned. Emit warning and drop.
@@ -4082,6 +4272,29 @@ export class AgentFramework {
                 console.error(`[inference-dropped] agent=${agentName} reason=agent_not_found requests=${requests.length}`);
                 continue;
             }
+            const providerCooldown = this.providerAccelerationCooldowns?.get(agentName);
+            if (providerCooldown) {
+                if (now < providerCooldown.until) {
+                    for (const req of requests) {
+                        if (!providerCooldown.heldRequests.some((r) => this.sameInferenceRequest(r, req))) {
+                            providerCooldown.heldRequests.push(req);
+                        }
+                    }
+                    const recovery = this.providerAccelerationRecoveries.get(agentName);
+                    if (recovery)
+                        recovery.heldRequests = providerCooldown.heldRequests.length;
+                    // The timer owns release. Do not hot-poll these requests.
+                    continue;
+                }
+                // Timers can deliver late under load. Release synchronously and merge
+                // the held causes into this one current compile.
+                clearTimeout(providerCooldown.timer);
+                this.providerAccelerationCooldowns.delete(agentName);
+                const recovery = this.providerAccelerationRecoveries.get(agentName);
+                if (recovery)
+                    recovery.releasedAt = now;
+                requests = [...providerCooldown.heldRequests, ...requests];
+            }
             // Skip if agent is busy (inferring, streaming, or waiting for tools) —
             // or if a turn is alive at all (activeTurnTokens): the state machine
             // goes idle at endTurn's reset while driveStream teardown is still
@@ -4097,9 +4310,14 @@ export class AgentFramework {
             // token; the predecessor frame's late finally no-ops via token-match.
             // This mirrors how the restart has always overwritten activeStreams
             // rather than waiting for the old stream's teardown.
-            const isBudgetRestart = requests.some((r) => r.reason === 'context_budget_restart');
-            const turnAlive = !isBudgetRestart && this.activeTurnTokens.has(agentName);
-            if (turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
+            const budgetRestart = requests.find((r) => r.reason === 'context_budget_restart');
+            const turnAlive = !budgetRestart && this.activeTurnTokens.has(agentName);
+            const providerGate = this.providerGates?.get(agentName);
+            // A primary can own provider admission while yielding to an already in-flight
+            // auxiliary call. Keep this agent's later wakes queued, but do not block the
+            // framework event loop or other residents while that auxiliary call settles.
+            const providerPrimaryWaiting = (providerGate?.primaryDepth ?? 0) > 0 && !this.activeTurnTokens.has(agentName);
+            if (providerPrimaryWaiting || turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
                 // Re-queue requests, but warn if they've been pending too long
                 const oldest = Math.min(...requests.map(r => r.timestamp));
                 if (now - oldest > STALE_REQUEST_MS &&
@@ -4136,10 +4354,21 @@ export class AgentFramework {
                 // exactly this class of silent drop. One stderr line per drop.
                 console.error(`[inference-dropped] agent=${agentName} reason=policy-skip ` +
                     `requests=${requests.length} triggers=${requests.map((r) => r.reason).join(',')}`);
+                const gate = this.providerGates.get(agentName);
+                if (gate?.primaryPending && this.providerAccelerationRecoveries.has(agentName)) {
+                    gate.primaryPending = false;
+                    this.providerAccelerationRecoveries.delete(agentName);
+                    this.flushAuxiliaryAdmission(agentName);
+                }
                 continue;
             }
             // Start streaming inference (non-blocking — driveStream runs in background)
-            const trigger = requests[0];
+            // The request that grants the turn-alive exception must also define the
+            // downstream turn semantics. An ordinary wake can already be pending
+            // when the tool boundary appends a context-budget restart; selecting
+            // requests[0] in that mixed batch bypassed the turn lock because a
+            // restart existed, then treated the continuation as a fresh turn.
+            const trigger = budgetRestart ?? requests[0];
             // Route this turn's auto-published speech to the channel that triggered
             // it (item-3 redux). A batched wake may carry several triggering channels
             // (messages arrived in >1 channel while the agent was busy/idle):
@@ -4218,7 +4447,9 @@ export class AgentFramework {
                 : id);
         }
         const suppressedNote = suppressed > 0
-            ? `${suppressed} plain-speech segment(s) suppressed (explicit send in the same round — resend with a send tool if it was meant to be heard)`
+            ? agent.proseRouting === 'disabled'
+                ? `${suppressed} plain-speech segment(s) suppressed (proseRouting=disabled — publish only with an explicit send tool)`
+                : `${suppressed} plain-speech segment(s) suppressed (explicit send in the same round — resend with a send tool if it was meant to be heard)`
             : '';
         const text = shown.length > 0
             ? `[delivered] plain speech → ${shown.join(' · ')}${suppressedNote ? ` · ${suppressedNote}` : ''}`
@@ -4571,6 +4802,13 @@ export class AgentFramework {
             console.error('maybePrimeProseMode: state read/write failed:', err);
             return;
         }
+        // Disabled mode is intentionally silent: no model-visible routing prose.
+        // The resident publishes only through explicit tools. This contains
+        // continuity-summary locus leaks (Host #96).
+        if (mode === 'disabled') {
+            console.error(`[prose] ${agent.name}: disabled mode recorded (no primer injected)`);
+            return;
+        }
         try {
             const id = agent.getContextManager().addMessage('user', [{ type: 'text', text: proseModePrimer(mode) }], { system: true, kind: 'prose-routing-primer' });
             this.emitTrace({ type: 'message:added', messageId: id, source: 'prose-routing-primer' });
@@ -4580,7 +4818,32 @@ export class AgentFramework {
             console.error('maybePrimeProseMode: failed to append primer:', err);
         }
     }
-    async startAgentStream(agent, trigger, attempt = 0) {
+    async startAgentStream(agent, trigger, attempt = 0, providerGateAlreadyHeld = false) {
+        const ownsProviderGate = !this.ephemeralRuns.has(agent.name) && !this.conversationAgentHomes.has(agent.name);
+        if (ownsProviderGate && !providerGateAlreadyHeld) {
+            this.acquirePrimaryProviderGate(agent.name);
+            const gate = this.providerGate(agent.name);
+            if (gate.auxiliaryInFlight > 0) {
+                // Do not await inside processInferenceRequests: one slow auxiliary call for
+                // this resident must not block events or other residents. Admission stays
+                // owned and the continuation receives it after the in-flight call settles.
+                void this.waitForAuxiliaryIdle(agent.name).then(async () => {
+                    if (this.providerAdmissionClosed) {
+                        this.releasePrimaryProviderGate(agent.name);
+                        return;
+                    }
+                    await this.startAgentStream(agent, trigger, attempt, true);
+                }).catch((error) => {
+                    this.releasePrimaryProviderGate(agent.name);
+                    console.error(`[provider-cooldown] failed to resume primary for ${agent.name}:`, error);
+                });
+                return;
+            }
+            if (this.providerAdmissionClosed) {
+                this.releasePrimaryProviderGate(agent.name);
+                return;
+            }
+        }
         // Mark the turn alive before ANYTHING awaits (hooks, compile, stream
         // setup): from here until this turn's teardown, cross-turn writers defer
         // (addMessage guard) instead of appending — nothing may enter the window
@@ -4601,12 +4864,14 @@ export class AgentFramework {
         this.activeTurnTokens.set(agent.name, turnToken);
         let tokenHandedOff = false;
         try {
-            tokenHandedOff = await this.beginAgentTurn(agent, trigger, attempt, turnToken);
+            tokenHandedOff = await this.beginAgentTurn(agent, trigger, attempt, turnToken, ownsProviderGate);
         }
         finally {
             if (!tokenHandedOff && this.activeTurnTokens.get(agent.name) === turnToken) {
                 this.activeTurnTokens.delete(agent.name);
             }
+            if (!tokenHandedOff && ownsProviderGate)
+                this.releasePrimaryProviderGate(agent.name);
         }
     }
     /**
@@ -4614,7 +4879,7 @@ export class AgentFramework {
      * turn token unconditionally. Returns true iff the token was handed off to
      * driveStream (whose finally then owns clearing it).
      */
-    async beginAgentTurn(agent, trigger, attempt, turnToken) {
+    async beginAgentTurn(agent, trigger, attempt, turnToken, ownsProviderGate) {
         // Flush messages deferred during the PREVIOUS turn — before the
         // checkpoint, the locus announcement, and the compile — so a turn started
         // by a queued wake actually CONTAINS the message that woke it. (2026-07-31
@@ -4700,10 +4965,10 @@ export class AgentFramework {
             this.proseHybridSuppressed.delete(agent.name);
             if (agent.proseRouting === 'hybrid')
                 this.proseTargetPins.delete(agent.name);
-            if (agent.proseRouting === 'explicit') {
-                // Explicit prose routing: there is no locus. The model names every
-                // destination in-band (`>>` prefixes); the only turn state is the
-                // sticky target, reset for each fresh turn. No freeze, no announce.
+            if (agent.proseRouting === 'explicit' || agent.proseRouting === 'disabled') {
+                // Explicit and disabled prose routing have no inferred locus.
+                // Explicit mode uses a turn-scoped `>>` target; disabled mode has no
+                // prose target at all. Neither mode freezes or announces a locus.
                 this.proseTargetPins.delete(agent.name);
                 this.proseContinuations.delete(agent.name);
                 this.midTurnInputSignals.delete(agent.name);
@@ -4783,7 +5048,7 @@ export class AgentFramework {
                 }
             }
             const { stream, request: compiledRequest } = await agent.startStreamWithInjections(tools, injections);
-            const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest);
+            const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest, ownsProviderGate);
             this.activeStreams.set(agent.name, handle);
             // Handoff: driveStream captured the token in its synchronous prefix;
             // its finally now owns clearing it. The caller's finally must not.
@@ -4802,6 +5067,12 @@ export class AgentFramework {
                 stack: err.stack,
             });
             agent.reset();
+            if (ownsProviderGate && this.holdProviderAcceleration(agent, err, trigger)) {
+                // Capacity scheduling is not poisoned history. The cooldown timer owns
+                // one later fresh compile; no immediate retry or exhaustion marker.
+                this.eventGate?.onInferenceEnded(agent.name);
+                return false;
+            }
             const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
             if (action.retry) {
                 await new Promise((resolve) => setTimeout(resolve, action.delayMs));
@@ -4849,7 +5120,7 @@ export class AgentFramework {
             return false;
         }
     }
-    async driveStream(agent, stream, requestSnapshot, trigger, attempt = 0, compiledRequest) {
+    async driveStream(agent, stream, requestSnapshot, trigger, attempt = 0, compiledRequest, ownsProviderGate = false) {
         const startTime = Date.now();
         const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
@@ -4906,9 +5177,11 @@ export class AgentFramework {
         //     this doesn't violate never-guess: it says "attending to what you
         //     sent here", which is true regardless of where the reply goes.
         //     Heartbeat/no-trigger explicit turns show no indicator.
-        const typingChannel = agent.proseRouting === 'explicit'
-            ? trigger?.channelId ?? null
-            : resolveTurnLocus();
+        const typingChannel = agent.proseRouting === 'disabled'
+            ? null
+            : agent.proseRouting === 'explicit'
+                ? trigger?.channelId ?? null
+                : resolveTurnLocus();
         if (typingChannel)
             this.channelRegistry.startTyping(typingChannel);
         // MCPL Spec 14.3 outgoing streaming: route text deltas to their
@@ -4936,7 +5209,7 @@ export class AgentFramework {
             turnIndex: 0,
             phase: 'started',
         });
-        const proseStream = this.channelRegistry
+        const proseStream = this.channelRegistry && agent.proseRouting !== 'disabled'
             ? new ProseStreamRouter({
                 mode: agent.proseRouting === 'explicit' ? 'explicit' : agent.proseRouting === 'hybrid' ? 'hybrid' : 'locus',
                 initialTarget: typingChannel,
@@ -5109,7 +5382,11 @@ export class AgentFramework {
                                 liveProseRouting = true;
                                 const roundSegments = splitProseSegments(assistantBlocks);
                                 if (roundSegments.length > 0) {
-                                    if (agent.proseRouting === 'hybrid') {
+                                    if (agent.proseRouting === 'disabled') {
+                                        console.error(`[routing] ${agent.name}: mid-turn prose NOT routed (proseRouting=disabled)`);
+                                        this.recordProseSuppression(agent.name, roundSegments.length);
+                                    }
+                                    else if (agent.proseRouting === 'hybrid') {
                                         if (turnSilenced) {
                                             this.recordProseSuppression(agent.name, roundSegments.length);
                                         }
@@ -5210,6 +5487,9 @@ export class AgentFramework {
                         else {
                             agent.addAssistantResponse(terminalContent);
                         }
+                        // Bind the cooldown receipt to this fresh, successful request —
+                        // never to the frozen request that received the 429.
+                        this.recordProviderAccelerationRecovery(agent, compiledRequest, response.stopReason);
                         // §10.5: context/afterInference is removed in 0.5.0 — no
                         // content leaves the host here. Turn boundaries are announced
                         // by the metadata-only inference/lifecycle notifications
@@ -5402,7 +5682,11 @@ export class AgentFramework {
                                 .join('\n')
                                 .trim();
                             if (speechText) {
-                                if (agent.proseRouting === 'hybrid') {
+                                if (agent.proseRouting === 'disabled') {
+                                    console.error(`[routing] ${agent.name}: text-only prose NOT routed (proseRouting=disabled)`);
+                                    this.recordProseSuppression(agent.name, 1);
+                                }
+                                else if (agent.proseRouting === 'hybrid') {
                                     const locus = resolveTurnLocus();
                                     console.error(`[prose] ${agent.name}: text-only turn -> hybrid prose gateway`);
                                     try {
@@ -5468,7 +5752,13 @@ export class AgentFramework {
                             // land before the trailing prose. Awaited even when silenced —
                             // the chain may still be flushing earlier rounds' posts.
                             await turnSpeechChain;
-                            if (agent.proseRouting === 'hybrid') {
+                            if (agent.proseRouting === 'disabled') {
+                                if (segments.length > 0) {
+                                    console.error(`[routing] ${agent.name}: tool-call trailing prose NOT routed (proseRouting=disabled)`);
+                                    this.recordProseSuppression(agent.name, segments.length);
+                                }
+                            }
+                            else if (agent.proseRouting === 'hybrid') {
                                 if (silenced && segments.length > 0) {
                                     this.recordProseSuppression(agent.name, segments.length);
                                 }
@@ -5576,6 +5866,11 @@ export class AgentFramework {
                             break;
                         this.abortAgentScript(agent.name, 'stream error');
                         agent.reset();
+                        if (ownsProviderGate && this.holdProviderAcceleration(agent, err, trigger)) {
+                            lifecyclePhase = 'failed';
+                            this.eventGate?.onInferenceEnded(agent.name);
+                            break;
+                        }
                         const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
                         if (action.retry) {
                             await new Promise((resolve) => setTimeout(resolve, action.delayMs));
@@ -5709,10 +6004,21 @@ export class AgentFramework {
             }
         }
         catch (error) {
-            // Stream itself threw (unexpected) — no retry path here, so also emit
-            // inference:exhausted so ephemeral agent promises can settle.
+            // Stream itself threw. Organization acceleration is deferred from a
+            // fresh compile; every other throw keeps the ordinary exhausted path.
             const err = error instanceof Error ? error : new Error(String(error));
             const durationMs = Date.now() - startTime;
+            if (ownsProviderGate && this.holdProviderAcceleration(agent, err, trigger)) {
+                this.emitTrace({ type: 'inference:failed', agentName: agent.name, error: err.message, stack: err.stack });
+                this.logInference({ timestamp: startTime, agentName: agent.name, requestId, success: false,
+                    error: `Provider acceleration cooldown: ${err.message}`,
+                    request: compiledRequest ?? { note: 'streaming request rate-limited' }, durationMs });
+                this.abortAgentScript(agent.name, 'provider acceleration cooldown');
+                lifecyclePhase = 'failed';
+                agent.reset();
+                this.eventGate?.onInferenceEnded(agent.name);
+                return;
+            }
             this.emitTrace({
                 type: 'inference:failed',
                 agentName: agent.name,
@@ -5768,6 +6074,8 @@ export class AgentFramework {
             // wedge). onInferenceEnded is idempotent, so a redundant call is safe.
             this.eventGate?.onInferenceEnded(agent.name);
             this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+            if (ownsProviderGate)
+                this.releasePrimaryProviderGate(agent.name);
             // Stop the typing indicator on every exit path (complete, error,
             // exhausted, abort) so it never sticks after the turn ends.
             this.channelRegistry?.stopTyping();
@@ -5826,6 +6134,91 @@ export class AgentFramework {
             agentName: call.callerAgentName ?? '__ephemeral__',
         });
     }
+    /**
+     * Admin puppet: execute ONE tool call AS an agent and persist the
+     * tool_use + tool_result pair in that agent's window exactly as a
+     * model-initiated call is stored.
+     *
+     * Born from the princess exemplar surgery (2026-08-23). Her folded
+     * narrative said "I have no tools"; every past tool_use/tool_result pair
+     * had folded out of her context, so the act of calling had no in-context
+     * exemplar and she could not emit her first call despite 30 eidoverse
+     * tools riding every request. Placing one first-person pair restored the
+     * capacity. That repair required stop → store surgery → restart; this
+     * method is the live path — and the general lever for demonstrating an
+     * affordance to a model that cannot find it (older models especially).
+     *
+     * Semantics:
+     * - Refused unless the agent is idle: puppeting mid-turn would corrupt
+     *   the turn state machine and the live stream's wire ordering.
+     * - Refused for tools outside the agent's own surface (canUseTool): the
+     *   stored pair must be an act the agent could genuinely have taken.
+     * - The call executes FOR REAL through the shared dispatch (MCPL,
+     *   channel tools, utils, modules) with the agent's provenance — a
+     *   puppeted walk_to actually moves the avatar.
+     * - Storage byte-follows the ordinary path: a bare tool_use assistant
+     *   message (no fabricated thinking or text — a stored assistant turn
+     *   with unverifiable thinking is the labclaude 400 class) plus a
+     *   tool_result under the same bounded spill policy (issue #89).
+     * - Does NOT request inference; the agent sees the pair on its next
+     *   wake. Speak to the agent afterward if a wake is wanted.
+     * - Provenance is loud in traces (puppet:tool-call) and the host log,
+     *   deliberately NOT in the stored messages — metadata there would break
+     *   byte-parity with real turns. Whether to disclose to the resident is
+     *   the operator's call; the princess precedent was disclosed first.
+     */
+    async puppetToolCall(agentName, toolName, input) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        if (agent.state.status !== 'idle') {
+            throw new Error(`puppet refused: agent ${agentName} is ${agent.state.status} (requires idle — ` +
+                `injecting a turn under an active stream corrupts wire ordering)`);
+        }
+        const onSurface = this.getToolsForAgent(agentName)
+            .some((t) => t.name === toolName && agent.canUseTool(t.name));
+        if (!onSurface) {
+            throw new Error(`puppet refused: tool ${toolName} is not on ${agentName}'s surface — ` +
+                `the stored pair must be an act the agent could genuinely have taken`);
+        }
+        // Anthropic-shaped id so the stored pair is indistinguishable from a
+        // provider-issued call.
+        const alphabet = 'ABCDEFGHJKMNPQRSTVWXYZabcdefghjkmnpqrstvwxyz0123456789';
+        let suffix = '';
+        for (let i = 0; i < 22; i++)
+            suffix += alphabet[Math.floor(Math.random() * alphabet.length)];
+        const toolUseId = `toolu_01${suffix}`;
+        const started = Date.now();
+        const result = await this.executeToolCall({
+            id: toolUseId,
+            name: toolName,
+            input,
+            callerAgentName: agentName,
+        });
+        const durationMs = Date.now() - started;
+        // Store the pair through the same shapes the ordinary path uses. Build
+        // the result blocks BEFORE storing the tool_use: the spill path awaits,
+        // and a message arriving during that await must land before the pair,
+        // never between tool_use and its tool_result. The two addMessage calls
+        // below are synchronous and adjacent — nothing can interleave.
+        const { blocks } = await this.buildStoredToolResultContent([{ id: toolUseId, name: toolName, input, result, durationMs }], this.resolveToolResultInlineCap(agent).cap);
+        const cm = agent.getContextManager();
+        cm.addMessage(agentName, [
+            { type: 'tool_use', id: toolUseId, name: toolName, input },
+        ]);
+        cm.addMessage('user', blocks);
+        this.emitTrace({
+            type: 'puppet:tool-call',
+            agentName,
+            toolName,
+            toolUseId,
+            isError: !!result.isError,
+            durationMs,
+        });
+        console.log(`[puppet] ${agentName}: ${toolName} → ${result.isError ? 'ERROR' : 'ok'} ` +
+            `in ${durationMs}ms (${toolUseId})`);
+        return { toolUseId, result };
+    }
     async executeToolCallFrom(call, origin) {
         // Client-side programmatic tool calling for promise-based callers
         // (SubagentModule ephemerals). Keyed by callerAgentName so each ephemeral
@@ -6948,6 +7341,19 @@ export class AgentFramework {
                 name,
                 status: agent.state.status,
                 consecutiveInferenceFailures: this.consecutiveInferenceFailures.get(name) ?? 0,
+                providerAdmission: (() => {
+                    const gate = this.providerGates?.get(name);
+                    const cooldown = this.providerAccelerationCooldowns?.get(name);
+                    return {
+                        primaryActive: (gate?.primaryDepth ?? 0) > 0,
+                        primaryPending: gate?.primaryPending ?? false,
+                        auxiliaryInFlight: gate?.auxiliaryInFlight ?? 0,
+                        auxiliaryDeferred: gate?.deferredAuxiliary ?? 0,
+                        cooldownUntil: cooldown?.until ?? null,
+                        heldRequests: cooldown?.heldRequests.length ?? 0,
+                        lastRecovery: this.providerAccelerationLastRecovery?.get(name) ?? null,
+                    };
+                })(),
                 lastInference: this.lastInferenceAt.get(name) ?? null,
                 refusalStats: this.refusalStats.get(name) ?? null,
             })),
@@ -8615,7 +9021,7 @@ export class AgentFramework {
                 if (opened) {
                     this.activeTriggerChannels.set(agentName, opened);
                     const openerAgent = this.agents.get(agentName);
-                    if (openerAgent && openerAgent.proseRouting !== 'explicit') {
+                    if (openerAgent && (openerAgent.proseRouting === 'locus' || openerAgent.proseRouting === 'hybrid')) {
                         this.turnLocusPins.set(agentName, opened);
                         this.lastAnnouncedLocus.set(agentName, opened);
                         result = {
@@ -8814,7 +9220,10 @@ export class AgentFramework {
         if (announce && this.channelRegistry) {
             const text = input.message ?? `💤 Going quiet for ${human}. I'll still see messages, but won't respond until I wake.`;
             const agent = this.agents.get(agentName);
-            if (agent?.proseRouting === 'explicit') {
+            if (agent?.proseRouting === 'disabled') {
+                console.error(`[sleep] ${agentName}: proseRouting=disabled — sleep announcement not posted`);
+            }
+            else if (agent?.proseRouting === 'explicit') {
                 // Explicit mode: announce to the turn's sticky prose target if the
                 // model has set one; otherwise stay quiet — never guess a channel.
                 const target = this.proseTargetPins.get(agentName);