@animalabs/agent-framework 0.22.3 → 0.23.0

package/dist/src/framework.d.ts

@@ -83,9 +83,15 @@ export interface HostModeStatus {
     /** Context writes (module events, api message.send) withheld because the
      * host is quiesced. Persisted while quiesced and flushed by resume(). */
     deferredWrites: number;
-    /** Agents whose turn `abandon` could NOT cancel: the turn token is held but
-     * no stream exists yet (still in hooks/compile) or ever will (puppet tool
-     * turns). Present only after an abandon that left such turns behind. */
+    /** Agents whose turn `abandon` had not ended when its grace ran out: a
+     * 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. */
     unabandonable?: string[];
 }
 /**
@@ -203,21 +209,25 @@ export declare class AgentFramework {
     private stopPromise;
     private stopCompleted;
     private ownedStoreClosed;
-    /** Whether the latest stop() stopped in time everything it waits on with
-     * its deadline (an operator's operations, modules and MCPL servers),
-     * whatever failed after that. create()'s release reads it to say whether
-     * part of what a failed create() started may still be running. */
+    /** 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
+     * the stop. A step that threw may have left part of its work running, as
+     * a wait that ran out does. create()'s release reads it to say whether part
+     * of what a failed create() started may still be running. */
     private stopFinishedTeardown;
     /** An operator's operations in flight, and the config materializations they
      * start. stop() waits until this set is empty before it tears down, unless
      * its wait budget runs out. */
     private readonly operatorOperations;
     /** What a wait of stop()'s left running when its budget ran out, by its
-     * promise: a stream it cancelled or an event loop still in a call. A later
+     * promise: a stream it cancelled or an event loop still in a call; and a
+     * stream whose cancel threw, which stop() doesn't wait for. A later
      * stop() waits for each again, beside what it finds, whatever has happened
      * since to the entry it was found under (a run's end removes its stream's,
-     * a start() replaces the loop), so a budget never lets the store close
-     * under work still running. Each leaves once it settles. */
+     * a start() replaces the loop), so neither a budget nor a cancel that
+     * threw lets the store close under work still running. Each leaves once it
+     * settles. */
     private readonly leftRunning;
     private membrane;
     private queue;
