@animalabs/agent-framework 0.21.1 → 0.22.1

package/dist/src/framework.d.ts

@@ -1,14 +1,15 @@
+import { type PresentationSnapshot } from "./tool-presentation.js";
 import { JsStore } from '@animalabs/chronicle';
 import type { Membrane, NormalizedRequest } from '@animalabs/membrane';
 import { ContextManager } from '@animalabs/context-manager';
 import type { TokenBudget } from '@animalabs/context-manager';
-import type { FrameworkConfig, TraceEventListener, InferenceLogQuery, InferenceLogQueryResult, InferenceLogEntryWithId, ProcessLogQuery, ProcessLogQueryResult, ProcessLogEntryWithId, ProcessEvent, ToolCall, ToolResult, AgentConfig, InferenceRequest, Module, ContextMaintenanceSnapshot, AgentRuntimeSettingsPatch, AgentRuntimeSettingsSnapshot } from './types/index.js';
+import type { FrameworkConfig, TraceEventListener, InferenceLogQuery, InferenceLogQueryResult, InferenceLogEntryWithId, ProcessLogQuery, ProcessLogQueryResult, ProcessLogEntryWithId, ProcessEvent, ToolCall, ToolResult, AgentConfig, InferenceRequest, Module, ContextMaintenanceSnapshot, AgentRuntimeSettingsPatch, AgentRuntimeSettingsSnapshot, SameRoundThinkTextPolicy } from './types/index.js';
 import { Agent } from './agent.js';
 import { type ToolClass, type ToolClassSource } from './mcpl/tool-classes.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
 import type { SessionUsageSnapshot } from './usage/types.js';
