@animalabs/agent-framework 0.27.0 → 0.28.0

package/dist/src/framework.d.ts

@@ -88,11 +88,15 @@ export interface HostModeStatus {
      * is false until it has. A parked continuation of a turn is counted here
      * and, as a turn alive, in `activeTurns` and `activeTurnAgents`. */
     parkedAdmissions: number;
-    /** Inference requests parked by the quiesce wake gate (while quiesced), or
-     * simply queued (while serving — non-zero right after a resume until the
-     * scheduler's next pass consumes them). Continuations of a held turn
-     * (budget restart, tool results) and a held turn's retry, which a quiesce
-     * lets through, are never counted. */
+    /** Inference requests waiting to start: queued (parked by the quiesce wake
+     * gate while quiesced, or, while serving, until the scheduler's next pass
+     * takes them), in a scheduler pass's hands, or held by a provider hold (an
+     * acceleration or host hold, or a provider's stated wait). There, a start
+     * that carries a turn on counts as the wakes merged into it. A start parked
+     * on provider admission behind an auxiliary call counts once in
+     * `parkedAdmissions` instead, however many wakes are merged into it.
+     * Continuations of a turn (budget restart, tool results) and a held turn's
+     * retry, which a quiesce lets through, are never counted. */
     gatedRequests: number;
     /** code_execution scripts still running that no call is waiting on: left
      * running after a yield, outside any turn. Quiesce does NOT stop them —
@@ -106,11 +110,12 @@ export interface HostModeStatus {
      * turn token held with no stream to cancel and no check ahead to stop it
      * at (a puppet tool turn, a store surgery's reservation, a turn finishing
      * its last delivery), or a turn with no stream that hasn't reached its
-     * next check, such as one in a hook that hasn't returned. A turn whose
-     * stream the abandon cancelled isn't listed, even one still running when
-     * the grace runs out, as one whose tool-result guard waits on its speech
-     * may be. Present only after an abandon that left such turns behind, while
-     * the host stays quiesced. */
+     * next check, such as one in a hook that hasn't returned, or a turn whose
+     * stream's cancel threw with no check ahead, so that its stream goes on.
+     * A turn whose stream the abandon cancelled isn't listed, even one still
+     * running when the grace runs out, as one whose tool-result guard waits on
+     * its speech may be. Present only after an abandon that left such turns
+     * behind, while the host stays quiesced. */
     unabandonable?: string[];
 }
 /**
@@ -168,25 +173,27 @@ interface InferenceToolSnapshot {
  * this policy after one send, and the framework is the one retry layer: each
  * retry is a fresh compile, a stop cancels its wait, and the wait is seen.
  * The decision is membrane's (`@animalabs/membrane/retry`), on the settings
- * given (membrane's defaults unless a host passes its own, e.g. from a
- * recipe's retry config):
+ * given: membrane's, with the two changes below for the turn path, unless a
+ * host passes its own (e.g. from a recipe's retry config), which are taken as
+ * they are:
  * - not retryable (400 invalid_request, 401 auth, context_length, safety,
  *   a caller-code error): terminal on the first failure. Retrying them burns
  *   API quota without any chance of success; production traces showed clerk +
  *   reviewer wasting 4 inferences on each 400 due to blind retries.
  * - overloaded (a 529, or an overloaded error mid-stream): the overloaded
- *   schedule, jittered (by default 7 tries, 10 s doubling to 5 min, ~10 min).
+ *   schedule, jittered, 10 s doubling to 5 min (by default 13 tries, where
+ *   membrane's settings have 7: about 30 min).
  * - rate limited (429): the base schedule with at least 5 tries.
  * - any other retryable failure, a stream deadline on a sent request
  *   included (membrane leaves those to its caller): the base schedule (by
  *   default 3 tries, 1 s then 2 s).
  * A provider's stated wait (`retryAfterMs`) is waited when it is longer than
- * the backoff, up to the framework's own cap (PROVIDER_ACCELERATION_MAX_
- * COOLDOWN_MS, ten minutes) where a schedule's ceiling is lower; past it the
- * turn ends here. (Before this policy runs, the framework holds a resident
- * for a stated wait or an acceleration 429 itself, and ends an ephemeral run
- * on a wait past that cap; see holdProviderAcceleration and
- * nonOwningProviderWait.)
+ * the backoff, up to the schedule's ceiling, which by default is at least the
+ * framework's own cap (PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, ten minutes);
+ * past it the turn ends here. A host's own settings keep their ceilings.
+ * (Before this policy runs, the framework holds a resident for a stated wait
+ * or an acceleration 429 itself, and ends an ephemeral run on a wait past
+ * that cap; see holdProviderAcceleration and nonOwningProviderWait.)
  * An error that isn't a MembraneError is retried as a retryable failure, on
  * the base schedule.
  */
@@ -197,6 +204,40 @@ export declare class DefaultErrorPolicy implements ErrorPolicy {
     constructor(settings?: RetrySettings);
     onInferenceError(error: Error, _agentName: string, attempt: number): ErrorAction;
 }