@@ -285,7 +295,6 @@ export declare class AgentFramework {
     /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
     private lastInferenceAt;
     private processLoggingPersist;
-    private processLoggingBroadcast;
     private activeStreams;
     /** Told once per inbound acceptance (mcpl/inbound-source.ts). An internal
      *  seam, unset here: the receipt work (shelf-354) assigns it inside the
@@ -364,10 +373,14 @@ export declare class AgentFramework {
     private ephemeralRuns;
     /** Ephemeral namespaces/names are single-generation for this framework
      * lifetime. Reusing one while an old stream drains would let name-keyed
-     * liveness/settlement state cross generations. */
+     * liveness/settlement state cross generations. Each name records what
+     * reserved it: an ephemeral run (createEphemeralAgent), which takes no
+     * global fallback even after its release, or a conversation fork. */
     private usedEphemeralAgentNames;
     /** One-shot generation tickets minted by createEphemeralAgent. */
     private ephemeralCandidates;
+    /** Warn only once per Agent instance after utilities are registered. */
+    private emptyUtilityPermissionWarnings;
     /** Physical ephemeral frames deliberately disposed by their run watchdog/caller.
      * The name is single-generation, so these frames still own their terminal
      * typing/outgoing close even after runEphemeralToCompletion deregisters them. */
@@ -394,7 +407,7 @@ export declare class AgentFramework {
     private refusalStreak;
     /** Per-agent count of consecutive refusal-driven rewinds in the current turn
      *  chain (reset when a turn completes without a refusal). Bounds the auto
-     *  rewind loop — see refusalHandling + rewindTriggeringTurn. */
+     *  rewind loop — see refusalHandling + shedNewestTurn. */
     private refusalRewinds;
     /** Per-agent count of poison-history rewinds performed by the hard-down
      *  breaker (noteInferenceExhausted). Reset when a turn completes
@@ -461,7 +474,9 @@ export declare class AgentFramework {
     private unackedDeferredWrites;
     /** Monotonic order stamp for deferred writes: the durable queue is always
      *  written, restored, drained and flushed in `seq` order, whatever the
-     *  pending/un-acked split — a re-deferred entry keeps its place. */
+     *  pending/un-acked split — a re-deferred entry keeps its place. Boot
+     *  recovery numbers the restored queue 1..N in that order, and the stamp
+     *  goes on from N (restorePersistedDeferredWrites). */
     private deferredSeq;
     /**
      * Per target agent: the store's message count when the OLDEST currently
@@ -480,8 +495,38 @@ export declare class AgentFramework {
      * guessing from the newest message in the window.
      */
     private activeTurnTriggers;
+    /**
+     * The `[Continue]` prompt the current round of each turn follows, keyed by
+     * the turn's trigger. Each stream start sets it from what the Agent read in
+     * its request (`StartStreamResult.continuePrompt`), and a tool boundary
+     * that hands the live stream messages after the results clears it, since
+     * the next round follows those messages. `silentTurnRowMetadata` stamps the
+     * round's rows with it.
+     */
+    private readonly turnPrompts;
     /** The trigger of `agentName`'s turn in progress, if a turn is running. */
     getActiveTurnTrigger(agentName: string): InferenceRequest | undefined;
+    /**
+     * The window of the frame that holds an agent's turn with no stream to
+     * carry a stop and one of its checks ahead: a start, from its entry until
+     * it hands its turn to a stream or ends (its checks after the hooks, after
+     * the compile, at a failure and after a wait to retry its compile),
+     * driveStream's wait to retry a failed inference (its check after the
+     * wait), and the tool-result guard's wait for the agent's speech (its
+     * check after the wait, which the window lets the abandon reach once a
+     * caller's cancelStream() has left the agent holding no stream). Each
+     * frame opens a window of its own and closes it only while it
+     * is still the agent's, so a start that ends after a later frame opened
+     * one, such as its retry's stream waiting to retry, leaves that one open.
+     * An operator's abandon marks the window, and the frame's check collects
+     * the mark, which goes with the window. abortInference() and the abandon
+     * count a turn with no stream only here; a stop made anywhere else, as
+     * while an agent is idle, a turn finishes its last delivery or a provider
+     * hold has parked it, has no check to end it, and the next start drops
+     * it. Keyed by the Agent, so a replacement agent under the same name
+     * never shares one.
+     */
+    private checkAhead;
     /** Structured calls executed in the current logical turn. Unlike the
      * per-stream local this survives framework retries and budget restarts. */
     private logicalTurnToolCalls;
@@ -523,6 +568,9 @@ export declare class AgentFramework {
      * ephemeral agents have isolated slots and are their own only readers.
      */
     private readonly sharedSlotAgents;
+    /** The windows of forks and runs deregistered while the host was quiesced,
+     *  by agent name; resume() releases them (releaseWindowNowOrAfterResume). */
+    private readonly releasesAfterResume;
     /** The coalescing commit in flight, if any (see commitCoalescingDurable). */
     private coalescingCommit;
     private inferenceRouter;
@@ -587,11 +635,20 @@ export declare class AgentFramework {
     private mcplToolRefreshPending;
     /** Maps tool prefix → serverId for dispatch routing. */
     private mcplPrefixMap;
-    /** Namespaced tool name → the server whose tools/list produced it. Prefixes
-     *  can nest (`foo`, `foo--bar`), so a prefix match alone can name two. */
+    /** Namespaced tool name → the server whose tools/list produced it, from
+     *  its first listing of the name. resolveMcplTool reads it first. */
     private mcplToolServers;
     /** Servers whose tools/list answered in the latest refresh. */
     private mcplListedServers;
+    /** refreshMcplTools' starts, and the start whose result was published
+     *  last: a refresh that a later-started one has overtaken publishes
+     *  nothing, since that one listed every server after it. */
+    private mcplToolsRefreshStarted;
+    private mcplToolsRefreshPublished;
+    /** How many times each server's connection has closed. A listing that
+     *  began before its server's latest close is of a session that's over,
+     *  and refreshMcplTools publishes none of it. */
+    private mcplServerCloses;
     /** Zero-match tool-pattern diagnostics (checkToolPatterns): set at the end
      *  of create(), when the tool universe is first complete. */
     private toolPatternChecksArmed;
@@ -602,6 +659,27 @@ export declare class AgentFramework {
     private toolPatternKnownPrefixes;
     /** Maps serverId → McplServerConfig for prefix lookup. */
     private mcplServerConfigs;
+    /** Modern-MCP (2026-07-28) servers, by id; read through modernServers().
+     *  They are kept apart from the MCPL registry on purpose: they have no
+     *  grant, planes or server→host traffic, so the MCPL machinery (quiesce's
+     *  plane pauses, awareness gates, policy) never sees them. They take part
+     *  only through the tool paths, and their list changes reach agents
+     *  through ordinary admission. */
+    private modernMcpConnections;
+    /** Connects and disconnects in flight, by server id (holdMcpServerId);
+     *  created on first use, like modernMcpConnections. */
+    private mcpServerOps;
+    /** Each legacy connect in flight's own abort (connectHeldMcplServer):
+     *  stop() and a disconnect of its id end it at once, its launch reaped,
+     *  rather than waiting out its handshake. Created on first use, as the
+     *  restart claims are (legacyConnectAborts()). */
+    private legacyConnectAbortMap;
+    /** The ids and tool prefixes restarts hold, each with the claim of the
+     *  restart holding it, from the restart's checks through its connect
+     *  (restartMcplServer): no other connect or restart takes them while the
+     *  old server is torn down. Created on first use (restartClaims), like
+     *  mcpServerOps. */
+    private mcpRestartClaims;
     /** Host capabilities advertised during the MCP handshake — stored so servers
      *  can be connected at runtime (connectMcplServer) after initialization. */
     private mcplHostCapabilities;
@@ -639,9 +717,10 @@ export declare class AgentFramework {
      * Create and start the framework. A create() that fails releases what it
      * had acquired before its error reaches the caller, so that the caller can
      * try again in the same process: the framework it had begun is stopped, as
-     * stop() stops one, but giving up after 30 s on each of stop()'s two cleanup
-     * waits, for an operator's operations already running and then for its
-     * modules and MCPL servers, and a store it opened is closed. A store the
+     * stop() stops one, but giving up after 30 s on each of stop()'s cleanup
+     * waits, for an operator's operations already running, then for its
+     * modules and MCPL servers, and then for awareness drains a failed startup
+     * barrier left running, and a store it opened is closed. A store the
      * caller passed in is left open.
      */
     static create(config: FrameworkConfig): Promise<AgentFramework>;
@@ -687,23 +766,38 @@ export declare class AgentFramework {
     private static joinDiagnostics;
     private printDiagnostics;
     /**
-     * Start the event loop.
+     * Start the event loop. A start() on a running framework does nothing.
+     * Refused, with an error, from a stop() call until that stop() settles,
+     * since that stop would wait on the lifecycle a start() begins, or tear it
+     * down under it. What a start() after a settled stop() should do is #315's
+     * question.
      */
     start(): void;
     /**
-     * Stop the event loop. After a failed or timed-out wait, storage stays open
-     * and stop() can be called again. A timed-out wait lets teardown go on while
-     * what it waited for may still act on what is being torn down.
+     * Stop the event loop. Until it settles, start() and addModule() are
+     * refused. Each step of the teardown runs whatever an earlier one did: one
+     * that throws, such as a host stream's cancel(), fails the stop() once the
+     * rest has run. When a step or a wait up to and including
+     * the wait on awareness drains fails or times out, storage stays open and
+     * stop() can be called again; one that fails after it, in the storage work
+     * that finishes the stop, fails the stop() without keeping storage open.
+     * A timed-out wait lets teardown go on while what it waited for may still
+     * act on what is being torn down.
      * @param teardownTimeoutMs Optional budget for each of stop()'s waits, in
      * turn: on the streams it cancels, on maintenance in flight (a pass or an
      * over-budget drain kick), on the event loop, on an operator's operations
-     * already running, then on modules and MCPL together. With a budget, a
-     * stop() can take up to five of them, besides the withheld-spill deadline
-     * of a guard's write still under way. Omit to wait until each settles, as
-     * required by existing module/child contracts. A wait whose budget runs out
-     * fails the stop() with a ShutdownTimeoutError naming what it waited for;
-     * with more than one, or beside another failure, stop() fails with an
-     * AggregateError of them all. After it:
+     * already running, on modules and MCPL together, then on Discord awareness
+     * drains, which send nothing once stop() has begun, recording the call the
+     * close ended. With a budget, a stop() can take up to six of them, besides
+     * the withheld-spill deadline of a guard's write still under way. Omit to
+     * wait until each settles, as required by existing module/child contracts.
+     * A wait whose budget runs out fails the stop() with a ShutdownTimeoutError
+     * naming what it waited for; with more than one, or beside another failure,
+     * stop() fails with an AggregateError of them all. A stream whose cancel
+     * threw is treated as one whose wait ran out, whatever the budget, and the
+     * stop() fails with the cancel's error: that stop() doesn't wait for it,
+     * even with no budget, and a later stop() waits for it as for anything an
+     * earlier one left running (the last point below). After either:
      * - an agent still registered whose stream is still running keeps its
      *   deferred writes queued, since the stream may still write. The stream's
      *   own turn-end flush takes them when it settles, if the process lives on,
@@ -716,11 +810,18 @@ export declare class AgentFramework {
      *   land in the run's namespace after them.
      * - an event loop still in a call, such as a module's onProcess, finishes
      *   that call and the rest of its iteration, and then exits. A start()
-     *   made meanwhile runs its own loop beside that last iteration.
+     *   made once that stop() has failed runs its own loop beside that last
+     *   iteration.
      * - a later stop() waits again, within its own budget, for any stream or
      *   loop this one left running, so the store never closes under it.
      */
     stop(teardownTimeoutMs?: number | undefined): Promise<void>;
+    /** 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;
+     * 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
      * its whole life: its synchronous trace callbacks can reenter stop(), and
@@ -733,6 +834,22 @@ export declare class AgentFramework {
      * queue (after a failed or completed stop()). The admission rule for every
      * operator entry point, the host/command listener included. */
     private stopHasBegun;
+    /** stop()'s first step for each connect still in flight, in either engine:
+     *  end it, so it fails at once and its operation ends, its launch reaped,
+     *  rather than holding stop()'s wait until its handshake's deadline. A
+     *  modern connect's connection is registered before it starts and is
+     *  closed; a legacy one's handshake, and the access provider a WebSocket
+     *  dial waits for, are aborted (legacyConnectAborts). A modern close's
+     *  outcome is the teardown's to report (closeModernMcpConnections). */
+    private endConnectsInFlight;
+    /** Wakers for the waits a connect makes that a stop() ends: see
+     *  untilStopBegins. Made on first use. */
+    private stopWaiters;
+    /** `work`, or undefined once stop() has begun, whichever comes first: a
+     *  connect's last step (its tool listing, which asks every server) needn't
+     *  hold stop()'s wait for operator operations on a server that doesn't
+     *  answer. The work goes on; the teardown's close ends what it waits for. */
+    private untilStopBegins;
     private refuseOperatorAfterStop;
     /** Wait in rounds until the set is empty: admitted work can still start work
      * of its own. All rounds share the caller's deadline rather than renewing
@@ -837,7 +954,9 @@ export declare class AgentFramework {
      * 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.
+     * framework is never left with a wait parked for days. The frame's window
+     * (checkWindow) carries a waker that ends the whole wait: a stop
+     * abortInference() records, or an operator's abandon, wakes it.
      */
     private waitForRetry;
     /**
@@ -968,7 +1087,10 @@ export declare class AgentFramework {
     offTrace(listener: TraceEventListener): void;
     private removeTraceRegistration;
     /**
-     * Add a module at runtime.
+     * Add a module at runtime. Refused, with a rejection, while a stop() is
+     * still running: a module added then would either be stopped by that stop
+     * or, once the stop has taken its list of modules to stop, stay started
+     * past it.
      */
     addModule(module: Module): Promise<void>;
     /**
@@ -989,7 +1111,10 @@ export declare class AgentFramework {
      */
     getConversationRouter(): ConversationRouter | null;
     /**
-     * Abort an in-flight inference for an agent.
+     * Abort an in-flight inference for an agent. True when there was one to
+     * stop: a stream, or a turn with no stream and one of its checks ahead (its
+     * hooks or compile, a wait to retry, the tool-result guard's wait), which
+     * ends at that check, before it sends anything more.
      */
     abortInference(agentName: string, reason?: string): boolean;
     /**
@@ -1015,9 +1140,10 @@ export declare class AgentFramework {
      * Terminal for a stop the framework itself made: stop()'s shutdown and an
      * operator's quiesce abandon, each recorded in frameworkCancelledStreams
      * before the cancel. A stream may report that cancel as `aborted`, as
-     * `error`, or by just closing, and each of those ends here, so the three
-     * cannot drift: settle the turn (an ephemeral run rejects with the stop's
-     * own text), an attributable inference-log terminal, ONE inference:aborted
+     * `error`, by just closing, or by throwing, and each of those ends here
+     * (through endFrameworkCancel()), so the four cannot drift: settle the
+     * turn (an ephemeral run rejects with the stop's own text), an
+     * attributable inference-log terminal, ONE inference:aborted
      * carrying the framework's reason, gate release. No [turn-interrupted]
      * marker, since nobody stopped the agent, and none of the failure
      * accounting that inference:failed / inference:exhausted drive.
@@ -1030,6 +1156,8 @@ export declare class AgentFramework {
      * Get all registered modules.
      */
     getAllModules(): Module[];
+    /** Read the namespaced utility catalogue without adding first-class model tools. */
+    getAllUtilities(): import('./types/index.js').ToolDefinition[];
     /**
      * Get all available tools from all modules and MCPL servers.
      */
@@ -1040,11 +1168,22 @@ export declare class AgentFramework {
      *  a writable workspace mount for storage). */
     private referenceFetcherInstance?;
     private getReferenceFetcher;
-    /** Register every RFC-005 reference in a tool-result content array against
-     *  its server, then eagerly fetch the ones inside the autofetch envelope
-     *  (below the eager ceiling, connection origin — never worse than the
-     *  server having inlined the bytes). Failures are non-fatal: the stub then
-     *  says fetch_reference instead of a path. */
+    /** Register every RFC-005 reference in an MCPL peer's tool-result content
+     *  against its server, then fetch by `mode`:
+     *  - `register`: nothing. An in-process caller (executeMcplToolCall) may
+     *    never show the result to an agent, and an eager fetch would spend the
+     *    server's fetch budget, which the agent's own fetch_reference needs, on
+     *    bytes nobody asked for. A stub later made of a registered reference is
+     *    bound, so fetch_reference can fetch it.
+     *  - `model`: eagerly fetch the ones inside the autofetch envelope (below
+     *    the eager ceiling, connection origin — never worse than the server
+     *    having inlined the bytes). Failures are non-fatal: the stub then says
+     *    fetch_reference instead of a path.
+     *  - `script`: as `model`, then fetch every reference ("eagerly lazy"): a
+     *    script receiving a result is the strongest available signal that the
+     *    bytes are wanted (scripts process, they do not browse), so the stub it
+     *    receives carries a workspace path it can open directly.
+     *  A uri the result calls expired is fetched in no mode. */
     private autoFetchReferences;
     /** Core agent_settings keys — extension keys must not collide with these. */
     private static readonly AGENT_SETTINGS_CORE_KEYS;
@@ -1084,7 +1223,7 @@ export declare class AgentFramework {
      *  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. */
+     *  made while a stop() is still running is refused. */
     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
@@ -1097,9 +1236,11 @@ export declare class AgentFramework {
     /** Each guard that may have queued storage work, once, by agent name: the
      *  live agents' and every other that isn't idle. */
     private guardsWithStorageWork;
+    /** `think` for one agent: its same-round policy, and `skip_reply` named only where the agent may call it. */
     private buildThinkTool;
     /** agent_settings tool definition with module extension fields merged in. */
     private buildAgentSettingsTool;
+    private warnEmptyUtilityPermissions;
     private getToolsForAgent;
     /** Available is independent of presentation visibility; execution callers keep this surface. */
     private availableToolsForPresentation;
@@ -1472,11 +1613,12 @@ export declare class AgentFramework {
     /** previewAgentRuntimeSettings for an agent in hand: boot restore previews one not yet registered. */
     private previewRuntimeSettingsFor;
     /**
-     * Check if process logging is enabled.
+     * Whether process events and their responses are written to Chronicle
+     * (`processLogging.persist`). `process:completed` trace events are emitted
+     * either way.
      */
     isProcessLoggingEnabled(): {
         persist: boolean;
-        broadcast: boolean;
     };
     /**
      * Get the underlying store.
@@ -1605,8 +1747,10 @@ export declare class AgentFramework {
     /**
      * Create an ephemeral agent that is NOT registered in the main event loop.
      *
-     * Used by SubagentModule (and similar) to create short-lived agents
-     * that are driven externally (not by the framework's event loop).
+     * Used by SubagentModule (and similar) to prepare short-lived agents.
+     * Call runEphemeralToCompletion(agent, contextManager) to register and run
+     * the returned agent. Framework-created identities have tool authority only
+     * while registered; public tool calls before a run or after retirement fail.
      * The returned agent has its own ContextManager on a namespaced state
      * within the framework's shared Chronicle store — messages go to
      * `{namespace}/messages`, context log to `{namespace}/context`.
@@ -1713,23 +1857,24 @@ export declare class AgentFramework {
     private static readonly CHAT_CORE_TAGS;
     /**
      * Mark an inference refusal visibly: react on the message that holds the
-     * conversational locus (the most recent incoming channel message) with a
-     * category-specific emoji. Best-effort — failures are logged, never thrown,
-     * and non-Discord loci are silently skipped.
+     * refused agent's conversational locus (the most recent incoming channel
+     * message; 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;
     /**
-     * Rewind the single turn that fed a refused generation: redact the newest
-     * message the agent did NOT author (a tool result, or an incoming message)
-     * and inject a metadata-only marker in its place. The marker carries a
-     * *description* of what was withheld (kind + size), never the content — so it
-     * cannot itself re-trip the classifier — while the raw record survives in the
-     * chronicle log for forensics. Returns a record describing the removal, or
-     * null if there is nothing eligible to rewind (e.g. only the agent's own
-     * turns, or a prior system marker, remain).
+     * 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 auto path (on `stop_reason: refusal`) and the `/rewind`
-     * host command.
+     * Shared by the refusal rewind, automatic or forced by `/unstick`, and by
+     * the shed after inference exhaustion (quarantinePoisonedHistory).
      */
     private shedNewestTurn;
     /**
@@ -1741,12 +1886,6 @@ export declare class AgentFramework {
      * refusal clears. Returns the running count.
      */
     private updateRewindMarker;
-    /**
-     * Announce a refusal-rewind on the conversational surface (Discord), used
-     * when the withheld turn was a *human* message so it isn't dropped silently.
-     * Best-effort; mirrors reactToRefusal's locus resolution.
-     */
-    private announceRewind;
     /**
      * A turn that ended WITHOUT a refusal (a natural completion that wasn't
      * one, or a tool-ended turn) ends the rewind episode: the model responded.
@@ -2070,13 +2209,13 @@ export declare class AgentFramework {
      * reconnect or start delivers what is still pending.
      *
      * Like a server's drain, the delivery runs apart from the operation that
-     * started it: it isn't an operator's operation, so stop() doesn't wait for
-     * it. A drain already running when stop() begins runs on while the
-     * connections close, and what it can't deliver stays pending in the
-     * durable outbox. Once stop() has begun, none is started, since there's
-     * no point opening a drain that the teardown is about to cut off: the
-     * marks stay pending, and the next start's barrier reconciles the outbox
-     * with the branch and delivers them.
+     * started it: it isn't an operator's operation. A drain already running
+     * when stop() begins sends nothing more, and stop() waits for it to record
+     * the call it had in flight, which closing the connections ends; what it
+     * hasn't sent stays pending in the durable outbox, unrecorded. Once stop()
+     * has begun, none is started, since there's no point opening a drain that
+     * the teardown is about to cut off: the marks stay pending, and the next
+     * start's barrier reconciles the outbox with the branch and delivers them.
      *
      * @param after What moved the branch, for the log and the alert
      *   ("rollback", "branch switch", "undo" …).
@@ -2366,6 +2505,11 @@ export declare class AgentFramework {
     /** Deliver through the lane's ordinary path; report where it landed. */
     private deliverCoalesced;
     private wakeForCoalescedBatch;
+    /** Queue a wake for each agent of the batch's audience, when its latest
+     *  occurrence triggers inference. `plain`: an ordinary push wake, without
+     *  the subject a withdrawal of the batch's wakes goes by, for a render
+     *  placed in its agent's deferred queue (wakeToRead). */
+    private queueCoalescedWakes;
     /** Withdraw unstarted wakes whose sole cause is this subject (§4.2). */
     private cancelCoalescedWakes;
     /**
@@ -2412,13 +2556,25 @@ export declare class AgentFramework {
     private derivePushEventChannel;
     private processInferenceRequests;
     /**
-     * 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.
+     * Stamps for the rows the agent's reply stores in its current turn: its
+     * assistant responses, its tool_result rows (through `storeResults`), and
+     * the contained-wrapper row that stands in for a response. The turn's other
+     * stores (a delivery receipt, a routing notice, a deferred flush) aren't the
+     * reply's, and carry none.
+     * - A silent heartbeat tick stamps each of them for the whole turn, with the
+     *   separator text its request rendered. The stamps keep every row of the
+     *   tick identifiable after the turn, for a later retention policy to find
+     *   or collapse. The stamp names the agent: residents share one message
+     *   slot, and a broadcast tick reaches each of them with the same eventId.
+     * - A `[Continue]` prompt stamps the rows of each round that follows it
+     *   (`turnPrompts`).
+     * Request builds render each turn before the first surviving assistant row
+     * that carries its stamp and that they can recognise: one with a tool call,
+     * or with signed or redacted thinking (see silent-heartbeat.ts). The
+     * tool_result rows and the wrapper row are stored as `user`, so their
+     * stamps place nothing: they mark each row as the reply's.
+     * Undefined for ordinary turns, whose rows are stored exactly as before.
+     * (Named for its first use, the silent tick.)
      */
     private silentTurnRowMetadata;
     /** Record plain-prose segments this turn suppressed without drafts (proseRouting=disabled). */
@@ -2609,13 +2765,15 @@ export declare class AgentFramework {
      */
     private repinTurnLocus;
     /**
-     * Durable window notice for a channel the agent did not ask to open —
-     * subscription-policy admission, or an open forced by the agent's own
-     * delivery into a closed channel. The agent must always learn that the
-     * channel opened, and that `channel_close` opts out (their decision
-     * outranks policy). What an open channel delivers is its server's to say
-     * (#406), so the notice doesn't promise its traffic. System message: never
-     * triggers inference, never conversational, never locus-eligible.
+     * Durable window notice for a channel the agent did not ask to open: a
+     * subscription-policy admission, announced as the decision before its
+     * transport RPC (a failed open keeps the decision, and channel_list shows
+     * transport state), or an open that the agent's own delivery or reply
+     * caused (`opened-by-delivery`, `opened-by-reply`), once its transport is
+     * confirmed. Either way it names `channel_close` as the opt-out (their
+     * decision outranks policy). What an open channel delivers is its server's
+     * to say (#406), so the notice doesn't promise its traffic. System message:
+     * never triggers inference, never conversational, never locus-eligible.
      */
     private recordChannelAutoOpenNotice;
     /**
@@ -2727,6 +2885,27 @@ export declare class AgentFramework {
      * newer turn instead.
      */
     private abortDroppedTurn;
+    /**
+     * The stop no stream will carry, collected at a check of the frame whose
+     * window it is (a start's checks before it sends anything, and the checks
+     * at a failure and after a wait to retry): an operator's quiesce abandon of
+     * the turn (the window's mark), else a caller's cancelStream() or
+     * abortInference() made while the agent held no stream, since the start
+     * that dropped an older one at its entry. When both are there, the
+     * framework's own stop is the one that ends the turn, as at a stream's
+     * terminal, and the caller's goes with it.
+     */
+    private takeStartStop;
+    /**
+     * 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
+     * settleDeliberateCancel ends a cancelled stream, with the note saying the
+     * turn was stopped before it sent anything (or, for a start that continues
+     * a turn, before it finished), and a quiesce abandon as
+     * settleFrameworkCancel ends one. Each settles the turn, an ephemeral run
+     * included, and emits the one inference:aborted.
+     */
+    private endStoppedStart;
     /**
      * Body of startAgentStream, split out so the caller's try/finally owns the
      * turn token unconditionally. Returns true iff the token was handed off to
@@ -2744,8 +2923,12 @@ export declare class AgentFramework {
      * call entered through — a public method shared with model callers can
      * never confer module trust, whatever the input claims. Module origin
      * exists only through the private closure handed to ModuleRegistry
-     * (ctx.callTool → executeToolCallFrom with {kind:'module'}). Callers that
-     * don't identify themselves fail safe to agent semantics too.
+     * (ctx.callTool → executeToolCallFrom with {kind:'module'}), which is exempt
+     * from agent allowlists. Registered agents' allowedTools is enforced at
+     * dispatch, including namespaced utility names; utils only grants the
+     * list/describe/run slot. Genuinely unidentified public callers (including
+     * unknown legacy names) remain unrestricted. Framework-created identities
+     * are refused while unregistered, even if their configured list allows it.
      */
     executeToolCall(call: ToolCall): Promise<ToolResult>;
     /**
@@ -2904,14 +3087,45 @@ export declare class AgentFramework {
     private getOrCreateScriptRunner;
     /**
      * Resolve one script-inner tool call to the string the script's tool
-     * function returns. Never rejects — errors become "Error: ..." strings,
-     * matching the managed PTC runtime ("Claude's code receives this error").
+     * function returns, and whether that result is an error (the script's
+     * `.is_error`). Never rejects: a failure without structured content becomes
+     * an "Error: ..." string, matching the managed PTC runtime ("Claude's code
+     * receives this error"), and a structured one its JSON object.
      *
-     * Results are serialized with the HISTORY serializer (images become
-     * placeholders): programmatic tool results are text-only by contract, and
-     * a script variable holding megabytes of base64 helps nobody.
+     * A result without structured content is serialized with the HISTORY
+     * serializer: images become placeholders, since a script variable holding
+     * megabytes of base64 helps nobody. A result with structured content is
+     * one JSON object holding both of the server's views
+     * (scriptStructuredResult), so its content blocks reach the script as the
+     * dispatch gave them, images and payloads included. A module's result that
+     * can't be stored or sent, such as a cyclic object or a BigInt, is already
+     * an error naming the tool when the dispatch returns it (storableToolResult),
+     * so a script reads that error's text.
      */
     private handleScriptToolCall;
+    /** The 5MB protocol safety cap on what a script receives. */
+    private static readonly SCRIPT_RESULT_MAX_CHARS;
+    /**
+     * A structured MCP result as a script receives it: one JSON object holding
+     * both of the server's views, `{ content, structuredContent, isError }`,
+     * plus `error` (the text) on a tool error. `content` is the content array
+     * the dispatch gave this call (the direct reading): the server's blocks as
+     * sent, so payloads and images survive, except that an MCPL peer's blocks
+     * get the treatment RFC-005 gives them on every lane the model reads
+     * (referenceBlockForScript). `structuredContent` is the tool's own JSON, as
+     * sent. Past the size cap the result stays valid JSON: the whole object is
+     * saved to the workspace, and the script gets
+     * `{ isError, oversized: { chars, savedTo } }`. If it can't be saved, the
+     * script gets a failure to materialize the result, saying the tool may
+     * already have completed, never a success missing its result. A result
+     * that can't be converted to JSON (a cyclic object, a BigInt), which the
+     * dispatch's own check makes unlikely here, gets the same object empty,
+     * `{ content: [], structuredContent: null, isError: true, error }`, the
+     * error naming the tool. In every form, the script's `.is_error` is the
+     * `isError` of the object its string holds, and its `.structured` is read
+     * from that string.
+     */
+    private scriptStructuredResult;
     /**
      * Dispatch a script-inner tool call through the NORMAL dispatch path and
      * resolve with its result. The waiter intercept in handleProcessEvent
@@ -2959,6 +3173,9 @@ export declare class AgentFramework {
      *  entry for it, and its usage can be counted twice in the log. */
     private logInference;
     private logProcessEvent;
+    /** Count one server's close (see mcplServerCloses). Partially-constructed
+     *  frameworks (tests build them with Object.create) have no map yet. */
+    private noteMcplServerClosed;
     /** Forget one server's RFC-008 class declarations (see the close handler). */
     private dropMcplToolClasses;
     /**
@@ -2994,15 +3211,20 @@ export declare class AgentFramework {
     }>;
     /**
      * Find the MCPL server for a tool: [serverId, prefix], or null.
-     * Prefixes can nest (`foo` and `foo--bar`), so `foo--bar--x` can match
-     * both. The tool listing decides: the server whose tools/list offered the
+     * 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
-     * closed since keeps its names until the next one). Where two servers list
-     * the same name, the listing holds the one listed last (#265). A name the
-     * listing doesn't hold (invented by the model, or no longer listed) goes to
-     * the longest matching prefix. Never prefix-map insertion order.
+     * 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
+     * `foo--bar`, are refused at configuration (prefixesMeet, #265), so a name
+     * fits at most one configured server's prefix; this rule doesn't rely on
+     * that. Never prefix-map insertion order.
      */
     private resolveMcplTool;
+    /** Registered policy; framework-created identities have no dispatch authority
+     * while unregistered. Genuine legacy caller names retain their surface. */
+    private canAgentUseTool;
+    private agentToolPermissionFailure;
     /**
      * Why this host refuses a skip_reply call, as the model will read it, or
      * undefined when it doesn't (skipReplyWakeRefusal): without an EventGate,
@@ -3085,13 +3307,20 @@ export declare class AgentFramework {
      * of the body isn't stored. (Requeued, the
      * landed shards would be stored twice, and only the rest could not be
      * appended later without splitting the body.) Boot's scan for landed
-     * writes counts a landed shard the same way.
+     * writes counts a landed shard the same way. When the store can't be read
+     * back (storedCopiesOf logs it), nothing is found, and the entry is put
+     * back as one that couldn't be stored: if it had landed, a later flush
+     * stores it again.
      *
      * Returns what was written (stored, or deferred again by addMessage, whose
      * id is then empty), in queue order: for one target, a prefix of its
-     * entries. `onLanded` hears an entry whose write threw after storing it,
-     * with the id it landed under, as soon as it's found: before the writes
-     * after it, so whatever it records keeps their order.
+     * entries. Each comes with its content: as given, unless the store took it
+     * as more than one message (a sharded body) and can be read back, when its
+     * copies are returned joined, as later compiles render them (asCompiled),
+     * or its write threw after storing it (above). `onLanded` hears an entry
+     * whose write threw after storing it, with the id it landed under, as soon
+     * as it's found: before the writes after it, so whatever it records keeps
+     * their order.
      */
     private writeDrainedInOrder;
     /** How many messages the agent's store holds: undefined when its store
@@ -3116,6 +3345,149 @@ export declare class AgentFramework {
      *  the writes after it: an open turn's arrivals keep the order the writes
      *  landed in, and its newest stays the newest (remainingArrival). */
     private readdDrained;
+    /**
+     * Where a notice about an agent's own action belongs: its failed reply, its
+     * bounced prose (beside its `{{unsent}}` clipboard), its background script's
+     * wake, the notices about its drafts. Every registered agent's notice is
+     * addressed to that agent, so it lands in the window that agent reads and
+     * waits on that agent's own turn, stream and tool cycle: a conversation
+     * fork or an ephemeral run reads only its isolated slot, and a resident's
+     * notice would otherwise wait on the primary's turn rather than its own.
+     * Residents share one message slot, so a resident's notice can land there
+     * while another resident's turn is alive; agent-framework #291 covers that.
+     *
+     * null when the agent is no longer registered (a fork or a run already
+     * released): there is no window to write, so the caller writes nothing,
+     * traces nothing and requests no wake. The drop is logged here, once. A
+     * failed reply is passed on by name instead (passFailedReplyToPrimary). The
+     * notice of a channel an agent's own send opened follows the same rule in
+     * recordChannelAutoOpenNotice, which passes it on by name too.
+     */
+    private noticeTargetFor;
+    /**
+     * A conversation fork or an ephemeral run has been deregistered. A release
+     * never runs while the host is quiesced: it waits for resume()
+     * (releaseWindowNowOrAfterResume), since a write could land mid-surgery.
+     *
+     * The agent never reads its window again, so every failed-reply notice it
+     * never read is passed to the primary, by name, once: each one stored in
+     * its window above its consumed watermark (flushed there at its turn's end,
+     * or stored while it was idle) and not heard at a tool boundary, and each
+     * one still queued for it. Writes still
+     * queued would wait for a boundary it never reaches, and the flush that
+     * finds it gone would drop them, so they land in its own window now, which
+     * Chronicle keeps for investigation. Its stream is over or cancelled, so it
+     * compiles nothing more. One path still stores after these writes: a
+     * `complete` that arrived while the agent still waited for tools awaits
+     * the spill of its last tool results, and stores them once that resolves,
+     * even if a watchdog has ended the run meanwhile. A tool boundary stores
+     * nothing for a round whose turn was stopped while its results were
+     * prepared.
+     */
+    private releaseWindow;
+    /**
+     * The failed-reply notices stored in `agent`'s window that it never read:
+     * those above the lower of its consumed watermark and the point where the
+     * watermark's branch and the current one part (branchesPartAt), or every
+     * one, when it never compiled. The watermark moves at a compile, and at a
+     * tool boundary whose
+     * stream declares it carries the messages injected there
+     * (markContextConsumed), so a notice the live stream heard is under it, and
+     * one a boundary stored without sending (a turn a tool ended, a budget
+     * restart, a stream that may drop injections) is above it.
+     */
+    private unreadFailedReplies;
+    /**
+     * The last sequence two branches' histories share: Infinity for one branch,
+     * and for two, the point where they part. A branch's records are numbered
+     * on from its branch point (Chronicle gives each record its branch's head
+     * plus one), so up to that point both hold the same records under the same
+     * numbers, and past it each branch's numbers are its own. -Infinity when
+     * the store knows no shared history for them, as for an empty branch.
+     */
+    private branchesPartAt;
+    /**
+     * Release a deregistered fork's or run's window (releaseWindow) now, or,
+     * while the host is quiesced, when it resumes. A release lands the agent's
+     * queued writes in its window, and while quiesced a write could land
+     * mid-surgery; dropping them instead would lose them from both the window
+     * and the recovery queue. Only the window waits: the agent is already
+     * deregistered, so its stream can't dispatch anything more and resume
+     * doesn't weigh its context, and a write addressed to it meanwhile is
+     * treated as for any agent no longer registered (dropped, or passed to the
+     * primary if it's a failed reply).
+     */
+    private releaseWindowNowOrAfterResume;
+    /** resume(): the windows whose release the quiesce window postponed, each on its own. */
+    private runReleasesAfterResume;
+    /**
+     * A fork or an ephemeral run ended before reading that its reply's delivery
+     * to a channel failed: it was released with the notice stored in its window
+     * unread, or its delivery failed after release. (A notice still queued for
+     * it, at release or restored at boot, goes on as the queue entry itself:
+     * queuedFailedReplyForPrimary.) Tell the primary instead, naming the
+     * speaker, so an agent who can still act learns of it and can tell the
+     * human. It gives the reply's length, not its words, which stay in the
+     * speaker's window. Its wording follows the speaker's own notice
+     * (onRouteFailure): a delivery that wasn't confirmed may have been posted,
+     * and neither text says no one saw the reply, since only this channel's
+     * routing failed. Only for a delivery to a channel; a reply that had no
+     * channel to go to (no locus) had no human waiting for it. Never throws:
+     * it runs inside a release, which must complete whatever this write meets.
+     */
+    private passFailedReplyToPrimary;
+    /**
+     * A queued failed-reply entry for `speaker`, who is gone, as the primary's
+     * by-name notice (passFailedReplyToPrimary's words): the same entry, under
+     * its own id and seq, now addressed to the primary. Written through the
+     * drain, it lands stamped with that id, or waits in the queue under it, so
+     * boot's exactly-once holds for it: a crash before the original's ack
+     * replays one entry, never the original and a separate notice. null when no
+     * one is told (logged): a reply that had no channel to reach, or no primary.
+     */
+    private queuedFailedReplyForPrimary;
+    /** The primary's by-name notice of `speaker`'s failed reply, or null when no
+     *  one is told, which is logged here (see passFailedReplyToPrimary). */
+    private failedReplyNoticeForPrimary;
+    /**
+     * A channel as a notice names it: the label when the registry has one, since
+     * a bare snowflake is unresolvable for the agent (the 2026-07-21 incident
+     * read as "a stale artifact", not a live failure).
+     */
+    private channelForNotice;
+    /**
+     * A module's write through its context: addMessage's, except that a write
+     * the framework holds is answered by its handle (heldHandle) rather than
+     * '', so the module can find, read, edit and remove what it wrote before
+     * the write lands. The framework's own callers keep the '' they've always
+     * had, which their traces and checks take as a write not stored yet.
+     */
+    private addModuleMessage;
+    /**
+     * The writes the framework holds for the store `reader` reads, in queue
+     * order: those addressed to it and, when it's an ordinary resident, those
+     * addressed to any ordinary resident, since residents share one message
+     * slot (sharedSlotAgents). A write whose target is gone isn't among them:
+     * no module reads that agent's store, and the write waits for its window's
+     * release (drainDeferredFor) or, at its flush, is dropped (addMessage), a
+     * failed reply passing to the primary as its notice
+     * (queuedFailedReplyForPrimary).
+     */
+    private heldWritesFor;
+    /**
+     * The writes held for `reader`'s store (heldWritesFor) as the rows a
+     * module's context reads: each under its handle, marked `held`, with the
+     * participant, content and metadata it was written with, the time it was
+     * first held as its timestamp, and a sequence after every row the store
+     * holds, in queue order. The sequence and timestamp are provisional: the
+     * stored row has the store's own.
+     */
+    private heldRows;
+    /** The row a held write landed as, found by the id it's stored with
+     *  (`metadata.deferredWriteId`): the first, for a body stored in shards,
+     *  as addMessage answers a stored write. Null when it hasn't landed, or is
+     *  no longer in the store. */
+    private landedRow;
     private editMessage;
     private removeMessage;
     private getMessage;
@@ -3234,6 +3606,44 @@ export declare class AgentFramework {
      * Fail-open: individual server connection failures don't prevent framework startup.
      */
     private initializeMcpl;
+    /** The modern connections, created on first use, so a framework assembled
+     *  field by field (as unit tests do) needs no setup for them. */
+    private modernServers;
+    /** The restarts' claims (mcpRestartClaims), created on first use, as the
+     *  modern connections are. */
+    private restartClaims;
+    private legacyConnectAborts;
+    /**
+     * Hold a server id for one connect or disconnect, until `release()`.
+     * Together with the live connections (the MCPL registry and the modern
+     * map) this is what holds an id: from a connect's admission until its
+     * teardown is done, one owner at a time. So a connect is refused while
+     * anything holds its id, and a teardown never removes what a later
+     * connection registered. A disconnect takes the hold over, and waits for
+     * the operation it displaced (`previous`); a connect that finds itself
+     * `displaced` ends rather than setting up a server being removed. Each
+     * release frees only its own hold.
+     */
+    private holdMcpServerId;
+    /** Whether a server's connection still serves it, or is reconnecting to
+     *  it. One the host is closing or has closed doesn't, and neither does one
+     *  lost for good, whose reconnecting has stopped. */
+    private static mcpConnectionServes;
+    /**
+     * A connect whose failed launch couldn't be confirmed exited. Its
+     * connection stays registered, closed, and holds the id, so nothing
+     * launches beside a child that may still be running; a disconnect retries
+     * the reap, and completes once the exit is confirmed. Once stop() has
+     * begun it refuses a disconnect, and retries the reap itself, so no
+     * disconnect is offered then.
+     */
+    private unreapedConnectFailure;
+    /** Close every modern-MCP connection, including any connect still in
+     *  flight, so none outlives a failed startup or stop(). One whose close
+     *  fails or is still pending stays registered, holding its id, as a failed
+     *  connect's does, and every failure is thrown, as the MCPL registry's
+     *  closeAll does. `timeoutMs` bounds the wait without cancelling cleanup. */
+    private closeModernMcpConnections;
     /**
      * 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
@@ -3252,6 +3662,10 @@ export declare class AgentFramework {
      * Deliver every due ref independently. Permanent Discord failures are kept
      * in the ledger for audit but do not block later operations; retryable
      * failures remain pending for the next reconnect/list-change attempt.
+     * Once stop() has begun, a drain sends nothing more and records nothing
+     * for what it hasn't sent: that stays pending, as it was, for the next
+     * start's barrier. stop() closes the connections and then waits for each
+     * drain still running to record the call it had in flight.
      */
     private drainDiscordAwarenessOutbox;
     private readDiscordAwarenessPending;
@@ -3267,7 +3681,9 @@ export declare class AgentFramework {
      * 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.
+     * the same drain share the fresh pass that follows it. Once stop() has
+     * begun, a drain sends nothing more, so a gate armed then completes with
+     * what it found pending left for the next start.
      */
     private drainForGeneration;
     /**
@@ -3278,10 +3694,57 @@ export declare class AgentFramework {
      * meanwhile. Rejects as the generation it waited for rejects.
      */
     private awaitDiscordAwarenessBarriers;
+    /**
+     * Per connection, the transport epoch whose §5.3 policy exchange is in
+     * flight: a connect's, from when the registry hands the connection back,
+     * or a reconnect's, from its 'reconnect' event. Until the exchange settles,
+     * that transport's traffic must wait for its grant, so a gate that opens
+     * every connection's planes meanwhile (another server's list change, a
+     * resume, an awareness sync, startup's staged open) passes it by
+     * (mcplPlanesMayOpen), and the exchange's own caller opens them once it
+     * settles (openMcplPlanesAfterExchange).
+     */
+    private readonly mcplPolicyExchanges;
+    /** Whether a gate may open this connection's planes: no policy exchange is
+     *  in flight on its current transport (see mcplPolicyExchanges). */
+    private mcplPlanesMayOpen;
+    /**
+     * Run a connection's §5.3 policy exchange with its planes held: it is
+     * marked in flight for the transport it runs on, so no gate releases that
+     * transport's traffic before its grant exists. With `epoch`, it runs only
+     * on that transport: a runtime connect passes the one it registered, and
+     * if that transport is gone, the exchange isn't run, since a reconnect
+     * that adopts a next transport, if one comes, runs that one's. With
+     * `closeOnFailure`, as for a runtime connect or restart, an exchange that
+     * throws closes the connection for good, through the registry, before it
+     * lifts the marker: left live, the connection would be half registered,
+     * and unmarked before its close, a gate completing in between would let
+     * out what it held with no grant. A close that fails keeps the connection
+     * registered, but closed for good, it readies nothing but its own reports.
+     * Without `closeOnFailure`, as for a reconnect or a staged startup connect,
+     * an exchange that throws leaves the connection live with the grant it
+     * reached, empty if the policy step itself threw, and the marker lifts.
+     */
+    private settlePolicyExchange;
+    /**
+     * Open a connection's planes once its exchange has settled, when the gate
+     * its connect or reconnect installed was replaced during the exchange: the
+     * newer gate passed the connection by, and if it has completed, nothing
+     * else would open it. A connection whose transport dropped meanwhile is
+     * readied as any gate readies one between transports, so its own reports
+     * go on. How far follows what is held now: while a gate is up, only the
+     * control plane opens, since a gate holds data planes alone, and its
+     * completion, which no longer passes this connection by, opens the data
+     * plane; a quiesced host (issue #122) likewise opens only control planes;
+     * otherwise both open.
+     */
+    private openMcplPlanesAfterExchange;
     /**
      * Install one framework-global Discord-awareness generation before releasing
      * any inference-bearing event. With pending work or a drain still running,
-     * every MCPL data plane is paused while all control planes remain live.
+     * every MCPL data plane is paused while the control planes remain live,
+     * but for a connection whose policy exchange is in flight, which neither
+     * the release nor the completion opens (mcplPlanesMayOpen).
      * With neither, ready() runs synchronously so request responders preserve
      * their historical same-stack behavior.
      */
@@ -3289,6 +3752,14 @@ export declare class AgentFramework {
     private releaseMcplDataPlaneGate;
     private completeMcplDataPlaneGate;
     private failMcplDataPlaneGate;
+    /**
+     * Close a legacy connection for good through the registry. A close that
+     * can't confirm its child exited keeps the connection registered, holding
+     * its id, and emits no 'close', so no close listener takes its tools off
+     * the agents' list: this does, then rethrows the failure for the caller to
+     * report. A server the host has given up on leaves the list either way.
+     */
+    private closeMcplServerForGood;
     /**
      * Close a runtime connect's new connection for good, through the registry,
      * after a step of that connect failed. A close that fails keeps the entry,
@@ -3303,11 +3774,23 @@ export declare class AgentFramework {
      * lifecycle API (connectMcplServer). Throws on connection failure.
      */
     private connectMcplServerInternal;
-    /** Per-connection §17.8 fetch limiter: at most one in-flight fetch, at
-     *  most one queued behind it (announcements coalesce), floor between
-     *  completed fetches. Exceeding the floor drops the excess with a
-     *  diagnostic — the host bounds the rate; it never depends on server
-     *  coalescing. */
+    /** The part of a connect that runs holding its id, handing back the
+     *  connection it registered. `displaced`: whether a disconnect has taken
+     *  the id over and is waiting for this connect, which a legacy connect asks
+     *  once its handshake is done. */
+    private connectHeldMcplServer;
+    /** Per-connection §17.8 fetch limiter, keyed by the connection, so one
+     *  that replaces a removed server under its id starts its own: at most one
+     *  fetch in flight; announcements during it coalesce into one refresh run
+     *  after it, and announcements within the floor after a fetch into one run
+     *  once the floor has passed — the host bounds the rate; it never depends
+     *  on server coalescing. A queued refresh runs only on the transport of
+     *  the latest announcement it holds (`queuedEpoch`), and its receipt
+     *  reports the domains of the announcements coalesced into it there
+     *  (`queuedDomains`), since its fetch answers them all. The next
+     *  transport's initialize and policy exchange start afresh, and its own
+     *  announcements queue their own, so an earlier transport's hints are
+     *  dropped. */
     private manifestRefreshState;
     private static readonly MANIFEST_FETCH_FLOOR_MS;
     /**
@@ -3325,7 +3808,9 @@ export declare class AgentFramework {
      */
     private handleManifestChanged;
     /** A refresh handleManifestChanged schedules for itself, after the fetch
-     *  floor or behind a fetch in flight. It's contained as the announcement's
+     *  floor or behind a fetch in flight. Its announcement is the domains of
+     *  the announcements it coalesced (`{ domains }`), the one field
+     *  handleManifestChanged reads of one. It's contained as the announcement's
      *  own run is. Its fetch's own failure is logged by the fetch's catch, as
      *  in 0.22.x; any other failure emits mcpl:request-handler-error and a
      *  stderr line through the containment. */
@@ -3392,13 +3877,25 @@ export declare class AgentFramework {
      * false or null is refused, as `create()` refuses one.
      */
     connectMcplServer(config: import('./mcpl/types.js').McplServerConfig): Promise<void>;
+    /** connectMcplServer's work, for a restart's connect too: the id and tool
+     *  prefix its `claim` holds are free to it, and refused to everyone else. */
     private runConnectMcplServer;
     /**
-     * Disconnect an MCPL server at runtime: close the connection, destroy its
-     * feature-set and checkpoint state (permanent removal — unlike a transient
-     * transport close, which preserves checkpoints for the reconnect), remove
-     * its channels from the registry, drop routing entries, and refresh tools.
+     * Disconnect an MCPL server at runtime: remove its channels from the
+     * registry (first, cancelling their queued lifecycle work), close the
+     * connection, destroy its feature-set and checkpoint state (permanent
+     * removal — unlike a transient transport close, which preserves checkpoints
+     * for the reconnect), drop routing entries, and refresh tools.
      * No-op-ish if the server is not connected (still clears routing state).
+     *
+     * It holds the id throughout (holdMcpServerId): a connect for it is
+     * refused meanwhile, and a connect already in flight is ended (closed, or
+     * displaced when its legacy handshake finishes) and settles before
+     * anything but the channel entries the disconnect found when it began is
+     * removed. A close that can't confirm a child exited fails the disconnect
+     * before anything but those entries is removed: the server stays
+     * registered, closed, so nothing launches beside a child that may still be
+     * running, and disconnecting again retries the reap.
      */
     disconnectMcplServer(id: string): Promise<void>;
     private runDisconnectMcplServer;
@@ -3407,11 +3904,63 @@ export declare class AgentFramework {
      * same (or an updated) config. This actually respawns a stdio child —
      * unlike `reconnect: true`, which only retries after transport-level
      * failures. Throws if the server has no stored config and none is given.
-     * A config `connectMcplServer` would refuse for its boolean settings is
-     * refused before the running server is disconnected, so it stays up.
+     * What its connect would refuse is refused before the running server is
+     * torn down. Until the connect, a connect or a restart started meanwhile
+     * is refused the id and the tool prefix the restart moves the server to,
+     * and a module added meanwhile is refused that tool prefix. The id and
+     * prefix it moves the server from are free once its disconnect is done, as
+     * after any disconnect.
+     *
+     * A disconnect of the id the restart moves the server to (its own id, for
+     * a restart under the same id), or a `stop()`, that begins during the
+     * restart ends it, as a disconnect ends a connect in flight: the restart
+     * rejects, saying the server is down, and its holds are released, and the
+     * server isn't left configured, as after any disconnect. A restart whose
+     * connect fails on its own leaves the server down, configured under the
+     * new configuration and its id, and holding its tool prefix, as any failed
+     * connect does: `listMcplServers()` lists it as not connected, and a
+     * restart or a disconnect under that id tries it again or removes it.
+     *
+     * Treat a submitted configuration and its nested values as immutable for
+     * as long as the server uses them. Apply changed settings with
+     * `restartMcplServer(id, newConfig)`; use `accessProvider` for a network
+     * server's rotating credentials (a stdio server's changed `env` goes
+     * through a restart with the new configuration).
      */
     restartMcplServer(id: string, newConfig?: import('./mcpl/types.js').McplServerConfig): Promise<void>;
     private runRestartMcplServer;
+    /**
+     * A redactor for text that may come from any configured server, with every
+     * server's credentials replaced: those of the configurations present when
+     * it's made, then those present when it's used. An operation makes it
+     * before it waits, so a server removed meanwhile, and one connected
+     * meanwhile, both have their credentials replaced. When one of them can't
+     * be read, the text is withheld, as redactServerText withholds it.
+     */
+    private everyServerRedactor;
+    /** Why a connect for this id is refused, or null when the id is free. One
+     *  owner per id, across both engines (holdMcpServerId): a connect or
+     *  disconnect in flight holds it, and so does a registered connection,
+     *  including one kept because its launch couldn't be confirmed exited, and
+     *  a restart moving its server to the id (mcpRestartClaims), except to
+     *  that restart's own connect (`claim`). That connect is still refused
+     *  while a disconnect of the id is in flight: the restart's own disconnect
+     *  has finished by then, so that one began during the restart, and it ends
+     *  the restart. `restarting` words the refusal for a restart of that
+     *  server checking the id it would move to. */
+    private mcpServerIdTaken;
+    /** The collision rules create() enforces at startup, as a runtime connect
+     *  (or a restart, before its disconnect) meets them, in either engine: the
+     *  tool prefix must not shadow a module name or another server's prefix,
+     *  or meet another server's (prefixesMeet, #265), and must neither be nor
+     *  meet one a restart is moving its server to (mcpRestartClaims). The
+     *  server's own prefix is free to keep, so is that of the server a restart
+     *  is about to disconnect (`leaving`), and so is the prefix a restart's own
+     *  connect holds (`claim`). */
+    private mcplPrefixCollision;
+    /** The protocol family a configuration resolves to, or a refusal naming
+     *  every problem with it, before anything is spawned, dialed or torn down. */
+    private static usableConfigFamily;
     /**
      * List configured MCPL servers with live connection status and the number
      * of tools each currently contributes.
@@ -3420,10 +3969,22 @@ export declare class AgentFramework {
         id: string;
         connected: boolean;
         retrying: boolean;
+        /** Which engine serves it: `legacy` (MCP 2024-11-05 + MCPL) or `modern`
+         *  (MCP 2026-07-28), as its configuration selects; null when the
+         *  configuration names no usable transport (see `refused`). */
+        family: 'legacy' | 'modern' | null;
+        /** The MCP revision its last handshake established; null until one has. */
+        protocolVersion: string | null;
+        /** How it is reached; null when the configuration names no usable transport. */
+        transport: 'stdio' | 'websocket' | 'http' | null;
+        /** Why connecting refuses this configuration, before anything is spawned
+         *  or dialed; null when it is usable. */
+        refused: string | null;
         toolPrefix: string;
         toolCount: number;
-        /** True only after the §5.3 policy receipt activated the grant. */
-        policyEstablished: boolean;
+        /** True only after the §5.3 policy receipt activated the grant. Null for
+         *  a modern server, which has no MCPL policy. */
+        policyEstablished: boolean | null;
         /** Sole normative authorization allowlist for the connection (§5.4). */
         effectiveGrant: string[];
         /** Advertised paths removed by host enabled/disabled capability config. */
@@ -3462,6 +4023,10 @@ export declare class AgentFramework {
             lastNegotiatedAt: number | null;
         };
         command?: string;
+        /** The url as {@link redactUrl} shows it, since a credential may ride in
+         *  it: no userinfo, each query parameter's value replaced, and any path
+         *  segment or query parameter name that looks like a credential
+         *  replaced. */
         url?: string;
     }>;
     /**
@@ -3470,6 +4035,9 @@ export declare class AgentFramework {
      * rejection at this boundary, including failures after channels/register or
      * channels/changed has acknowledged the request. It's invoked at once, so
      * control-plane replies keep their acknowledge-before-reconcile order.
+     * Each text a failure records, in its trace and its log line, goes through
+     * `recorded`, the server's redactor where the caller has one, since a
+     * handler's error can quote what the server sent.
      */
     private containedInboundHandler;
     /**
@@ -3477,9 +4045,29 @@ export declare class AgentFramework {
      * Push events and inference requests are deferred to Steps 6/7.
      */
     private wireMcplEvents;
+    /**
+     * Wire a modern-MCP connection's events. There's less here than for MCPL
+     * on purpose: no push, inference, channels or policy exist on this family.
+     * A list change, including the relist after a reconnect, takes the legacy
+     * engine's refresh path (`handleToolsListChanged`), so any wake it causes
+     * goes through ordinary admission: it parks under quiesce or a hold like
+     * every other wake. It installs no awareness gate, since that gate orders
+     * MCPL data-plane traffic, which this family doesn't carry.
+     */
+    private wireModernEvents;
+    /** An MCP tool call's trace: a result the server marked an error (or one
+     *  the reading couldn't complete) is tool:failed, as on the other tool
+     *  paths; anything else is tool:completed. */
+    private traceMcpToolOutcome;
     /**
      * Discover tools from all connected MCPL servers and cache them.
      * Tools are namespaced as `{toolPrefix}--{toolName}` per server config.
+     * No two servers' prefixes meet (prefixesMeet, refused at create(), a
+     * runtime connect and a restart), so no two servers give one name. A
+     * server that lists one name more than once keeps its first listing, and
+     * an ops alert at each refresh that finds it says so (#265): a tool list
+     * holding one name twice is refused by membrane's native formatter and by
+     * Anthropic's API.
      */
     private refreshMcplTools;
     /**
@@ -3509,11 +4097,47 @@ export declare class AgentFramework {
      * Emit a trace event and push an external-message listing newly added tools.
      */
     private emitMcplToolDiff;
+    /** The refusal of a tool call whose server isn't one to call yet, for the
+     *  model's call, a script's and an in-process one alike: none registered,
+     *  or a modern connection whose connect is still under way
+     *  (modernStillConnecting). It says "connecting" while a connect of its id
+     *  is in flight (mcpServerOps) or a restart holds the id, and "gone"
+     *  otherwise. */
+    private mcplServerAbsentText;
+    /** A modern connection a connect still under way registered: it registers
+     *  before it starts, so until its first session is up it's no server to
+     *  call, and a call reads the "connecting" text, as one during a legacy
+     *  connect's handshake does. Once that session is up, a call goes to it,
+     *  even while the connect lists its tools. */
+    private modernStillConnecting;
     /**
      * Dispatch a tool call to an MCPL server.
      * Strips the configured toolPrefix and routes to the server.
      */
     private dispatchMcplToolCall;
+    /**
+     * The direct path's reading of an MCP tool result (executeToolCall,
+     * ModuleContext.callTool). `data` stays the raw content array, as module
+     * callers have always received it. Two things change: a tool error
+     * (`isError: true`) is now a failure, where every answer used to count as
+     * success, and `structured` is added by presence.
+     */
+    private static directToolResult;
+    /**
+     * The framework's ToolResult for an MCP tool result on the model path
+     * (model dispatch, and scripts, which ride it). A standard peer, meaning an MCP-only legacy
+     * server or any modern server, gets the standard reading
+     * (tool-result-normalize.ts): typed content blocks, workspace-saved
+     * payloads, and `structured` kept by presence. An MCPL peer keeps the
+     * RFC-005 reading. Its content array passes through when it holds
+     * non-text blocks, so references and images render natively. It gets
+     * `structured` too, with the JSON view when its content is empty. The
+     * direct path (a module's callTool, a channel's tool call) doesn't come
+     * here: it returns the server's result itself (directToolResult), for
+     * either engine, as does a script's call whose result is structured, with
+     * an MCPL peer's blocks given RFC-005's treatment (referenceBlockForScript).
+     */
+    private mcpToolResult;
     /**
      * Build BeforeInferenceParams from agent state and trigger context.
      */