-import { type OperatorLogEntry, type OperatorLogInput, type OperatorRequester } from './operator-log.js';
+import { type SurgeryMarkerReceipt, type OperatorLogEntry, type OperatorLogInput, type OperatorRequester } from './operator-log.js';
 /**
  * Feasibility verdict for a runtime-settings patch, derived through the SAME
  * settings→config mapping the live apply path uses (`Agent.planRuntimeSettings`
@@ -103,9 +104,64 @@ export declare class ResumeBlockedError extends Error {
         preview: RuntimeSettingsPreview;
     }>);
 }
+interface InferenceToolSnapshot {
+    sameRoundThinkTextPolicy: SameRoundThinkTextPolicy;
+}
+/**
+ * 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
+ * a `context_length` at 413. The status is a heuristic for when a shed may
+ * help, not proof that the history is at fault.
+ *
+ * 400 and 422 are how a provider answers a request that fails its
+ * validation, as a history it can't accept does, but other refusals come
+ * back the same way, such as Anthropic's 400 for a credit balance that's too
+ * low. A 413 is the request's size. When the newest exchange made it too
+ * large, as an oversized attachment does, shedding that exchange may bring
+ * the request back under the limit, and nothing else in the framework
+ * recovers a 413; when the history as a whole is too large, the shed doesn't
+ * help, and the breaker stops at its rewind cap. The 413 arm takes both
+ * labels a 413 arrives under, invalid_request and context_length, because
+ * membrane's label for a 413 differs by version and adapter. Other statuses
+ * keep the history, since shed history can't be got back and the status
+ * gives no sign that a shed would help: a 404 is a model or an endpoint that
+ * doesn't exist, and 405, 409, 410 and 415 are about the HTTP request or the
+ * resource, as a rule, rather than the conversation.
+ *
+ * The table test in test/inference-exhaustion-rewind.test.ts is this
+ * predicate's contract. The notes below on which membrane version gives which
+ * label are its history, and will go stale as hosts move to newer releases.
+ *
+ * Which failures reach the gate with which label depends on the membrane:
+ * - As membrane 0.5.86 classifies them: Anthropic files a 400 as
+ *   invalid_request (after its context check) and its other 4xx as unknown.
+ *   The chat adapters never file one as invalid_request, since they classify
+ *   by the error's message text, and a context_length they file that way
+ *   carries status 400 whatever the response's was. The raw-fetch Responses
+ *   adapter files every status it doesn't list (404, 405, 409, 410, 413,
+ *   415, 422 …) as invalid_request, so it alone produces an invalid_request
+ *   at 413 or 422, and no 0.5.86 adapter produces a context_length at 413.
+ * - From membrane #56 (merged, not yet in a release), one table serves every
+ *   adapter. Auth codes and context overflow are checked on a 400 or 422
+ *   first, a 404 is invalid_request, a 413 is context_length, and other 4xx
+ *   are invalid_request. So a 413 still sheds, an Anthropic one included,
+ *   while a context_length at 400 or 422, a token overflow, keeps the
+ *   history. The 422 arm then also covers an OpenAI-compatible server, such
+ *   as a FastAPI one, that answers a validation failure with 422.
+ *
+ * An error with no status, from a membrane that reports none, keeps the rule
+ * the breaker had before: the type alone.
+ */
+export declare function shedMayHelp(errorType: string | undefined, httpStatus: number | undefined): boolean;
 export declare class AgentFramework {
+    private toolPresentations;
+    private presentationPreviews;
+    getRequestToolPresentation(request: object): PresentationSnapshot | null;
     private store;
     private ownsStore;
+    private stopPromise;
+    private stopCompleted;
+    private ownedStoreClosed;
     private membrane;
     private queue;
     private agents;
@@ -152,7 +208,13 @@ export declare class AgentFramework {
     private providerAccelerationDefaultCooldownMs;
     private providerAccelerationJitterMs;
     private providerHoldHook;
+    /** Provider waits (stated retry-after) per (agent, model), kept across restarts. */
+    private providerWaits;
+    /** Wakers for error-policy retry waits in progress: stop() ends them. */
+    private retryWaitWakers;
     private providerAdmissionClosed;
+    /** Invalidates framework turns still assembling when stop begins. */
+    private lifecycleGeneration;
     /** Last time we reported stale (busy-requeued) inference requests, per agent. */
     private staleWarnAt;
     /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
@@ -186,26 +248,6 @@ export declare class AgentFramework {
      *  keeps unrelated channels from moving the pin. Cleared at every fresh
      *  turn's start; budget restarts keep it. */
     private turnEngagedChannels;
-    /** Channels this turn's PLAIN PROSE was actually delivered to, in delivery
-     *  order (deduped at render). Feeds the `[delivered]` receipt appended at
-     *  logical turn end: explicit sends receipt themselves via their
-     *  tool_result, but auto-routed prose previously vanished into the router
-     *  with no in-window record — the agent could never see where its own
-     *  words landed (2026-07-31 misroute series; antra: minimal receipts).
-     *  Cleared at every fresh turn's start; budget restarts keep it (same
-     *  logical turn, receipt covers the whole turn). */
-    private turnProseDeliveries;
-    /** Count of plain-prose segments SUPPRESSED this turn by sticky
-     *  explicit-send silencing. The suppression rule itself is untouched
-     *  (antra, 2026-07-31: visibility is enough) — but it must never be a
-     *  silent black hole: Mythos multiplexed two threads in one round (prose
-     *  for the lane + explicit send for another channel, textbook per the
-     *  routing doc), the silencing ate the prose reply, and his own record
-     *  ("scene delivered to #mythos via plain speech — routing confirmed")
-     *  believed it delivered. The receipt now reports suppression, so the
-     *  author sees the segment's fate one turn later. Cleared each fresh
-     *  turn; budget restarts keep it. */
-    private turnProseSuppressed;
     /** A tool boundary injected fresh CONVERSATIONAL input (a real message —
      *  not a reaction or a system marker) into the live stream. Tells
      *  driveStream to clear sticky explicit-send suppression before handling
@@ -218,14 +260,43 @@ export declare class AgentFramework {
     private lastAnnouncedLocus;
     /** Latest bounced (undelivered) prose per agent — the `{{unsent}}` source. */
     private proseClipboards;
-    /** Sticky per-TURN delivery target set by the turn's first `>>` prefix.
-     *  Cleared at every non-restart turn start; survives context restarts. */
-    private proseTargetPins;
-    /** Hybrid router is fail-closed after a malformed/unresolved envelope until a new valid target. */
-    private proseHybridSuppressed;
-    /** Agents whose current turn requested `!` continuation — re-woken when the
-     *  turn completes instead of pausing until the next external event. */
-    private proseContinuations;
+    /**
+     * Each agent's routing state for its current turn (TurnRouting): the
+     * sticky destination, the turn's destination for a resumed stream,
+     * hybrid's hold, a `!` continuation and receipt tallies. A fresh turn starts a new object
+     * instead of clearing the old one, and a stream that resumes the turn
+     * (resumesLogicalTurn) keeps it. A queued delivery holds the object of the
+     * turn that queued it, so prose a turn leaves queued when it ends (a
+     * skip_reply ends it before its posts have run) still follows that turn's
+     * destination, and its late writes can't reach the next turn.
+     */
+    private turnRouting;
+    /**
+     * 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
+     * posts go out in the order they were written, across streams and turns.
+     */
+    private proseSpeechChains;
+    /**
+     * Each agent's open logical turn (LogicalTurn). It stays open from the
+     * fresh start that opens it until the turn settles (settleAgent: it
+     * completes, a tool ends it, or it fails or is abandoned), and every fresh
+     * start that routes prose while it is open continues it: a framework
+     * retry, the start that consumes tool results the non-streaming fallback
+     * left (whichever wake the scheduler starts it with), the later compile a
+     * provider-capacity hold defers a turn to. A silent start neither
+     * continues nor opens one. A stream that ends without settling needs to do
+     * nothing to carry its turn. Settling only detaches the turn from future
+     * starts: the settling stream keeps its own object, which its remaining
+     * deliveries, its receipt and its ` !` check go on using (a completion
+     * settles before it awaits its chain and writes its receipt). So every
+     * logical end must close inheritance once, before the next fresh start:
+     * a turn left open would hand its object, late writes and all, to an
+     * unrelated turn. A tool-ended turn settles before the next turn can
+     * start. Only the stream that holds the open turn closes it; disposal
+     * drops it, and stop() clears every agent's.
+     */
+    private openLogical;
     /** Consecutive bounce-wakes per agent; capped so an agent that keeps
      *  emitting unprefixed prose can't wake-loop (notices still append). */
     private proseBounceStreaks;
@@ -405,10 +476,16 @@ export declare class AgentFramework {
     private codeExecutionConfig;
     private codeExecutionRunners;
     private scriptToolWaiters;
-    /** Agents whose running script hit an endTurn-carrying inner result —
-     *  deferred and applied to the final code_execution result instead of
-     *  cancelling the stream mid-script (which would wedge the turn). */
+    /** Per agent, the foreground script now running. An endTurn-carrying inner
+     *  result marks the script that made the call, and is applied to that
+     *  script's code_execution result instead of cancelling the stream
+     *  mid-script (which would wedge the turn). A stopped script's late result
+     *  marks only that script, never the agent's next one. */
     private scriptDeferredEndTurn;
+    /** RFC-007: per agent, the origin of the foreground script its runner is
+     *  executing, handed to that script's inner calls (scripts run one at a
+     *  time per runner). Background runners capture theirs in the closure. */
+    private foregroundScriptOrigins;
     /** Background (daemon) scripts: model-authored watchers that outlive their
      *  spawning turn. Each gets a DEDICATED PyRunner; wake_agent() injects a
      *  provenance envelope + payload and requests inference. Keyed by script id. */
@@ -439,6 +516,16 @@ export declare class AgentFramework {
     /** Namespaced tool name → the server whose tools/list produced it. Prefixes
      *  can nest (`foo`, `foo--bar`), so a prefix match alone can name two. */
     private mcplToolServers;
+    /** Servers whose tools/list answered in the latest refresh. */
+    private mcplListedServers;
+    /** Zero-match tool-pattern diagnostics (checkToolPatterns): set at the end
+     *  of create(), when the tool universe is first complete. */
+    private toolPatternChecksArmed;
+    /** Patterns already reported as matching nothing — each is reported once. */
+    private toolPatternsReported;
+    /** Every (prefix → serverId) ever configured. A removed or restarting
+     *  server's patterns stay undecided rather than reported mid-restart. */
+    private toolPatternKnownPrefixes;
     /** Maps serverId → McplServerConfig for prefix lookup. */
     private mcplServerConfigs;
     /** Host capabilities advertised during the MCP handshake — stored so servers
@@ -483,9 +570,15 @@ export declare class AgentFramework {
      */
     start(): void;
     /**
-     * Stop the event loop.
+     * Stop the event loop. Failed module/MCPL cleanup can be retried with its
+     * original context; storage stays open until that cleanup succeeds.
+     * @param teardownTimeoutMs Optional module/MCPL wait budget. Omit to wait
+     * until cleanup settles, as required by existing module/child contracts. This
+     * does not bound earlier stream or event-loop quiescence, or cancel cleanup.
      */
-    stop(): Promise<void>;
+    stop(teardownTimeoutMs?: number | undefined): Promise<void>;
+    private resetCompletedStop;
+    private stopOwned;
     /**
      * Advance queued ContextManager work without requiring a new message.
      *
@@ -496,12 +589,34 @@ export declare class AgentFramework {
      */
     private providerGate;
     private providerGateBlocked;
+    /** Acceleration and host holds park the whole agent; a provider wait holds
+     *  only its own model, which auxiliary admission checks per call. */
+    private cooldownBlocksAuxiliary;
     private acquirePrimaryProviderGate;
     private releasePrimaryProviderGate;
     private flushAuxiliaryAdmission;
     private waitForAuxiliaryIdle;
     private withAuxiliaryAdmission;
     private auxiliaryMembraneFor;
+    /**
+     * A conversation agent's auxiliary calls (its context manager's
+     * compression). A conversation agent takes no provider gate: admission
+     * belongs to the persistent resident, and a generation-unique fork must not
+     * leave a gate behind. But its stated waits are recorded for (agent, model)
+     * 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.)
+     */
+    private conversationAuxiliaryMembraneFor;
+    /** The framework's membrane, with each complete() call passed through
+     *  `admit` along with the model it names. */
+    private membraneAdmitting;
+    /** An acceleration hold's length: AF's own pacing (`ownMs`: its default
+     *  plus jitter, capped), or the provider's stated wait in its place
+     *  (`stated`). The stated wait is a lower bound: jitter only adds to it,
+     *  and the cap applies only to AF's own default. A negative stated wait is
+     *  a stated 0, as in ProviderWaits: the 1 s floor, plus jitter. */
     private accelerationCooldownMs;
     private sameInferenceRequest;
     private consultProviderHold;
@@ -509,16 +624,135 @@ export declare class AgentFramework {
      *  inference on it. True = extended in place (held requests stay held). */
     private extendHostProviderHold;
     private holdProviderAcceleration;
+    /**
+     * A provider's stated wait on a turn that doesn't own provider admission:
+     * a conversation agent's or an ephemeral run's. Left to the error policy,
+     * which returns a stated wait as it is, a 429 stating two hours would hold
+     * the turn asleep two hours, up to three times, with nothing recorded and
+     * nothing raised (membrane #56 review, M3). So:
+     * - A conversation agent's turns come through the scheduler as a resident's
+     *   do, so it treats the wait as a resident does: recorded for (agent,
+     *   model), alerted past PROVIDER_WAIT_ALERT_MS, and the turn held until the
+     *   wait passes or an operator releases it ('held'). A non-retryable failure
+     *   records the wait for the calls after it and keeps its own disposition.
+     * - 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
+     *   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.
+     */
+    private nonOwningProviderWait;
+    /** Why an ephemeral run ended instead of sleeping a provider's stated wait,
+     *  for its caller. */
+    private statedWaitNotSlept;
+    /** When a hold's timer next fires: at its deadline, stepped past what one
+     *  timer can hold. A hold with no deadline (a wait held until released, or
+     *  the stand-in for unreadable records) asks again as often as unreadable
+     *  records are read again: records that read again end it, and nothing
+     *  announces that. */
+    private providerHoldTimerMs;
     private releaseProviderAccelerationCooldown;
+    /**
+     * Wait an error policy's retry delay, all of it: the delay can be a
+     * provider's retry-after, and a single timer past 2^31-1 ms fires almost at
+     * once. Steps through longer waits; stop() wakes it so a shutting-down
+     * framework is never left with a wait parked for days.
+     */
+    private waitForRetry;
+    /**
+     * Record a provider's stated wait (a classified error carrying
+     * `retryAfterMs`) for (agent, model). Returns the wait that binds now,
+     * which is the longer of this one and any outstanding one. A wait that
+     * newly binds past PROVIDER_WAIT_ALERT_MS, or until released, raises an
+     * ops alert.
+     */
+    private recordProviderWait;
+    /**
+     * Hold this agent's primary turns for a provider wait on its model. The
+     * requests are kept and released together, into one fresh compile, when
+     * the wait ends: the same path an acceleration cooldown takes, without
+     * parking auxiliary calls to other models.
+     */
+    private holdForProviderWait;
+    /**
+     * Refuse an auxiliary call to a model the provider asked this agent to wait
+     * on, without calling it. The refusal is a retryable rate limit carrying
+     * the remaining wait, so a caller that paces (context-manager's compression
+     * lane, from its corrective round #138 on) waits it out instead of spending
+     * a call. It is marked
+     * `providerAdmission: 'deferred'`: no call was made, so a caller can keep
+     * the wait without counting a failed call (room-225 #47927).
+     */
+    private refuseHeldProviderModel;
+    /**
+     * Release provider waits: one model's for an agent, or every model's. The
+     * explicit operator override for a wait that should not be honoured (the
+     * passing of time needs no call). Recorded, so a restart does not bring the
+     * wait back; held primary turns are released into one fresh compile. An
+     * acceleration hold the released wait lengthened keeps only AF's own pacing
+     * for its failure; a host hold stays the host's.
+     */
+    releaseProviderWait(agentName: string, model?: string, by?: string): Array<{
+        model: string;
+        until: string | null;
+        release: 'recorded' | 'pending' | 'in-process override';
+    }>;
+    /** Provider waits binding now, for health and doctor tooling. */
+    providerWaitSnapshot(agentName?: string): Array<{
+        agent: string;
+        model: string;
+        until: string | null;
+        reason: string;
+        setAt: string;
+    }>;
     private recordProviderAccelerationRecovery;
     private cancelProviderAdmission;
     private startQueuedMaintenance;
     private runQueuedMaintenance;
     private contextProgress;
+    /**
+     * A server's request or notification the host couldn't handle, answered
+     * with a JSON-RPC error when it is a request (a notification has no one to
+     * answer, and is logged), rather than thrown out of the connection's
+     * listener, where it was an unhandled rejection and the server's request
+     * waited for its timeout.
+     * - `refused`: the listener turned it away before its handler ran; the
+     *   host is stopping, and none of it was taken. Answered -32000, "the host
+     *   is stopping", the code the push coalescer already gives a stopping
+     *   host: the server can send it again to the host's next run.
+     * - `failed`: the handler threw, whatever it threw, `undefined` included.
+     *   While the host stops (its queue closed), that's answered -32000 too,
+     *   with the handler's own message after the stop wording; on a live host
+     *   it's a fault, answered -32603 with the handler's message. The handler
+     *   may have admitted part of the request first (an earlier message of a
+     *   batch), so nothing here claims that none of it was taken.
+     * A request the handler already answered before it threw isn't answered
+     * again: the failure is logged.
+     */
+    private refuseServerItem;
     /**
      * Push a process event to the queue.
+     *
+     * After stop() the queue is closed and this throws, so a direct caller
+     * learns the framework is stopped — except for a tool's result. A call
+     * still running at stop() completes later, into a callback with nothing
+     * to catch the throw (an unhandled rejection), and nothing could take its
+     * result anyway: the queue that would carry it to its stream is closed,
+     * stop() is ending the streams, and the tool has already run. That
+     * result is dropped, and the drop is logged.
      */
     pushEvent(event: ProcessEvent): void;
+    /**
+     * A module's event. stop() closes the queue before it stops modules, so a
+     * module's event can arrive after that: from a listener that fires while
+     * stop() runs, or from the module's own stop(). Nothing will process it,
+     * and a throw there can go unhandled or fail stop(), so it's dropped with a
+     * log line naming the module. Otherwise it's queued as pushEvent() queues
+     * it, or, through the deprecated queue handle, without the trace.
+     */
+    private pushModuleEvent;
     /**
      * Add a trace event listener for observability.
      */
@@ -531,9 +765,11 @@ export declare class AgentFramework {
      */
     get channels(): ChannelRegistry | null;
     /**
-     * Remove a trace event listener.
+     * Remove a trace event listener: its first subscription, if it holds more
+     * than one.
      */
     offTrace(listener: TraceEventListener): void;
+    private removeTraceRegistration;
     /**
      * Add a module at runtime.
      */
@@ -592,11 +828,51 @@ export declare class AgentFramework {
     private spillSettingsExtension;
     private captureInferenceToolSnapshot;
     private toolResultGuardSettingsExtension;
-    private restoreToolResultGuardSetting;
+    /** Every guard's annotation still running, for stop() (agent-framework #277). */
+    private readonly guardAnnotations;
+    /** Each guard that isn't idle, by agent name, as the guard reports it. An
+     *  ephemeral run or a closed fork leaves the agent map with an annotation
+     *  maybe still running, or a stub edit, acceptance edit or audit write
+     *  queued, which maintenance and stop then retry (agent-framework #277). A
+     *  guard is here from the moment it has work left until the moment it has
+     *  none, however that comes about. */
+    private readonly busyGuards;
+    /** Withheld originals' writes still under way past their deadline: while
+     *  any is, the workspace isn't answering and no other withheld original's
+     *  write is started. Several can be, when writes of different agents'
+     *  batches stalled together. */
+    private readonly stalledSpills;
+    /** Withheld spills skipped since the current stall began. */
+    private stallSkips;
+    /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
+    private withheldSpillDeadlineMs;
+    /** The lifecycle generation whose stop() has let the running annotations
+     *  finish: a withheld original is then no longer written to a workspace
+     *  that is stopping, and its stub names the audit record. A start() after
+     *  that stop() has finished has a generation of its own, so the spill gate
+     *  is open again for an instance kept with a store it doesn't own and that
+     *  is still open (start() doesn't restore stopped modules or MCPL
+     *  connections, and refuses an owned store that stop() closed). A start()
+     *  made while a stop() is still draining isn't a supported order. */
+    private guardSpillsClosedFor;
+    /** A new agent's guard: its persisted setting, the tool-results spill its
+     *  withheld originals are written to, and the set stop() waits on
+     *  (agent-framework #277). */
+    private adoptToolResultGuard;
+    /** Each guard that may have queued storage work, once, by agent name: the
+     *  live agents' and every other that isn't idle. */
+    private guardsWithStorageWork;
     private buildThinkTool;
     /** agent_settings tool definition with module extension fields merged in. */
     private buildAgentSettingsTool;
     private getToolsForAgent;
+    /** Available is independent of presentation visibility; execution callers keep this surface. */
+    private availableToolsForPresentation;
+    inspectToolPresentation(agentName: string, snapshot?: InferenceToolSnapshot): PresentationSnapshot | null;
+    private advertisedToolsForAgent;
+    /** Compression can revisit calls to hidden tools; never apply visibility here. */
+    private compressionToolsForAgent;
+    private editToolPresentation;
     /**
      * The tools one agent is shown at inference: its surface (the subconscious
      * has its own), less what its permissions deny, plus — for explicit-mode
@@ -903,9 +1179,11 @@ export declare class AgentFramework {
      * events after an ephemeral/conversation agent has been disposed. */
     private recordLogicalTurnToolCalls;
     private recordEphemeralToolCalls;
-    /** Settle an active ephemeral run (no-op for resident agents). The tool-call
-     *  count comes from the run's own counter — the single source of truth,
-     *  which unlike a per-stream local survives budget restarts. */
+    /** A logical turn's end, for every agent: it closes the agent's open
+     *  logical turn when it is the settling stream's own (openLogical), and
+     *  settles an active ephemeral run. The run's tool-call count comes from
+     *  its own counter — the single source of truth, which unlike a
+     *  per-stream local survives budget restarts. */
     private settleAgent;
     /**
      * Run an ephemeral agent to completion through the framework's event loop.
@@ -1056,6 +1334,10 @@ export declare class AgentFramework {
      *
      *   host-status — report the quiesce state (drained / parked wakes /
      *   running background scripts).
+     *
+     *   release-provider-wait — end an agent's provider wait (a provider's
+     *   stated retry-after, kept across restarts) for one `model` or all, as an
+     *   explicit, recorded operator override.
      */
     private handleHostCommand;
     /**
@@ -1158,6 +1440,12 @@ export declare class AgentFramework {
      * Discord messages that left the live context get awareness markers via the
      * durable outbox, exactly as message-granular `undo` does.
      *
+     * Returns once the switch has landed: the body is applied, with a
+     * marker-scheduling receipt (`markers`). It does not wait for Discord to
+     * accept the reactions: delivery is started, behind the MCPL data-plane
+     * gate, and continues without the caller or the store reservation waiting
+     * on it; its per-message outcomes stay in the outbox ledger.
+     *
      * Throws `OperatorActionError` (`agent-busy`, `unknown-message`, …) — the
      * agent must be idle; nothing is queued.
      */
@@ -1181,6 +1469,8 @@ export declare class AgentFramework {
             channelId: string;
             messageId: string;
         }>;
+        /** Whether awareness marks were scheduled; never a delivery claim. */
+        markers: SurgeryMarkerReceipt;
         lastVisible: {
             participant?: string;
             role?: string;
@@ -1194,6 +1484,9 @@ export declare class AgentFramework {
      * removed together. Discord originals get awareness markers via the outbox;
      * the batch is `explicit`-activated only after every removal succeeded, and
      * a crash mid-way is finished at next boot (resumePreparedDiscordSuppressions).
+     * Like rollbackToMessage, it returns once the body change has landed, with
+     * a marker-scheduling receipt (`markers`); delivery continues without the
+     * caller waiting on it.
      *
      * Not retroactive over derived state: a message already folded into an
      * autobiographical summary stays in that summary — roll back to before it
@@ -1216,12 +1509,64 @@ export declare class AgentFramework {
             channelId: string;
             messageId: string;
         }>;
+        /** Whether awareness marks were scheduled; never a delivery claim. */
+        markers: SurgeryMarkerReceipt;
         lastVisible: {
             participant?: string;
             role?: string;
             preview?: string;
         } | null;
     }>;
+    /**
+     * Record a surgery's prepared marker batch as active once its body change
+     * has landed, and say what happened. Never throws: the body is already
+     * applied, so a ledger failure here is reported in the receipt rather than
+     * as a failed surgery an operator might retry. A batch that could not be
+     * activated is retired, so no later reconciliation can deliver it behind a
+     * receipt saying it was not scheduled (`not-scheduled`). If retiring fails
+     * too, the receipt says only that the outcome is `unresolved`: the batch is
+     * retained, and it may still be delivered. A rollback's batch
+     * (activated by target branch) may be promoted by the very next
+     * reconciliation, the one the delivery it starts runs; a suppression's
+     * (activated explicitly) waits for the next start.
+     *
+     * A batch with no refs (a suppression journal with nothing addressable) is
+     * still activated, which closes its resume journal. It schedules no marks,
+     * so it reports `none` whatever the ledger does. If it can be neither
+     * activated nor retired, its journal is left prepared and closes at the
+     * next start: every interval it names has already committed, so the resume
+     * skips them all and activates it.
+     */
+    private activateSurgeryMarkers;
+    /**
+     * Start awareness delivery after a branch move (a surgery, a switch, an
+     * undo or redo) without the caller awaiting it. No operator response waits
+     * for Discord to accept marks: the MCPL data-plane gate alone holds channel
+     * traffic that arrives after it until they are attempted.
+     * `syncDiscordAwarenessMarkers` installs that gate synchronously, before
+     * its first await, so calling this while a surgery still holds the store
+     * puts the gate up before the store is released. With no drain running, the
+     * drain starts in the same synchronous run (the first reaction request can
+     * be written before this returns); with one running, this generation's pass
+     * follows it (drainForGeneration). Either way delivery continues
+     * independently: the caller's response and any store reservation stop
+     * waiting on remote reactions. A turn may run during delivery when its wake
+     * carries no channel traffic (a scheduler timer, a provider admission), and
+     * also when its channel traffic was admitted before the gate went up
+     * (queued when a surgery began, or arriving during its switch or fork): the
+     * surgery's store reservation, which used to hold such a turn through the
+     * drain, now ends once the gate is up. A failure is accounted by the gate
+     * itself: the current generation's failure recycles the connections, and a
+     * superseded one leaves that to the newer generation, whose own pass meets
+     * the same ledger. Here it is logged and raised as an ops alert, and the
+     * next sync, reconnect or start delivers what is still pending.
+     *
+     * @param after What moved the branch, for the log and the alert
+     *   ("rollback", "branch switch", "undo" …).
+     * @param agentName The agent the move was for, or "framework" for a
+     *   branch switch that names none.
+     */
+    startDiscordAwarenessDelivery(after: string, agentName?: string): void;
     /** Re-materialize config files from the (new) active branch — fire and
      *  forget; the gate picks changes up via mtime. Mirrors undoLastTurn. */
     private materializeConfigMountAfterBranchSwitch;
@@ -1413,6 +1758,13 @@ export declare class AgentFramework {
      * Convert an MCPL push event to a context message.
      */
     private handleMcplPushEvent;
+    /**
+     * Whether a batched gate wake's addressed route may become `agentName`'s
+     * speech locus. The gate broadcasts to every agent, conversation forks
+     * included. A fork speaks only in its home channel, and a channel bound to
+     * a fork is that fork's conversation, so no other agent takes it.
+     */
+    private mayTakeGateRoute;
     /**
      * Derive the MCPL composite channel id (the outbound routing locus) for a
      * push event from its server-defined `origin`, if it carries one.
@@ -1431,7 +1783,17 @@ export declare class AgentFramework {
      */
     private derivePushEventChannel;
     private processInferenceRequests;
-    /** Record prose segments suppressed by explicit-send silencing. */
+    /**
+     * Metadata for rows the agent's current turn stores: a silent heartbeat
+     * tick stamps each of them (assistant responses, tool_result rows) so they
+     * stay identifiable after the turn — request builds key the tick separator
+     * on it, and a later retention policy can find or collapse them. The stamp
+     * names the agent: residents share one message slot and a broadcast tick
+     * reaches each of them with the same eventId. Undefined for ordinary
+     * turns, whose rows are stored exactly as before.
+     */
+    private silentTurnRowMetadata;
+    /** Record plain-prose segments this turn suppressed. */
     private recordProseSuppression;
     /** Record a successful plain-prose delivery for this turn's receipt. */
     private recordProseDelivery;
@@ -1469,6 +1831,18 @@ export declare class AgentFramework {
      * never conversational, never locus-eligible.
      */
     private recordChannelAutoOpenNotice;
+    /**
+     * A `!` continuation the turn asked for (`>>#x !`, `>>>#x !`): start another
+     * turn now instead of pausing until the next external event. It reads the
+     * logical turn of the stream that asked (shared with a retry or a
+     * re-inference that continues it), once its deliveries have run, when the
+     * turn completes or a tool ends it. A stream that ends in an error asks for
+     * none itself, but a framework retry that follows it carries the request;
+     * a turn abandoned by a quiesce asks for none.
+     */
+    private requestProseContinuation;
+    /** The agent's routing state for its current turn, made when it has none. */
+    private routingOf;
     /**
      * Explicit-prose-routing delivery gateway (docs/explicit-prose-routing.md).
      * Every prose segment of an `explicit`-mode agent flows through here:
@@ -1478,6 +1852,21 @@ export declare class AgentFramework {
      * or via the turn's sticky target).
      */
     private deliverProse;
+    /**
+     * Explicit prose's envelopes, each `>>` target resolved now, once. A live
+     * round is admitted at its boundary: its turn's destination is decided from
+     * these resolutions (roundDestination), and its queued delivery posts to
+     * them, however the registry's names change before it runs.
+     */
+    private admitProse;
+    private deliverAdmittedProse;
+    /**
+     * Where a delivered round leaves its turn's sticky destination, as the
+     * explicit gateway sets it once the round's envelopes run: each `>>`
+     * envelope whose target resolved becomes the destination. One that didn't
+     * resolve bounces and leaves it, as do `>>skip_reply` and unprefixed text.
+     */
+    private roundDestination;
     /** Locus-preserving explicit publication. Source remains byte-identical in Chronicle. */
     private deliverHybridProse;
     private deliverProseEnvelope;
@@ -1616,6 +2005,30 @@ export declare class AgentFramework {
      * live wire copy can reuse the identical strings.
      */
     private buildStoredToolResultContent;
+    /** Where a tool result labelled `label` is written: `<first writable
+     *  mount>/tool-results/<label>.txt`, or null when there is no writable
+     *  workspace. */
+    private toolResultFilePlace;
+    /**
+     * A withheld original uses the remaining time in its batch's deadline.
+     * A write still under way at that deadline is reported as unfinished and
+     * goes on; the guard stops waiting for it, though stop() still waits for
+     * the workspace's turn it holds (bounded only by a teardown timeout). From
+     * then until every
+     * overdue write settles, new withheld spills are workspace_unanswered.
+     * Writes from other batches can start before the first deadline fires.
+     * An exhausted batch starts no more writes even if none is overdue.
+     * The inline cap's spills use writeToolResultFile without this deadline.
+     */
+    private spillWithheld;
+    /**
+     * Write one tool result's text to its tool-results file (see
+     * toolResultFilePlace): the one place both the inline cap's spill and the
+     * guard's withheld originals go. null when there is no writable workspace.
+     * A failed write is reported, traced and logged here, never thrown. With a
+     * branch, the file lands on that branch or isn't written (see writeBinary).
+     */
+    private writeToolResultFile;
     private spillOrTruncate;
     private getOrCreateScriptRunner;
     /**
@@ -1633,6 +2046,10 @@ export declare class AgentFramework {
      * resolve with its result. The waiter intercept in handleProcessEvent
      * (keyed by the pytc- call ID) routes the tool-result event here instead
      * of into the agent's pending tool round.
+     *
+     * RFC-007: with an `origin`, observers see the call as they see a model
+     * call (register, dispatch with its refusal sites, open; the terminal at
+     * the waiter intercept), under the inner tool's own name and class.
      */
     private dispatchScriptToolCall;
     /** Abort a running script when the agent's turn dies underneath it. */
@@ -1734,15 +2151,18 @@ export declare class AgentFramework {
      *      inference, so this never causes a retry/wake loop.
      *   3. escalation — after N consecutive failures the agent is hard-down;
      *      log that loudly (a repeated identical failure is the textbook signal).
-     *   4. breaker — when the failures are an `invalid_request` (a 400-class
-     *      rejection of the history itself, e.g. corrupted tool_use/tool_result
-     *      pairing or an oversized attachment), retrying the same context can
-     *      never succeed: every new push event wakes the agent onto the same
-     *      poisoned history forever. At the hard-down threshold, automatically
-     *      quarantine: shed the newest complete exchange (the same forced-rewind
-     *      primitive `/unstick` uses — shedNewestTurn never orphans a
-     *      tool_use/thinking block) and retry, bounded by the same rewind cap so
-     *      the breaker can never eat the whole history.
+     *   4. breaker — when a failure at or past the hard-down threshold suggests
+     *      the provider refused the request's content or size (shedMayHelp:
+     *      an `invalid_request` at HTTP 400, 413 or 422 or with no status, or a
+     *      `context_length` at 413, such as a provider's answer to a corrupted
+     *      tool_use/tool_result pairing or an oversized attachment), retrying
+     *      the same context is likely to fail the same way, and every new push
+     *      event would wake the agent onto that same history. At the hard-down
+     *      threshold, automatically quarantine: shed the newest complete
+     *      exchange (the same forced-rewind primitive `/unstick` uses —
+     *      shedNewestTurn never orphans a tool_use/thinking block) and retry,
+     *      bounded by the same rewind cap so the breaker can never eat the
+     *      whole history.
      */
     /**
      * Live health snapshot for /healthz and doctor tooling: gate state, queued
@@ -1784,9 +2204,12 @@ export declare class AgentFramework {
     private noteRefusal;
     /**
      * Classify a terminal inference error for the `inference:exhausted` trace.
-     * Single-sourced for every emit site: the downstream breakers (poison-history
-     * quarantine, OverBudget drain kick) gate on `errorType`, so classification
-     * drift between sites would silently disable a safety net.
+     * Single-sourced for every emit site that has an error to classify (a
+     * stream the framework aborted has none): the downstream breakers gate on
+     * what it returns (the poison-history quarantine on `errorType` and
+     * `httpStatus`, through shedMayHelp; the OverBudget drain kick on
+     * `errorType`), so classification drift between sites would silently
+     * change when a safety net acts.
      *
      * context-manager's refusal errors are matched by a real `instanceof` since
      * CM exports them from its package root (context-manager#41 / #71; floor
@@ -1813,7 +2236,7 @@ export declare class AgentFramework {
      * primitives as the refusal auto-rewind / `/unstick` (shedNewestTurn +
      * the single consolidated episode marker) — and queues a retry so the
      * rewound history is verified immediately instead of waiting for the next
-     * push event to wake the agent onto the same poisoned context.
+     * push event to wake the agent onto the same context.
      *
      * Bounded: at most `refusalHandling.maxRewinds` (default 3, hard cap 10)
      * sheds per failure episode; the budget resets on any successful inference.
@@ -1826,7 +2249,11 @@ export declare class AgentFramework {
      * Fail-open: individual server connection failures don't prevent framework startup.
      */
     private initializeMcpl;
-    /** Reconcile the durable ledger with Chronicle, then deliver every server's work. */
+    /**
+     * Reconcile the durable ledger with Chronicle, then deliver every server's
+     * work. A drain still running is waited for and then followed by a fresh
+     * pass (drainForGeneration).
+     */
     syncDiscordAwarenessMarkers(_onlyServerId?: string): Promise<void>;
     private resumePreparedDiscordSuppressions;
     /**
@@ -1839,12 +2266,32 @@ export declare class AgentFramework {
     private writeDiscordAwarenessSuccess;
     private writeDiscordAwarenessFailure;
     private beginDiscordAwarenessBarrier;
+    /**
+     * One server's drain for a new generation: a gate completes only after
+     * every operation pending when it was armed has been attempted. A drain
+     * already running can't promise that. It never re-sends a key it has
+     * attempted, so an operation re-pended while it runs (a rollback, its undo,
+     * then a redo, all mid-drain) stays pending, and it may already have made
+     * its last read of the ledger, missing a batch activated since. So a
+     * generation that finds a drain running waits for it, then drains again
+     * with a fresh pass that reads the ledger anew. Two generations waiting on
+     * the same drain share the fresh pass that follows it.
+     */
+    private drainForGeneration;
+    /**
+     * Wait out the awareness gate for an inbound event: the generation current
+     * now, and any generation installed while waiting, until none is current
+     * or the current one is one already waited for. A handler that waited only
+     * for the generation it first saw would go on behind a newer one armed
+     * meanwhile. Rejects as the generation it waited for rejects.
+     */
+    private awaitDiscordAwarenessBarriers;
     /**
      * Install one framework-global Discord-awareness generation before releasing
-     * any inference-bearing event. With pending work, every MCPL data plane is
-     * paused while all control planes remain live. With no pending work, ready()
-     * runs synchronously so request responders preserve their historical
-     * same-stack behavior.
+     * any inference-bearing event. With pending work or a drain still running,
+     * every MCPL data plane is paused while all control planes remain live.
+     * With neither, ready() runs synchronously so request responders preserve
+     * their historical same-stack behavior.
      */
     private installMcplDataPlaneGate;
     private releaseMcplDataPlaneGate;
@@ -1864,6 +2311,13 @@ export declare class AgentFramework {
      *  coalescing. */
     private manifestRefreshState;
     private static readonly MANIFEST_FETCH_FLOOR_MS;
+    /**
+     * The `mcpl:policy-refused` fields from a refusal receipt, as the host
+     * acts on them: the receipt is server-supplied, so `fallback` is the
+     * branch actually taken (anything but `close` is treated as `mcp-only`)
+     * and a non-string `reason` is dropped.
+     */
+    private static policyRefusalFields;
     /**
      * §17.5 host processing: fetch the complete manifest, validate exactly as
      * at initialize, diff, apply §6.7 consequences (removals eagerly even
@@ -1887,6 +2341,43 @@ export declare class AgentFramework {
      * disconnect are resumed, not reset.
      */
     private registerMcplServerFeatures;
+    /**
+     * Snapshot the protective Discord reaction default for this deployment, as
+     * suppression tokens: the forms the Discord adapter's suppression matcher
+     * reads, not marker payloads for an add, a remove or a replay. It covers
+     * the reactions the framework places: refusal markers, the adapter's own
+     * default awareness marker, the configured awareness marker, and retained
+     * outbox markers (including offline recovery choices and marks that can
+     * later be removed or replayed). A custom emoji appears as its bare ID,
+     * which suppression matches even after a rename; stored markers and the
+     * actual add/remove payloads stay unchanged. Explicit adapter or operator
+     * suppression settings still take precedence. Throws on an unreadable
+     * ledger rather than reporting a partial baseline.
+     */
+    getPlacedReactionBaseline(): readonly string[];
+    /**
+     * The reaction baseline an operator chose for a stdio server, if any: a
+     * value declared in its env, or one inherited from the host with
+     * `inheritEnv`, the declared one first. A value with no tokens, as
+     * discord-mcpl's parser reads them, counts as unset: the adapter splits on
+     * commas and keeps a token only when its normalizer leaves something of it
+     * (blank, `:`, `::` and a lone U+FE0F leave nothing), so such a value (an
+     * empty systemd `Environment=`, say, or `${A},${B}` or `:${NAME}:` with the
+     * variables empty) would otherwise turn the protective default off without
+     * anyone choosing that.
+     *
+     * Windows names are matched in both sources: Workers expose a case-
+     * sensitive `process.env` copy. Within one source, Node's spawn keeps the
+     * first spelling in sorted order, so each source is resolved that way.
+     *
+     * A value is read as the child will see it. A config loaded from JSON can
+     * carry a non-string there despite the type, and spawn writes every
+     * defined value as its string form, so a number is a declared value, not a
+     * failed connect. A null counts as unset, like a blank: written in JSON it
+     * means no value, and read as spawn's "null" it would replace the
+     * protective default with a list that suppresses nothing.
+     */
+    private declaredReactionBaseline;
     /**
      * Connect a new MCPL server at runtime. Refreshes the tool list and
      * notifies the agent of newly available tools. Throws if the MCPL
@@ -1971,6 +2462,24 @@ export declare class AgentFramework {
      * Tools are namespaced as `{toolPrefix}--{toolName}` per server config.
      */
     private refreshMcplTools;
+    /**
+     * Report operator tool-name patterns that match no model-facing tool:
+     * `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
+     * the bare server id is valid config that silently does nothing.
+     *
+     * Each pattern is reported at most once (console line + a
+     * `mcpl:tool-pattern-unmatched` trace). A pattern that could still name
+     * tools of a server whose listing is not in (not connected yet,
+     * reconnecting, restarting) stays undecided until that listing arrives.
+     * Diagnostic only: never throws into the refresh that called it.
+     */
+    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;
     /**
      * Handle a tools/list_changed notification with collapse logic.
      * At most 2 refresh cycles can be in-flight: one running and one pending.
@@ -2061,4 +2570,5 @@ export declare class AgentFramework {
     private dispatchGateToolCall;
     private buildBeforeInferenceParams;
 }
+export {};
 //# sourceMappingURL=framework.d.ts.map