+export interface ReinitAlertText {
+    opening: string;
+    message: string;
+}
+export declare const REINIT_MOVES: readonly ['undo', 'redo', 'rollback', 'suppression', 'branch switch'];
+export type ReinitMove = (typeof REINIT_MOVES)[number];
+export declare function refusedWorkAlert(move: ReinitMove, cause: string): ReinitAlertText;
+export declare function restoreAlert(restore: {
+    source: string;
+    now: string;
+    selected: boolean;
+    cause: string;
+} & ({
+    move: 'rollback';
+    managerCurrent?: false;
+} | {
+    move: 'suppression';
+    managerCurrent: boolean;
+})): ReinitAlertText;
+export declare function disposalAlert(disposal: {
+    move: ReinitMove;
+    heldWrites?: number;
+    reinitFailed?: string;
+    cleanupFailed?: string;
+}): ReinitAlertText;
+export declare function longHoldAlert(hold: {
+    move: string;
+    agentName: string;
+    heldSeconds: number;
+    queued: number;
+    reinitializing?: string;
+    waitingForMaintenance: boolean;
+}): ReinitAlertText;
+export declare function opsWebhookText(message: string): string;
 /**
  * Whether the poison-history breaker may shed the newest exchange for a
  * failure: an `invalid_request` at HTTP 400, 413 or 422 or with no status, or
@@ -287,6 +328,7 @@ export declare class AgentFramework {
     private stopPromise;
     private stopCompleted;
     private ownedStoreClosed;
+    private ownedStoreManagersClosed;
     /** Whether the latest stop() got through its teardown with nothing failed:
      * every step and every wait up to and including the one on awareness
      * drains, whatever failed after that, in the storage work that finishes
@@ -314,6 +356,8 @@ export declare class AgentFramework {
     private inferencePolicy;
     private errorPolicy;
     private pendingRequests;
+    private readonly exhaustedTurns;
+    private readonly roundTurns;
     private running;
     private loopPromise;
     /** Quiesce/maintenance mode (issue #122). DELIBERATELY separate from
@@ -365,6 +409,7 @@ export declare class AgentFramework {
     private providerWaits;
     /** Wakers for error-policy retry waits in progress: stop() ends them. */
     private retryWaitWakers;
+    private waitingTraceEveryMs;
     private providerAdmissionClosed;
     /** Invalidates framework turns still assembling when stop begins. */
     private lifecycleGeneration;
@@ -379,6 +424,7 @@ export declare class AgentFramework {
      *  framework, and tests set it by cast. */
     private inboundAcceptanceObserver?;
     private streamBoundaryEnds;
+    private streamCarries;
     /** A tool boundary injected fresh CONVERSATIONAL input (a real message,
      *  or an edit the coalescer marks as the agent's first view; not a system
      *  marker or a reaction, reaction removal, edit or deletion marker) into
@@ -409,6 +455,7 @@ export declare class AgentFramework {
      * next turn.
      */
     private turnRouting;
+    private readonly reasoningLoss;
     /**
      * The latest link of each agent's chain of queued prose deliveries. Every
      * stream queues its own behind it, a fresh turn's included, so the agent's
@@ -707,6 +754,11 @@ export declare class AgentFramework {
      *  queued, and clears them. While a name is here, no other flush drains
      *  its queue (drainDeferredFor). */
     private readonly releasesAfterResume;
+    private readonly managerReleases;
+    private readonly releasedByCleanup;
+    private readonly openManagers;
+    private readonly openManagerRefs;
+    private readonly collectedManagers;
     /** The coalescing commit in flight, if any (see commitCoalescingDurable). */
     private coalescingCommit;
     private inferenceRouter;
@@ -743,12 +795,13 @@ export declare class AgentFramework {
     private readonly thinkingLossIncidents;
     /** Per live stream that can be noted, its rows so far after the compiled messages (noteRoundSent). */
     private readonly streamRequestNotes;
+    private readonly streamCarried;
     /** Per pending round's blocks (pendingAssistantBlocks' value), what membrane held as that round's reply
      *  (`roundContent`, its results left out); null where the round has no `roundContent` (XML or fallback). Keyed by
      *  the blocks themselves, so it goes wherever they go. */
     private readonly pendingRoundSent;
-    /** Per agent, a round that called code_execution and waits for those calls'
-     *  results before its prose is routed (ScriptRound). */
+    /** Per agent, a round that called code_execution or sent, and waits for
+     *  those calls' results before its prose is routed (ScriptRound). */
     private scriptRounds;
     /** Each code_execution result, by the round that dispatched its call: it
      *  settles only that round, even if a newer round reuses its call id. */
@@ -852,6 +905,9 @@ export declare class AgentFramework {
      * scheduler, ephemeral admission and puppet entry points.
      */
     private surgeryHold;
+    private readonly conversationSpawnsInFlight;
+    private syncMoveReinit;
+    private holdAlertMs;
     /** Serialize per-server drains so reconnect and an online undo cannot race. */
     private discordAwarenessDrains;
     /** The servers whose running pass a later trigger joined
@@ -859,9 +915,10 @@ export declare class AgentFramework {
      *  more what it had already tried. */
     private discordAwarenessDrainsJoined;
     private eventGate;
+    private judgeWired;
+    /** The heartbeat (FrameworkConfig.heartbeat), when the host turns it on. */
+    private heartbeat;
     private usageTracker;
-    /** Explicit-send or private suppression carried into a tool-result-guard retry. */
-    private guardRetryTurnSilenced;
     /** Presentation-only wall-clock zone; persistence remains UTC/epoch. */
     private readonly timeZone;
     private constructor();
@@ -879,8 +936,9 @@ export declare class AgentFramework {
     /**
      * The error a failed create() rejects with, once what it acquired is
      * released: the framework it had begun is stopped, with
-     * FAILED_CREATE_TEARDOWN_TIMEOUT_MS as stop()'s teardownTimeoutMs, and a
-     * store create() opened is closed even when that stop failed or timed out.
+     * FAILED_CREATE_TEARDOWN_TIMEOUT_MS as stop()'s teardownTimeoutMs, the
+     * context managers it opened are closed, and a store create() opened is
+     * closed even when that stop failed or timed out.
      * stop() keeps an owned store open when any of its waits fails or times
      * out, so that it can be called again, but no one can call it on a
      * framework that create() never returned. When the release doesn't finish
@@ -979,8 +1037,9 @@ export declare class AgentFramework {
     /** What start() and addModule() pass before either begins work of a
      * lifecycle. A stop() still running refuses both, from the moment it
      * claims its attempt until that attempt settles. A failed stop() has
-     * cleared its attempt, unless it closed an owned store, which is refused
-     * first. A completed stop() is cleared, and the call goes on as before;
+     * cleared its attempt, unless it closed an owned store, or the context
+     * managers it closes before that store, which are refused first. A
+     * completed stop() is cleared, and the call goes on as before;
      * whether a lifecycle should begin after a stop() is #315's question. */
     private resetCompletedStop;
     /** Register before invoking the body, so the set holds the operation for
@@ -1052,7 +1111,56 @@ export declare class AgentFramework {
      * under a surgery's hold, and no failure is reported for it.
      */
     private withdrawMaintenanceWhenStopping;
+    /**
+     * Wakes the framework holds for `agentName` that need no new event: a
+     * request already queued for it (it runs as soon as the agent is free) and
+     * turns a provider cooldown holds until its end. The reply judge is told of
+     * them beside the gate's own timers, so it can weigh what waiting costs.
+     */
+    private upcomingWakesFor;
+    /** The agents the heartbeat wakes: the residents, not conversation forks,
+     *  ephemeral runs or the subconscious, which keep windows of their own. */
+    private heartbeatTargets;
+    /**
+     * The event a heartbeat wake is to the gate: a push from the server id
+     * `heartbeat`, as heartbeat-mcpl's ticks and reminders were. So the
+     * agent's rules govern it as they governed those (a rule matching
+     * `source: "heartbeat"`, a `defer` default), and its sleep lets it through,
+     * as it lets that server id through.
+     */
+    private heartbeatGateEvent;
+    /**
+     * Deliver one of the heartbeat's wakes, as heartbeat-mcpl's push events
+     * were: a message-mode tick's or a reminder's text is stored, and the gate
+     * decides the wake by the agent's rules (heartbeatGateEvent), a sleep
+     * letting it through as it lets that server's pushes through. A silent
+     * tick stores no prompt: its turn, when the gate triggers one, is a silent
+     * heartbeat (silent-heartbeat.ts), prose suppressed. As for a stored push,
+     * the wake of the agent the text was delivered to is dropped once a
+     * request of its own has carried and answered the text (readsWriteFor);
+     * another resident's isn't tied to it.
+     */
+    private deliverHeartbeat;
+    /** Handle a call to one of the heartbeat's tools. */
+    private dispatchHeartbeatToolCall;
+    /**
+     * Why `agentName` may not make this heartbeat call, or null when it may.
+     * The heartbeat is the agent's, and wakes its residents: a conversation
+     * fork, an ephemeral run or the subconscious may look at it, but not
+     * change it or set a reminder that would wake someone else. Refused before
+     * the tool runs, as a fork's sleep is.
+     */
+    private heartbeatRefusal;
+    /** Run a heartbeat call, its throw an error result. */
+    private runHeartbeatTool;
     private auxiliaryMembraneFor;
+    /**
+     * The reply judge's calls. None waits: under the agent's holds a call is
+     * refused without being made, and the agent's turn stops the judge. A call
+     * that fails records the wait its provider states, if any, and holds
+     * nothing else.
+     */
+    private judgeMembraneFor;
     /**
      * A conversation agent's auxiliary calls (its context manager's
      * compression). A conversation agent takes no provider gate: admission
@@ -1061,13 +1169,20 @@ export declare class AgentFramework {
      * as a resident's are, so they bind its auxiliary calls too: a held model
      * is refused without a call, and an auxiliary call's own stated wait is
      * recorded for it. (An ephemeral run records nothing, its name being
-     * single-use, so its context manager keeps the plain membrane.) Its
+     * single-use, so its context manager's calls are only withdrawn, as below,
+     * through ephemeralAuxiliaryMembraneFor.) Its
      * compression is the background work a resident's is, whether a
      * maintenance tick or a drain after a message starts it, so it is withdrawn
      * as a resident's is: a call made while a surgery holds the store, or once
      * stop() has closed provider admission, is withdrawn without being sent.
      */
     private conversationAuxiliaryMembraneFor;
+    private ephemeralAuxiliaryMembraneFor;
+    private withdrawnOnceReleased;
+    private releaseManager;
+    private trackManager;
+    private closeManager;
+    private closeOpenManagers;
     /** The framework's membrane, with each complete() call passed through
      *  `admit` along with the model it names. */
     private membraneAdmitting;
@@ -1108,7 +1223,8 @@ export declare class AgentFramework {
      * - An ephemeral run's name is single-use, so a wait recorded for it would
      *   bind nothing, and its caller is waiting on it. A retryable stated wait
      *   up to PROVIDER_ACCELERATION_MAX_COOLDOWN_MS is left to the error policy,
-     *   slept and retried. A longer one, or one that can't be represented, ends
+     *   which sleeps and retries it unless it declines, as a host's own ceiling
+     *   can. A longer one, or one that can't be represented, ends
      *   the run now ('fail'): it is never retried before the provider's time,
      *   and the caller hears why at once.
      * Anything else is the error policy's.
@@ -1552,6 +1668,7 @@ export declare class AgentFramework {
     cancelAgentRuntimeSettingsTransition(agentName: string, opts?: {
         requester?: OperatorRequester;
     }): AgentRuntimeSettingsSnapshot;
+    private refuseRuntimeSettingsChangeUnderHold;
     /**
      * Wakes that passed the scheduler and now own provider admission while
      * waiting for an in-flight auxiliary call to settle — no turn token yet,
@@ -1991,7 +2108,7 @@ export declare class AgentFramework {
     private readAgentRuntimeSettings;
     private validatePersistedAgentRuntimeSettings;
     /** Load resident-set inline caps from framework state, dropping (loudly)
-     *  anything that fails the same validation the live update enforces. A
+     *  anything Number() doesn't read as a finite number of at least 1000. A
      *  failed read is logged and boot goes on without them: nothing is lost,
      *  since persistToolResultInlineCap reads the stored caps again before it
      *  writes one. */
@@ -2076,7 +2193,13 @@ export declare class AgentFramework {
      * `{namespace}/messages`, context log to `{namespace}/context`.
      *
      * Data persists after cleanup for investigation and cross-revert.
-     * Call cleanup() when done to release the ContextManager.
+     * Call cleanup() when done with the agent: the agent can't run again. From
+     * the run's end, or from cleanup(), its ContextManager makes no provider
+     * call, and the calls it has out are aborted. It starts no new call while a
+     * surgery holds the store or once stop() has begun, either; one already out
+     * then runs on until stop(), with a store the framework owns, closes the
+     * ContextManager, before the store. Until then the ContextManager stays
+     * open.
      */
     createEphemeralAgent(config: AgentConfig): Promise<{
         agent: Agent;
@@ -2114,8 +2237,9 @@ export declare class AgentFramework {
      * framework drives the stream (emitting traces, logging, dispatching tools).
      * Returns the agent's speech output when it finishes (no more tool calls).
      * Rejects with ProviderWaitNotSleptError when the run ends rather than sleep
-     * a retryable failure's stated wait, and with a plain Error for any other
-     * ending.
+     * a retryable failure's stated wait longer than the framework's ten-minute
+     * cap, or one it can't represent, and with a plain Error for any other
+     * ending, a stated wait its error policy declines among them.
      *
      * The caller provides a pre-created agent + contextManager (from createEphemeralAgent).
      * The task message should already be in the context manager.
@@ -2146,6 +2270,7 @@ export declare class AgentFramework {
      *  hot-reloaded gate.json (same validation as load), so a rule takes effect
      *  immediately and survives restart. */
     private static readonly WAKE_RULE_TOOLS;
+    private static readonly JUDGED_WAKE_RULE_TOOLS;
     /** Discoverability for event tags (MCPL RFC-001): the reserved chat:* core,
      *  each connected server's declared tag ontology, and gate.js status. */
     private static readonly EVENT_TAGS_TOOL;
@@ -2179,26 +2304,13 @@ export declare class AgentFramework {
      * Mark an inference refusal visibly: react on the message that holds the
      * refused agent's conversational locus (the most recent incoming channel
      * message that isn't a reaction, reaction removal, edit or deletion
-     * marker, apart from an edit the coalescer delivers on acceptance as the
+     * marker or a chat:system notice, apart from an edit the coalescer delivers on acceptance as the
      * agent's first view; an ephemeral run has none, so a subagent's refusal
      * marks no message) with a category-specific emoji. Best-effort —
      * failures are logged, never thrown, and non-Discord loci are silently
      * skipped.
      */
     private reactToRefusal;
-    /**
-     * Shed the newest turn: remove the newest message that isn't a system
-     * message, whoever wrote it, with the rest of its exchange (the tool_use
-     * turn paired with a tool result, and the whole of a body stored in
-     * shards). It adds no marker; the caller keeps one consolidated marker for
-     * the episode (updateRewindMarker). The returned record's descriptor says
-     * what was removed and its size, never the content, while the raw record
-     * survives in the chronicle log for forensics. Returns null when only
-     * system messages remain.
-     *
-     * Shared by the refusal rewind, automatic or forced by `/unstick`, and by
-     * the shed after inference exhaustion (quarantinePoisonedHistory).
-     */
     private shedNewestTurn;
     /**
      * Maintain exactly ONE consolidated marker for the current rewind episode,
@@ -2242,8 +2354,11 @@ export declare class AgentFramework {
         ok: boolean;
         error?: string;
         agentName?: string;
-        /** Agent state at queue time — 'idle' means the turn starts on the next
-         *  scheduler pass; anything else means it runs after the current turn. */
+        /** Agent state at queue time — 'idle' means no turn holds the agent, so
+         *  the turn starts on the next scheduler pass unless a provider hold (a
+         *  provider's stated wait, or a capacity cooldown) holds it until the hold
+         *  ends, or a start of the agent's that waits for an auxiliary call to
+         *  finish goes first; anything else means it runs after the current turn. */
         agentStatus?: string;
         /** True when the host is quiesced: the wake is PARKED, not running, until resume(). */
         quiesced?: boolean;
@@ -2271,7 +2386,7 @@ export declare class AgentFramework {
      *   return the snapshot; the operator lever for draining quarantine or
      *   advancing merges during a quiesce window.
      *
-     *   host-status — report the quiesce state (drained / parked wakes /
+     *   host-status — report the quiesce state (drained / waiting wakes /
      *   scripts left running).
      *
      *   release-provider-wait — end an agent's provider wait (a provider's
@@ -2326,6 +2441,14 @@ export declare class AgentFramework {
      * turn alive (no continuation or held retry of one on its way), or it is
      * refused (OperatorActionError 'agent-busy'), and no turn starts until the
      * switch is done.
+     *
+     * Every agent's context manager is re-initialized for the branch before
+     * the store is released (reinitializeManagers). One whose
+     * re-initialization fails raises an ops alert naming its agent
+     * (`context-reinit-failed`), and the switch still resolves. A switch to the
+     * branch the store is already on re-initializes them too, which is how a
+     * manager left refusing by a failed re-initialization is recovered without
+     * a restart.
      */
     switchBranch(name: string): Promise<void>;
     /**
@@ -2337,12 +2460,30 @@ export declare class AgentFramework {
      *
      * The undone branch is saved so `redo()` can restore it.
      * Returns the checkpoint that was undone, or null if nothing to undo.
+     *
+     * The branch moves under every agent sharing the store, so an undo
+     * reserves the store as a surgery does: every agent must be idle, or it is
+     * refused (OperatorActionError 'agent-busy'). It returns once the store has
+     * moved, and the store stays reserved until every agent's context manager
+     * is re-initialized for the new branch, so no turn starts before then. One
+     * whose re-initialization fails raises an ops alert naming its agent
+     * (`context-reinit-failed`). An undo or redo made before the managers are
+     * done moves the store again under the same reservation, and they are
+     * re-initialized for the branch the last one leaves.
+     *
+     * `settled`, present when the store moved, settles once that reservation
+     * is released, every manager re-initialized or its failure alerted, and
+     * never rejects. Await it before work that needs the store free: a
+     * compile on an agent's own context manager, or a write meant to land at
+     * once, which the reservation would defer. An undo or redo that moves the
+     * store again under the same reservation settles with it.
      */
     undoLastTurn(agentName: string, requester?: OperatorRequester): {
         undone: boolean;
         turnIndex?: number;
         fromBranch?: string;
         toBranch?: string;
+        settled?: Promise<void>;
     };
     /** undoLastTurn's work, for a host/command undo already admitted: a stop()
      *  begun by a trace of one of its turns doesn't refuse the next. */
@@ -2352,11 +2493,15 @@ export declare class AgentFramework {
      *
      * Switches back to the branch that was active before the last undo.
      * Returns false if there's nothing to redo.
+     *
+     * It reserves the store and re-initializes every agent's context manager
+     * as undoLastTurn() does, and its result's `settled` is undoLastTurn()'s.
      */
     redo(agentName: string, requester?: OperatorRequester): {
         redone: boolean;
         fromBranch?: string;
         toBranch?: string;
+        settled?: Promise<void>;
     };
     /**
      * Append a record to the operator action log and broadcast it as an
@@ -2396,6 +2541,13 @@ export declare class AgentFramework {
      * does. Always release in `finally`: a token nobody clears wedges the fleet.
      */
     private reserveStoreForSurgery;
+    private reinitializeManagers;
+    private reportLongHold;
+    private disposeEmptiedForks;
+    private reportReinitFailures;
+    private reportReinitFailure;
+    private beginSyncMove;
+    private reinitializeAfterSyncMove;
     /**
      * A surgery's marker batch, recorded before its body change. If it can't
      * be recorded, the surgery doesn't start, and the error says what the
@@ -2704,6 +2856,7 @@ export declare class AgentFramework {
      * the template ("trunk") is a dormant warm checkpoint, not a listener.
      */
     private routeConversationIncoming;
+    private writeToFork;
     /**
      * Spawn a persistent per-channel conversation agent ("fork") from the
      * template agent: own ContextManager under `conversations/{name}`, seeded
@@ -2736,13 +2889,15 @@ export declare class AgentFramework {
      * Store the router's counters with the spawn's generation, create the fork
      * the decision names and bind its channel to it, registered in
      * conversationSpawns under the channel until it settles. The store runs
-     * inside the spawn's promise, still in routeConversation's synchronous
-     * step, so a store that throws rejects the spawn, which each caller reports
-     * as a failed spawn, rather than throwing out of routeConversation before
-     * the caller's try. routeConversation registers a spawn only when none is
-     * in flight for the channel, and only this spawn's settlement removes it,
-     * so the entry it removes is its own. It's removed before anyone waiting
-     * on it resumes, so a waiter that decides again doesn't find it.
+     * inside the spawn's promise, after it waits out a move's hold, so the
+     * counter lands on the branch the fork is created on; with no hold up, it
+     * runs in routeConversation's synchronous step. Either way a store that
+     * throws rejects the spawn, which each caller reports as a failed spawn,
+     * rather than throwing out of routeConversation before the caller's try.
+     * routeConversation registers a spawn only when none is in flight for the
+     * channel, and only this spawn's settlement removes it, so the entry it
+     * removes is its own. It's removed before anyone waiting on it resumes, so
+     * a waiter that decides again doesn't find it.
      *
      * It binds only while the fork it created is still the agent registered
      * under its name. stop() ends each live fork and unbinds the channels
@@ -3053,7 +3208,10 @@ export declare class AgentFramework {
     /** Record plain-prose segments this turn suppressed without drafts (proseRouting=disabled, or a round withheld before its scripts returned). */
     private recordProseSuppression;
     /**
-     * Silenced plain speech: an explicit send holds it as resendable drafts; a
+     * Silenced plain speech: an explicit send that may have posted where it was
+     * going holds it as resendable drafts (in a round that calls `drafts` and
+     * sends nothing else, 'kept', its plain speech is kept and counted
+     * instead); a
      * deliberate silence (skip_reply, a silent turn, or a private think in
      * the same native round, where that policy applies: an XML-mode round has
      * no verbatim content to route live, so its prose is routed at the turn's
@@ -3061,9 +3219,12 @@ export declare class AgentFramework {
      * counted for the receipt, never drafted. `segments` are the runs exactly
      * as written (splitProseRuns), so a draft keeps the resident's words byte
      * for byte. What it holds, keeps or moves is the round's turn's
-     * (round.routing), whenever the hold runs.
+     * (round.routing), whenever the hold runs. Hybrid speech under a send goes
+     * through routeSilencedHybrid.
      */
     private holdSilencedProse;
+    private routeSilencedHybrid;
+    private sendHoldText;
     /**
      * Hold plain speech as drafts (src/prose-drafts.ts) instead of
      * letting it vanish: journaled durably and recorded for the receipt of the
@@ -3188,6 +3349,8 @@ export declare class AgentFramework {
      * ([discord-send-failed]); this is the success half.
      */
     private appendProseDeliveryReceipt;
+    private nameUnpostedSpeech;
+    private noteFailedTurnEnd;
     /**
      * The closed-channel note alone, in a send's words, at explicit mode's turn
      * end, which has no `[delivered]` receipt since the agent named every
@@ -3340,6 +3503,7 @@ export declare class AgentFramework {
      * left running when it handed the turn on.
      */
     private showTurnTyping;
+    private heardSince;
     /**
      * The channel of the turn's newest arrival whose message is still in the
      * agent's store (TurnRouting.arrivals). A message removed since it was
@@ -3387,6 +3551,7 @@ export declare class AgentFramework {
      * locus-eligible.
      */
     private recordChannelAutoOpenNotice;
+    private tellReasoningLoss;
     /**
      * Write a builder's channel notices in order, each on its own: one that
      * can't be written is logged, and the rest are still written. A reader's
@@ -3637,6 +3802,7 @@ export declare class AgentFramework {
     private draftStateNow;
     /** Locus-preserving explicit publication. Source remains byte-identical in Chronicle. */
     private deliverHybridProse;
+    private deliverHybridEnvelope;
     /** `>>skip_reply {{unsent}}` and its hybrid form: set the latest bounce
      *  draft aside — unless it is being sent right now, which a dismissal
      *  can't call back: the resident is told instead. So are a dismissal whose
@@ -3693,7 +3859,8 @@ export declare class AgentFramework {
      * abandon or a stop of a registered agent settles the turn as it settles a
      * turn's start (endStoppedStart: one inference:aborted, the turn settled,
      * the gate released). Any other drop ends it as a start dropped before it
-     * sends anything ends. That frame, if it hasn't let go of its token yet,
+     * sends anything ends, and settles a registered ephemeral run's turn with
+     * the drop's reason. That frame, if it hasn't let go of its token yet,
      * ends on its own and settles nothing. What was deferred for the agent
      * lands now, or at that frame's end.
      */
@@ -3703,8 +3870,9 @@ export declare class AgentFramework {
      * admission, the hold installs nothing (holdForProviderWait,
      * holdProviderAcceleration), so no retry follows the turn's
      * inference:failed, and the turn ends as a retry a stop cancelled ends, with
-     * an inference:aborted saying so. Nothing is written. True when it ended
-     * the turn.
+     * an inference:aborted saying so. Nothing is written but the
+     * [speech-not-posted] notice, for speech the turn's rounds left unposted.
+     * True when it ended the turn.
      */
     private endFailureAtStop;
     /**
@@ -3739,6 +3907,42 @@ export declare class AgentFramework {
      * terminal, and the caller's goes with it.
      */
     private takeStartStop;
+    /**
+     * Cancel a stream the framework stops, under `kind`, the mark that tells
+     * the stream's end apart from a caller's stop (frameworkCancelledStreams).
+     * A mark records a cancel that happened, so a cancel that throws takes its
+     * mark back, leaving an earlier mark of the same stream as it was, and the
+     * throw goes on to the caller. With no `kind` (the agent holds no stream),
+     * nothing is marked.
+     */
+    private cancelUnderMark;
+    /**
+     * Cancel a live stream the framework ends at a tool boundary (`site` says
+     * where), under its mark. A cancel that throws leaves the stream going: its
+     * mark is taken back (cancelUnderMark), `onFailed` undoes what the site
+     * did ahead of the cancel, and the failure is logged. The stream waits for
+     * the round's results, which the boundary doesn't send, and the turn holds
+     * its token until the stream ends, as an abort does when its own cancel
+     * goes through. Only an operator's abort or stop, or an ephemeral run's
+     * idle watchdog, comes back to it, so an operator alert says so too.
+     * Returns whether the cancel went through.
+     */
+    private cancelLiveStream;
+    /**
+     * Cancel a stream a start compiled and won't send (`site` says why).
+     * Membrane's yielding stream starts its request when it is first iterated,
+     * and this one never is, so it has sent nothing: a cancel that throws is
+     * logged, and the start's cleanup goes on as if it had worked.
+     */
+    private cancelUnsentStream;
+    /**
+     * Cancel a stream that no longer owns its agent: the agent was replaced or
+     * removed, or a newer stream took it. Its frame settles nothing and is
+     * leaving, so a cancel that throws is logged and the frame leaves all the
+     * same. Thrown on, it would reject driveStream's promise, which nothing
+     * awaits but stop().
+     */
+    private cancelSupersededStream;
     /**
      * End a start that a stop reached before it sent anything, through the
      * terminal the same stop gets on a live stream: a caller's stop as
@@ -3830,6 +4034,11 @@ export declare class AgentFramework {
      * assembled field by field (as unit tests do) needs no setup for it.
      */
     private toolsetActCalls?;
+    private puppetChanges?;
+    /** RFC-014 §6.1: a change reaches the agent once, so it goes with a result
+     *  only where the result is stored in an agent's window (the puppet's) or
+     *  handed to an agent awaiting it; null where it may not reach one. */
+    private changeTaker;
     /** A toolsets--act call resolved (resolveAct) to the call of the server's
      *  tool it makes, under that tool's model-facing name and with its
      *  arguments, its id kept; or the reason it can't be sent. */
@@ -3845,27 +4054,26 @@ export declare class AgentFramework {
      * before anything is sent.
      */
     private dispatchToolsetAct;
-    /**
-     * RFC-014 §6.2: a tool result that goes to the agent, with the tool change
-     * its hints made (applied as the result was read) told after the server's
-     * content; taking it means it isn't told again as a notice. The result
-     * itself when there's none, as for every server without toolHints.
-     */
-    private withToolsetChange;
     /** A programmatic call of an MCPL tool: `serverId` and `prefix` as
      *  resolveMcplTool matched them, or as toolsets--act resolved them
-     *  (toolsetActCalls). Its RFC-014 tool change isn't shown with its result,
-     *  which goes to its caller, not necessarily to the agent: it's told as a
-     *  notice (ToolsetController.tellUnlessClaimed). */
+     *  (toolsetActCalls). Its RFC-014 tool change goes with its result only
+     *  where the result is stored in an agent's window or handed to an agent
+     *  awaiting it (changeTaker); any other caller's
+     *  result may never reach one, so its change is told as a notice
+     *  (ToolsetController.tellUnlessClaimed). */
     private executeMcplToolCall;
+    private withWholeChange;
+    private withActStateHint;
     /** Event-pushing wrapper for the model-driven dispatch path. */
     private dispatchCodeExecutionToolCall;
+    private decideWaitingRound;
     /**
      * A model-issued tool's result has arrived. When it answers the last of
-     * the code_execution calls a round waits on (ScriptRound), the round's
-     * prose is routed now, its scripts' calls counted.
+     * the code_execution calls and sends a round waits on (ScriptRound), the
+     * round's prose is routed now, its scripts' calls counted.
      */
     private settleScriptRound;
+    private sendReachOf;
     /**
      * Whether a code_execution call watches a script that can change its
      * round's routing, so the round waits for the call (ScriptRound): a run's
@@ -4169,8 +4377,9 @@ export declare class AgentFramework {
     }>;
     /**
      * Find the MCPL server for a tool: [serverId, prefix], or null.
-     * The tool listing decides: the server whose tools/list offered the
-     * name, after its tool policy, as of the last tool refresh (a server that
+     * The tool listing decides: the server whose tools/list listed the name
+     * (offered to the model, or an RFC-014 dynamic tool, which dispatch then
+     * refuses by that name unless the published list or the server's latest tools/list puts it as static), after its tool policy, as of the last tool refresh (a server that
      * closed since keeps its names until the next one). A name the listing
      * doesn't hold (invented by the model, or no longer listed) goes to the
      * longest matching prefix. Prefixes that meet, such as `foo` and
@@ -4183,10 +4392,13 @@ export declare class AgentFramework {
      * while unregistered. Genuine legacy caller names retain their surface. */
     private canAgentUseTool;
     private agentToolPermissionFailure;
+    private markedInputFailure;
+    private cutOffResults;
     /**
-     * A dispatched call answered without running its tool. RFC-007's lifecycle
-     * forgets it, and its result says it was refused (`ToolResult.refused`), both
-     * from here, so the two can't disagree.
+     * A call answered without running its tool: one the dispatcher refused, or
+     * one in the last round of a response the output limit cut off. RFC-007's
+     * lifecycle forgets it, and its result says it was refused
+     * (`ToolResult.refused`), both from here, so the two can't disagree.
      */
     private refusedResult;
     /**
@@ -4207,7 +4419,8 @@ export declare class AgentFramework {
      * A call as its round's routing counts it, made directly, or by a script
      * and reaching the host while a run or wait call of the round watches it
      * (ScriptRound). A skip_reply refused, because the agent's allowedTools
-     * doesn't name it or because this host can't set the wake it asks for, is
+     * doesn't name it, because its arguments are refused (markedInputRefusal)
+     * or because this host can't set the wake it asks for, is
      * marked refused: it keeps its own round private and silences nothing after
      * it. A refusal withholds the call's effect, not the model's choice to keep
      * its words private. Any other call the list refuses posted nothing, so it
@@ -4804,12 +5017,9 @@ export declare class AgentFramework {
      *  nothing new costs less than a write no wake brings the agent to read
      *  or answer. */
     private deferredWriteDone;
-    /** The mark a wake for `agentName` takes for the write it was queued with
-     *  (`placement`, addMessage's out-param): set only when that write was
-     *  deferred for that agent, since a stored write's wake starts the turn
-     *  that reads it. The scheduler drops the wake once the write needs
-     *  nothing more of the agent (deferredWriteDone). */
-    private readsDeferredFor;
+    private storedMessageDone;
+    private writeAnswered;
+    private readsWriteFor;
     private editMessage;
     private removeMessage;
     private getMessage;
@@ -5496,7 +5706,9 @@ export declare class AgentFramework {
      */
     private refreshMcplTools;
     /**
-     * Report operator tool-name patterns that match no model-facing tool:
+     * Report operator tool-name patterns that match no tool name: one the
+     * model is offered, or an RFC-014 dynamic tool's listed name, which its
+     * class rules and lifecycle selectors match as a direct call's would:
      * `toolClassOverrides` keys and each server's `toolLifecycle.observe.tools`
      * / `toolLifecycle.inputs.tools`. These match `<toolPrefix>--<tool>`, and
      * the default prefix is `mcpl--<serverId>`, so a pattern written against
@@ -5511,8 +5723,9 @@ export declare class AgentFramework {
     private checkToolPatterns;
     /** Every tool name the framework offers to anyone: the shared board plus
      *  each agent's own surface, before presentation visibility (a hidden tool
-     *  is still callable, so classes and lifecycle still apply to it). */
-    private modelFacingToolNames;
+     *  is still callable, so classes and lifecycle still apply to it), and
+     *  every name an MCPL server lists, a dynamic tool's included. */
+    private patternableToolNames;
     /**
      * Handle a tools/list_changed notification with collapse logic.
      * At most 2 refresh cycles can be in-flight: one running and one pending.
@@ -5652,6 +5865,8 @@ export declare class AgentFramework {
      *  through callTool. */
     private handleUtilsToolCall;
     private dispatchUtilsToolCall;
+    private readAgentSettings;
+    private settingsChangedSince;
     private dispatchAgentSettingsToolCall;
     /** Aggregate the event-tag vocabulary: reserved chat:* core + each connected
      *  server's declared tag ontology + gate.js status. */