@animalabs/agent-framework 0.26.2 → 0.28.0

package/README.md

@@ -118,11 +118,11 @@ interface Module {
 
   // Optional
   onAgentSpeech?(agentName: string, content: ContentBlock[], context: SpeechContext): Promise<void>;
-  gatherContext?(agentName: string): Promise<ContextInjection[]>;
+  gatherContext?(agentName: string): Promise<ModuleContextInjection[]>;
 }
 ```
 
-An `EventResponse` can add/edit/remove messages, request inference, signal tool changes, and atomically update module state:
+An `EventResponse` can add/edit/remove messages, update module state, request inference, and signal tool changes. The framework applies its message changes, then its state update, then its inference request; when one of these throws, what came before it stays applied, that step may have taken effect in part, and the rest of that response isn't:
 
 ```typescript
 return {
@@ -150,7 +150,7 @@ Each agent has a `ContextManager` (from `@connectome/context-manager`) that main
 - **PassthroughStrategy** - No compression, raw message replay up to budget
 - **AutobiographicalStrategy** - Chunks old messages and summarizes them into diary entries, preserving recent context uncompressed
 
-Before inference, modules and MCPL hooks can inject additional context via `gatherContext()`.
+Before inference, modules and MCPL hooks can inject additional context via `gatherContext()`. An `afterUser` injection is stored in the agent's window, as the message `compile()` would have placed after the last user message, so it stays where the agent saw it: the replies after it keep their thinking, and the cache keeps the turns before it. A source's unchanged content isn't stored again while the copy the agent will read as current has it whole: the one its last request held, or a newer one a start stored whose compile then didn't record (it threw, or the start failed before it); once a fold has summarized it or the strategy's window has passed it, it's stored again, as one more row. Where a changed one lands right after the agent's own latest message, with no one else's message between, `[Continue]` still ends the request, after it. A stored row is history to the strategy, capped, sharded, budgeted and folded like any message. Its metadata carries `system: true`, `kind: 'context-injection'` and `contextInjection: { agent, namespace, contentHash, part, parts }`, which `storedInjectionMarkOf` reads, and every other agent's view leaves it out. A module's injection can set `placedEachCompile: true` to be placed by `compile()` at each start instead, near the end, at the cost of the thinking of every reply after its old place.
 
 ### Persistence
 
@@ -347,8 +347,9 @@ three ways:
   configuration error: `allowHostCommands: true`, an `enabledCapabilities`
   pattern that matches a capability denied by default, `channelSubscription:
   'auto'` or a non-empty list, a scope's non-empty `whitelist`, a
-  `toolLifecycle` `observe` or `inputs` block, and a
-  `toolLifecycle.maxInputBytes` or an `autofetch` bound above its default.
+  `toolLifecycle` `observe` or `inputs` block, a
+  `toolLifecycle.maxInputBytes` or an `autofetch` bound above its default,
+  and `toolHints: true`.
   A setting
   that only takes something away, or repeats a default, is already
   satisfied, so it is accepted: `enabledFeatureSets` and the rest of
@@ -429,6 +430,94 @@ backlog is simply its unread backlog. Receipts and subject history are kept in
 the `mcpl/coalescing` state (retry window 1 h); audit lines are
 `mcpl:coalescing` trace events.
 
+#### Tool presence and toolsets (RFC-014)
+
+A server configured with `toolHints: true` (default false) is offered
+`experimental.mcpl.toolHints`, and its hints count only if it advertised
+`toolHints` too. Without it nothing changes: every tool is listed as before,
+and the host advertises and reads nothing new.
+
+With it, the server's static tools stay in the tool list as before, and its
+dynamic tools (those in a toolset, or hinted `mcpl/presence: "dynamic"`) never
+enter it, since every change to the list rebuilds the prompt cache. The
+framework registers a `toolsets` module with four constant tools:
+
+- `toolsets--open {server?, toolset?, instance?, options?}` opens a toolset (or
+  a named instance of one), and answers with what the server shows on opening
+  and the tools usable now;
+- `toolsets--act {server?, tool, instance?, args?}` calls a dynamic tool down
+  the same path as a direct call of it (the agent's `allowedTools`, the
+  server's tool policy, the state exchange, the reading of its result, RFC-007
+  observers and RFC-008 class rules, which see the server's tool and its class),
+  with only the instance added, in
+  `_meta["mcpl/instance"]`. It first checks `args` against the definition in
+  force for that instance; that check is bounded, and leaves `pattern` and
+  anything nested or branching too far to the server, which checks every
+  call itself;
+- `toolsets--look {server?, toolset?, instance?, tool?}` restates what is open
+  and what can be opened, or one tool's signature, description, class and
+  input schema. It
+  re-reads each server that presents toolsets first, and says so when it
+  couldn't; what that changed
+  is in the answer when look restates everything, and otherwise told as a
+  notice;
+- `toolsets--close {server?, toolset?, instance?}` closes it.
+
+`server` can be left out when only one server has the name. By our reading of
+the code, a server with no toolsets stops presenting them once its latest `tools/list` has no dynamic
+tool, so until the rebuild, act takes its last one only with `server` named.
+Hint changes apply
+as their message is read, in `rev` order, whatever becomes of the message (a
+refused push, a result that came after its timeout). A move between static and
+dynamic takes effect when the server's `tools/list` states it, and the tool
+list follows at its next rebuild that lists the server, whichever refresh
+brings it (a move is no reason to rebuild the tool list early). Until then the
+tool is called at either place, where the tool list shows it or where the
+server's latest list put it (RFC-014 §4.2 keeps it working where it is until
+the move applies), and
+once that rebuild has published the list, a notice says where it went. A list
+read while a rebuild is under way can undo a move that rebuild then publishes;
+neither is told, and the next rebuild puts the tool back.
+A skipped rev re-reads `tools/list` and then `toolsets/list`, which the host
+also reads after every (re)connect, adopting what the server kept open and
+never re-opening anything.
+What changed is told where it happened: after a call's own result, after the
+push that explains it, or as a notice (`kind: 'mcpl-toolsets'`, which wakes
+nothing) for a standalone `tools/hints`, a late result, an adoption, a
+recovery, or a call whose result may not reach the agent (a script's, a
+module's or a host's, or one the framework makes itself); an open, close or
+look made that way also shows its caller the change, unless the change has
+already gone as a notice (below). A dynamic tool's change also goes as a notice
+when it wouldn't fit whole within its result's inline cap, or when its call
+fails after the result was read. A call's change also goes as a notice, ahead of its
+result, when a later change goes to the agent before the call's caller has
+taken it, so changes are told in the order they were read (the agent's window
+can still show a call's result, a push's event, or a change its taker couldn't
+show after a change read later). The model's own call's change counts as told
+once its result is handed back: if the turn is stopped while the call is out
+(or, by our reading of the code, the agent is gone), the result is dropped and the change with it, and
+`toolsets--look` shows the state it left. Notices and reminders
+need the server's `pushEvents` grant, like any delivery; without it, a change
+that would go as a notice is dropped, and `toolsets--look` shows the state. A new tool's first sentence is told with its
+definition until text describing it has reached the model, except that, by our reading of the code, a puppet's
+open, close or look whose result the store refuses has already counted it. Suggestions are shown, never acted on. Each
+`ended` id is told once while the
+host runs (told ids are kept in memory), short of rare interleavings, such as a
+`toolsets--look` overlapping other reads of the same server, that can tell one
+twice. When an
+open toolset's announcements have left an agent's context (compressed or out
+of the window), the module's `gatherContext` restates what is open, as a
+stored `afterUser` injection (namespace `mcpl-toolsets`), at that agent's next
+start.
+
+A dynamic tool called by its prefixed name is refused, pointing at
+`toolsets--act`, unless the tool list or the server's latest list shows it as
+static (a move waiting for its rebuild). Calls to an undeclared toolset's
+tools are refused while the host has that group closed (RFC-014 §5.4), except
+by a tool's listed name until the rebuild that publishes its move into the
+group. Projection and surface mode are not implemented: a `surface` server's
+static tools are listed like any server's.
+
 #### Per-channel conversation routing (deprecated)
 
 > **Deprecated: `FrameworkConfig.conversations` (`ConversationRouter`).** Per-channel conversation routing sends each channel's traffic to its own fork agent, spawned from a template agent and closed after an idle TTL. It is being retired ([#235](https://github.com/anima-research/agent-framework/issues/235)). Its `'mention'` bind/trigger rule, the default for channels, reads `metadata.mentioned`, which discord-mcpl does not set, so on Discord channels an @-mention never binds a fork or triggers a bound one. Don't adopt it in new hosts. Existing configurations still route exactly as before, and the framework logs one `[deprecated]` line when it is created with `conversations` set. Removal is a follow-up.
@@ -439,7 +528,7 @@ the `mcpl/coalescing` state (retry window 1 h); audit lines are
 2. **Drive**: Framework iterates stream events (tokens, tool-calls, complete, error)
 3. **Tool yield**: Stream yields tool calls → framework dispatches concurrently → collects results
 4. **Resume**: All results in → stream resumes with tool results
-5. **Budget restart**: If input tokens exceed `maxStreamTokens`, the stream is cancelled, context is recompressed, and a fresh stream starts
+5. **Budget restart**: If input tokens exceed `maxStreamTokens`, the stream is cancelled, context is recompressed, and a fresh stream starts. An agent whose model binds its thinking (`thinkingBinding.binds`) with `physicalWindowTokens` set skips this, and the window projection restarts it instead before a request the window can't hold
 6. **Complete**: Final response saved to context, agent returns to idle
 
 ### Abort / Cancellation
@@ -451,9 +540,11 @@ framework.abortInference('assistant', 'user requested stop');
 
 The non-streaming path uses `AbortSignal` forwarded to `membrane.stream()`, which returns an `AbortedResponse` with partial content. The streaming path cancels the `YieldingStream` directly.
 
-A turn whose stream is cancelled this way, or by `agent.cancelStream()`, ends as a stop, whether the stream reports the cancel as `aborted`, as an `error`, or by just closing: one `inference:aborted` carrying the caller's reason (`user` when none was given), a `[turn-interrupted]` note in the agent's context, and never `inference:exhausted`, which is for failed inferences. A stream that membrane aborts on its own, at a deadline or on an error (reason `timeout` or `error`), is a failed inference. `stop()` and an operator's quiesce abandon end a turn as a stop too, with their own reasons, `shutdown` and `quiesce_abandoned`, and write no note. A stopped stream still writes its inference-log row, with `success: false`.
+A turn whose stream is cancelled this way, or by `agent.cancelStream()`, ends as a stop, whether the stream reports the cancel as `aborted`, as an `error`, or by just closing: one `inference:aborted` carrying the caller's reason (`user` when none was given), a `[turn-interrupted]` note in the agent's context, and never `inference:exhausted`, which is for failed inferences. A stream that membrane aborts on its own, at a deadline or on an error (reason `timeout` or `error`), is a failed inference. `stop()` and an operator's quiesce abandon end a turn as a stop too, with their own reasons, `shutdown` and `quiesce_abandoned`, and write no note, except the `[speech-not-posted]` notice when the turn's rounds left speech unposted (XML tool mode, or a membrane without `roundContent`; see below). A stopped stream still writes its inference-log row, with `success: false`.
+
+A caller's stop and an operator's quiesce abandon also reach a turn that has no live stream: one running its modules' `gatherContext`, its MCPL hooks or its compile, one waiting to retry a failed inference or compile (`abortInference()` and an operator's abandon end the wait, and a stop through `Agent.cancelStream()` waits for it to run out), and one whose tool-result guard is waiting to retry after a refusal, which holds only the round's finished stream. The turn ends at its next check, before it sends anything more, as a stop on a live stream ends it, and a turn whose compile fails after the stop ends at the failure, before a provider hold, the error policy's retry or `inference:exhausted`. A caller's stop leaves the note saying the turn was stopped before it sent anything or before it finished, and an operator's abandon leaves none, except the `[speech-not-posted]` notice when the turn's rounds left speech unposted. `abortInference()` returns `true` for such a turn. In the guard's wait, `stop()` ends the turn as a stop with reason `shutdown`, and an operator's abandon ends it as the abandon, even when a caller's stop came first; with both, it ends as `stop()`'s. `stop()` drops a turn in its hooks, its compile or a wait to retry before it sends anything, as before, and drops one whose compile fails while it runs, once a caller's stop has reached it, rather than ending it as that stop. While the failure of a turn's stream is reported (`inference:failed`), the agent no longer holds that stream, so `abortInference()` from a listener reports `false`. A failure to build a turn's request is reported while the turn's check is still ahead, so there `abortInference()` reports `true`, and the turn ends at that check. A caller's stop made where no check of a turn is ahead stops nothing, and doesn't end the agent's next turn: while the agent is idle, while a turn finishes its last delivery, and while a non-streaming turn's tool results wait to start the turn's next call. A turn whose continuation (a budget restart's, or a tool-result guard's retry) waits to start, or whose failed call a provider-capacity hold or a provider's stated wait keeps for its retry, is ended by `abortInference()`, by an operator's quiesce abandon and by `stop()`: the continuation or retry is dropped, and the turn ends with the caller's reason, `quiesce_abandoned` or `shutdown`. After `abortInference()` or an abandon, wakes that arrived meanwhile still run (after the abandon, once the host resumes): those a hold keeps beside the retry, and those the scheduler merged into the retry's or the continuation's start before that start began, which the stop or the abandon puts back in the queue. A stop through `Agent.cancelStream()` stops nothing there.
 
-A caller's stop and an operator's quiesce abandon also reach a turn that has no live stream: one running its modules' `gatherContext`, its MCPL hooks or its compile, one waiting to retry a failed inference or compile (`abortInference()` and an operator's abandon end the wait, and a stop through `Agent.cancelStream()` waits for it to run out), and one whose tool-result guard is waiting to retry after a refusal, which holds only the round's finished stream. The turn ends at its next check, before it sends anything more, as a stop on a live stream ends it, and a turn whose compile fails after the stop ends at the failure, before a provider hold, the error policy's retry or `inference:exhausted`. A caller's stop leaves the note saying the turn was stopped before it sent anything or before it finished, and an operator's abandon leaves none. `abortInference()` returns `true` for such a turn. In the guard's wait, `stop()` ends the turn as a stop with reason `shutdown`, and an operator's abandon ends it as the abandon, even when a caller's stop came first; with both, it ends as `stop()`'s. `stop()` drops a turn in its hooks, its compile or a wait to retry before it sends anything, as before, and drops one whose compile fails while it runs, once a caller's stop has reached it, rather than ending it as that stop. While the failure of a turn's stream is reported (`inference:failed`), the agent no longer holds that stream, so `abortInference()` from a listener reports `false`. A failure to build a turn's request is reported while the turn's check is still ahead, so there `abortInference()` reports `true`, and the turn ends at that check. A caller's stop made where no check of a turn is ahead stops nothing, and doesn't end the agent's next turn: while the agent is idle, while a turn finishes its last delivery, and while a non-streaming turn's tool results wait to start the turn's next call. A turn whose continuation (a budget restart's, or a tool-result guard's retry) waits to start, or whose failed call a provider-capacity hold or a provider's stated wait keeps for its retry, is ended by `abortInference()`, by an operator's quiesce abandon and by `stop()`: the continuation or retry is dropped, and the turn ends with the caller's reason, `quiesce_abandoned` or `shutdown`. After `abortInference()` or an abandon, wakes that arrived meanwhile still run (after the abandon, once the host resumes): those a hold keeps beside the retry, and those the scheduler merged into the retry's or the continuation's start before that start began, which the stop or the abandon puts back in the queue. A stop through `Agent.cancelStream()` stops nothing there.
+In XML tool mode, or with a membrane that gives a tool round no `roundContent`, such a round's speech reaches a channel only when its stream completes. When the stream ends any other way (a failure, a stop, a tool that ends the turn, an error policy's retry, a context-budget or tool-result-guard restart, a quiesce abandon or `stop()`), the rounds' words are already in the agent's context, and a `[speech-not-posted]` notice tells the agent that nothing it wrote before its tool calls in those rounds was posted, so it can send what should go out again. It's written once for those rounds: where the turn ends, or before a retry's or a restart's request is sent. A turn its own `skip_reply` ends, a silent turn, a round still waiting on its tools when its stream ends (which never reaches the context) and the rounds of a stream that completes get none. In XML tool mode with thinking on, a round whose text was only thinking gets the notice too, since the framework has only the round's raw text there. A failed turn's `[inference-failed]` note says that its earlier rounds ran when any round reached the context with its results, and that a round's tool calls were started and may have taken effect when any of its streams ended before that round's results came back; a caller's stop says the latter in its `[turn-interrupted]` note too. A turn that fails, or that a caller stops, writes no `[delivered]` receipt, so when its rounds' plain speech was delivered live (native tool mode, in locus or hybrid routing), its `[inference-failed]` note, or the stop's `[turn-interrupted]` note, says that speech was handed on for delivery as written and that no `[delivered]` line was written for it. When some of its speech was still being routed as the turn ended, the note also says it may yet be posted and to check the channel before sending it again. A delivery that finished undelivered gets neither: a channel delivery's `[discord-send-failed]` note, or a refused `>>>` envelope's bounce, already says what happened. A quiesce abandon and `stop()` write neither note.
 
 ## API Server
 

package/dist/src/agent.d.ts

@@ -1,6 +1,8 @@
-import type { Membrane, NormalizedRequest, ContentBlock, YieldingStream } from '@animalabs/membrane';
+import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, ThinkingBindingEntry, YieldingStream } from '@animalabs/membrane';
 import type { CacheWireReceipt } from './kv-unified-wire.js';
 import { ToolResultGuard } from './tool-result-guard.js';
+import { type PlacedDrop } from './thinking-drops.js';
+import { type SentRow } from './sent-rows.js';
 import { type RequestOnlyPrompt, type SilentHeartbeatTick } from './silent-heartbeat.js';
 import { type ResolvedClockConfig } from './clock-rows.js';
 export interface ActivationRequestOptions {
@@ -9,13 +11,46 @@ export interface ActivationRequestOptions {
     /** A request that will never be sent (a preview): compile it as a dry
      *  run (see `compileWithInjections` for what that leaves alone). */
     dryRun?: boolean;
+    /** Messages added to the compile's: a preview's stand-in for the context
+     *  injections a start would store before its compile
+     *  (stored-injections.ts), put where that compile would render them, as
+     *  the window's newest rows. A preview stores nothing, so the compile
+     *  doesn't weigh them against the budget or shape them as it would the
+     *  stored rows. */
+    appendedMessages?: NormalizedMessage[];
+    /** `false`: the caller retries this stream's failures itself, so membrane
+     *  sends a failed round once and hands the error up. The framework's turns
+     *  pass it (its errorPolicy is their retry layer); a direct caller of
+     *  startStream keeps membrane's retries. */
+    membraneRetries?: boolean;
+}
+/** A compile's render stats, as context-manager's `getRenderStats()` types
+ *  them; each compile carries its own, where the strategy records them, in
+ *  `CompileResult.renderStats`. */
+export type RenderStats = NonNullable<ReturnType<ContextManager['getRenderStats']>>;
+/** The render stats of the dry compile that built `request`, or null: see
+ *  `AgentFramework.getRequestCompileStats`. */
+export declare function dryCompileStatsOf(request: object): RenderStats | null;
+/**
+ * What a compile is told when the agent's model binds its thinking: `compile()`'s options for a context manager
+ * that keeps a thinking-binding record, as agent-framework holds the binding (with the participant whose messages
+ * are the agent's own replies) and as digests of the request's head (bindingCompileOptions).
+ */
+export interface BindingCompileOptions {
+    thinkingBinding?: {
+        binds: boolean;
+        dropBlock: boolean;
+        participant: string;
+    };
+    identity?: RequestIdentity;
 }
 export interface StartStreamResult {
     stream: YieldingStream;
     request: NormalizedRequest;
     /** The request-only `[Continue]` prompt this request's reply follows, if
      *  any, read from the request: a new one when it ends on `[Continue]`;
-     *  else, when it ends on tool results, the prompt of the reply that called
+     *  else, when it ends on tool results, or on tool results and then
+     *  stored context injections alone, the prompt of the reply that called
      *  those tools (`toolLoopPrompt`); else none. The framework stamps the
      *  reply's rows with it (`metadata.promptedBy`), for later compiles to
      *  render it before them. */
@@ -25,21 +60,54 @@ export interface StartStreamResult {
         wireReceipt: CacheWireReceipt;
     } | undefined;
     drainKvSubmissionIds?: () => string[];
+    /** Where each block a call of this stream reports the provider dropped came from: a stored reply this
+     *  request's compile rendered, a round the stream appended, or neither (placeThinkingDrops). Optional, so a
+     *  stand-in for the stream start needn't supply it; without it, no drop can be placed. */
+    placeDrops?: (entries: readonly ThinkingBindingEntry[]) => PlacedDrop[];
+    /** The compile's `thinkingRecordedAfter`, when it gave one: a reply stored at or below it predates the branch's
+     *  thinking-binding record, so the provider may drop its thinking with no strip having missed. */
+    thinkingRecordedAfter?: number;
+    /** The key (`branchKey`) of the branch the compile read, when its provenance names one. */
+    thinkingBranch?: string;
+    /** Tells the context manager what the stream's later rounds carried after the compiled messages, every round so
+     *  far in sent order, with this request's head (context-manager's `noteRequestSent`). Present only where the
+     *  model binds its thinking and the context manager keeps a record it can be told of. */
+    noteRequestSent?: (rows: readonly SentRow[]) => boolean;
+    /** The stored bodies the request's compile carried, by each body's first message id (its provenance's raw bodies).
+     *  Absent when the compile reports no provenance. */
+    carriedBodies?: ReadonlySet<MessageId>;
 }
-import type { ContextManager, TokenBudget, ContextInjection, CompileResult, MessageMetadata } from '@animalabs/context-manager';
+import type { ContextManager, TokenBudget, ContextInjection, CompileResult, MessageId, MessageMetadata, RequestIdentity, ThinkingStrip } from '@animalabs/context-manager';
 import type { AgentConfig, AgentState, SameRoundThinkTextPolicy, SameRoundThinkTextPolicySource, ToolCallId, ToolCall, ToolResult, ToolDefinition, AgentInfo, InferenceResult, InferenceOptions, AgentRuntimeSettingsPatch, AgentRuntimeSettingsSnapshot, AgentRuntimeSettingsOverrides } from './types/index.js';
 /**
  * Refuse an agent config whose `promptCaching`, `toolResultGuard`,
- * `toolWrapperProseGuard`, `thinking.enabled` or `refusalHandling.autoRewind`
- * holds anything but true or false (assertBooleanSetting), or whose `thinking`
- * or `refusalHandling` is anything but an object, null or false
- * (holdsSettings). The constructor runs it first, so the rule holds wherever
- * an Agent is built. `create()` also runs it for each of its agents before
- * anything opens, and `createEphemeralAgent` before it reserves the name, so a
- * refusal there leaves nothing behind. Membrane reads `thinking.enabled`, and
- * the refusal is here because the setting is AgentConfig's.
+ * `toolWrapperProseGuard`, `thinking.enabled`, `thinkingBinding.dropBlock`,
+ * `thinkingBinding.binds` or `refusalHandling.autoRewind` holds anything but true or false
+ * (assertBooleanSetting, where null counts as left out), or whose `thinking`, `thinkingBinding` or
+ * `refusalHandling` is anything but an object, null or false (holdsSettings),
+ * or whose `autoContinue` resolveAutoContinue refuses. The constructor runs it
+ * first, so the rule holds wherever an Agent is built. `create()` also runs it
+ * for each of its agents before anything opens, and `createEphemeralAgent`
+ * before it reserves the name, so a refusal there leaves nothing behind.
+ * Membrane reads `thinking.enabled`, and the refusal is here because the
+ * setting is AgentConfig's.
  */
 export declare function assertAgentSwitches(config: AgentConfig): void;
+/** `AutoContinueConfig.maxConsecutive` when left out. */
+export declare const DEFAULT_AUTO_CONTINUE_MAX = 3;
+/**
+ * `AgentConfig.autoContinue` resolved: undefined when off (left out, null or
+ * false), else its cap. `true` takes the default cap; an object takes
+ * `maxConsecutive`, a whole number from 1 to 20 (the default when left out).
+ * Any other value is refused.
+ */
+export declare function resolveAutoContinue(config: AgentConfig): {
+    maxConsecutive: number;
+} | undefined;
+export declare function branchKey(branch: {
+    readonly id: string;
+    readonly created: number;
+}): string;
 /**
  * An agent wraps a context manager and manages inference state.
  */
@@ -63,6 +131,12 @@ export declare class Agent {
      * blocks are preserved through Chronicle.
      */
     readonly thinking: AgentConfig['thinking'];
+    /** Whether requests ask the provider to drop signed thinking whose earlier
+     *  conversation changed (see AgentConfig.thinkingBinding.dropBlock). */
+    private readonly thinkingDropBlock;
+    /** Whether the model binds its signed thinking to the conversation before
+     *  it (see AgentConfig.thinkingBinding.binds). */
+    private readonly thinkingBinds;
     /** Refusal auto-rewind policy (see AgentConfig.refusalHandling). */
     readonly refusalHandling: AgentConfig['refusalHandling'];
     readonly toolResultGuard: ToolResultGuard;
@@ -70,6 +144,11 @@ export declare class Agent {
     readonly proseRouting: 'locus' | 'explicit' | 'hybrid' | 'disabled';
     /** Exact whole-response known-tool wrapper containment (default off). */
     readonly toolWrapperProseGuard: boolean;
+    /** Continuation after a turn the model ends itself (see
+     *  AgentConfig.autoContinue); undefined when off. */
+    readonly autoContinue: {
+        maxConsecutive: number;
+    } | undefined;
     /** Clock rows' interval and precision (see AgentConfig.clock); undefined
      *  when the agent writes none of its own (a resident still reads those
      *  another resident writes into the shared slot). */
@@ -402,6 +481,48 @@ export declare class Agent {
         branch: string;
         sequence: number;
     } | null;
+    /**
+     * The newest consumed watermark a request carried that was answered: its
+     * round's tool calls, or its completion, came back. A message a boundary
+     * injected counts as heard only once a request carrying it is answered;
+     * the consumed watermark moves when the stream is handed it, before its
+     * request runs, so a request that fails, ending its stream with an error,
+     * leaves this as it was.
+     */
+    private answeredWatermark;
+    getAnsweredWatermark(): {
+        branch: string;
+        sequence: number;
+    } | null;
+    /** A request that carried `watermark` was answered. Requests are answered
+     *  in the order they're sent, and the consumed watermark only advances
+     *  within a branch, so the latest is the newest. */
+    markAnswered(watermark: {
+        branch: string;
+        sequence: number;
+    } | null): void;
+    /**
+     * Per destination (a server's channel, by its key), the newest consumed
+     * watermark the agent had read when it published there by a route the
+     * framework sees (its prose, a sleep's announcement, a channel_publish, a
+     * draft resend, or a send tool whose channel the framework records), on
+     * the branch it was taken on. A wake that carries a channel, unless it's
+     * marked ambient (InferenceRequest.ambient), keeps its turn unless the
+     * agent spoke there after reading the write the wake is for. It
+     * lives as long as this Agent: an agent made again starts it empty, and
+     * such a wake then stays.
+     */
+    private publishedThrough;
+    /** Note a publish into `destination` (its key), made having read through
+     *  `readThrough`: the consumed watermark when its words were written, or
+     *  its call made. */
+    notePublished(destination: string, readThrough: {
+        branch: string;
+        sequence: number;
+    } | null): void;
+    /** Whether the agent published into `destination` (its key) having read
+     *  the row stored at `sequence` on `branch`. */
+    publishedAfterReading(destination: string, branch: string, sequence: number): boolean;
     /** Mark everything currently stored as consumed (the agent's creation, at
      *  boot or later, and a tool boundary that injected messages into a live
      *  stream declaring it carries them; see consumedWatermark). */
@@ -432,14 +553,114 @@ export declare class Agent {
      * reaches here).
      */
     private applyCompileWatermark;
+    /**
+     * The branch now (`branchKey`) and its head, as `pendingWatermark` reads it: a message stored on that branch later
+     * has a larger sequence. Sequences are numbered per branch, so one compares with another only on the same branch.
+     */
+    branchHead(): {
+        branch: string;
+        sequence: number;
+    } | undefined;
     /** The watermark a successful compile will establish (taken before, applied after). */
     private pendingWatermark;
     /** A committing compile, as for a request that is sent: the context
      * manager commits what it commits for one, the consumed watermark moves,
      * and a prepared budget change settles. To inspect what the agent would
      * see, use the framework's `previewActivation`, which compiles as a dry
-     * run. */
+     * run. It isn't told the agent's thinking binding (`thinkingBinding.binds`),
+     * so a context manager that keeps a thinking-binding record neither reads
+     * nor writes the record here, and what it returns keeps thinking whose
+     * earlier conversation changed. */
     compileContext(budget?: TokenBudget): Promise<CompileResult>;
+    /**
+     * The stored context injections of this agent's that the last compile it
+     * built to send rendered (stored-injections.ts), the framework's activation
+     * request's or the direct API's: for each namespace and content, the parts
+     * the compile held, and the branch it read. A compile built to send whose
+     * request then isn't sent (a stop, a failure) still records: its rows stay
+     * in the window all the same. Undefined before the first, as after a
+     * restart. The framework's same-content skip reads it (renderedInjection).
+     */
+    private renderedInjections?;
+    /**
+     * Per branch (by id and created), the point a stored injection on it has
+     * to come after to have been in no request yet (unsentInjection): the
+     * newest row of this agent's window on that branch when the first plan
+     * there since its last compile built to send (a start's, or a preview's,
+     * which stores nothing) asked about a unit, before that plan's start
+     * stored anything. Each compile built to send that records what it
+     * held unsets its branch's, a restart unsets them all, and a plan asks
+     * here before it stores a unit, so every one of this agent's stored
+     * injections on a branch after its point was stored since that compile.
+     * Kept per branch, so a start or preview on another branch doesn't move
+     * this one's past a copy no request has had.
+     */
+    private readonly unsentSince;
+    /**
+     * A host's hook, called with the messages of each compile built to send
+     * (never a dry run), as the compile is recorded: what the request carries,
+     * after compression and the window have done their work. The framework
+     * uses it to tell when an MCPL toolset's announcement has left the context
+     * (RFC-014 §8.3 reminders). It must not change the messages; one that
+     * throws is logged, and the start goes on.
+     */
+    onCompiledToSend?: (messages: readonly unknown[]) => void;
+    /**
+     * A host's hook, called with each committing compile's `thinkingStrip` (never a dry run's) and the key of the
+     * branch it read (`branchKey`), as the compile returns, whether or not its request is then sent, since the
+     * context manager's binding record takes the strip either way. One that throws is logged. The framework sets it
+     * at the agent's first stream unless a host has set one, so a host's own observer stands in for the framework's,
+     * whose `[reasoning]` line for the agent then isn't told.
+     */
+    onThinkingStrip?: (strip: ThinkingStrip, branch: string) => void;
+    /**
+     * The newest content of `namespace` among this agent's rows stored since
+     * its last compile built to send (unsentSince), and whether every part of
+     * it is among them: rows a start stored whose compile then didn't record
+     * (it threw, or the start failed before it), which no request has had
+     * yet, and which are newer than anything renderedInjection knows. Undefined when there are none, as at every
+     * start whose last compile was built and recorded. A fold between that
+     * start and the next (a host's own committing compile, or the compression
+     * an over-budget retry waits for) can summarize them all the same: the
+     * next request then has the summary's word for them, and the start after
+     * it stores them again, as after any fold. The window is read back 64
+     * rows at a time from the newest, stopping at that point.
+     */
+    unsentInjection(namespace: string): {
+        contentHash: string;
+        whole: boolean;
+    } | undefined;
+    /** Record which of this agent's stored injections a compile built to send
+     *  rendered. Another agent's stored rows never reach this agent's compile,
+     *  since every compile of a shared store leaves them out by its view
+     *  filter (isAnotherAgentsInjection): a compile of a shared store without
+     *  that filter would mix them in here. */
+    private noteRenderedInjections;
+    /**
+     * The newest content of `namespace` among this agent's stored injections
+     * that the last compile built to send rendered, by its newest copy: its
+     * content hash, and whether every part of that content was there in some
+     * copy, every shard, however the strategy shaped it. Undefined when none
+     * was, when this agent hasn't built a request since it started, or when
+     * the window's branch has changed since.
+     */
+    renderedInjection(namespace: string): {
+        contentHash: string;
+        whole: boolean;
+    } | undefined;
+    /**
+     * Whether compiled message `i` of `result` is a row of this agent's stored
+     * context injections (stored-injections.ts): rendered as an injection's
+     * participant, and each of its stored rows, by the compile's provenance,
+     * carrying this agent's mark. A speaker merely named like an injection's
+     * participant isn't one. Only such a message's rows are read, so a start
+     * reads the store for those alone.
+     */
+    private isStoredInjectionRow;
+    /** A stored row's injection mark, or undefined for any other row, and for
+     *  one the store can't read just now, which is logged: a start doesn't fail
+     *  on it (the row then counts as no stored injection). */
+    private storedMarkOf;
     /**
      * Compile the context with injections (e.g. from MCPL servers), which the
      * context manager merges into the compiled messages. Without
@@ -451,15 +672,23 @@ export declare class Agent {
     compileWithInjections(budget?: TokenBudget, injections?: ContextInjection[], opts?: {
         kvUnifiedImmutablePrefixHash?: string;
         dryRun?: boolean;
-    }): Promise<CompileResult>;
+    } & BindingCompileOptions): Promise<CompileResult>;
     /**
      * Run inference and return result with tool calls and speech content.
-     * Updates agent state during execution.
+     * Updates agent state during execution. Its compile commits. With
+     * `thinkingBinding.binds` it also writes the context manager's
+     * thinking-binding record, so then call it only while none of this agent's
+     * requests is streaming: a stream open meanwhile then has its later notes
+     * write nothing, and its replies go without their thinking at the next
+     * compile. Its own reply is never noted, so with `binds` its thinking is
+     * left out at the compile after it's stored.
      */
     runInference(availableTools: ToolDefinition[], budget?: TokenBudget, options?: InferenceOptions): Promise<InferenceResult>;
     /**
      * Run inference with context injections.
-     * Same as runInference but passes injections through to compile.
+     * Same as runInference but passes injections through to compile. Its
+     * compile commits, and with `thinkingBinding.binds` writes the
+     * thinking-binding record, as runInference's does (see there).
      */
     runInferenceWithInjections(availableTools: ToolDefinition[], injections?: ContextInjection[], budget?: TokenBudget, options?: InferenceOptions): Promise<InferenceResult>;
     /**
@@ -486,7 +715,10 @@ export declare class Agent {
      * watermark); a preview passes `options.dryRun`, so its compile commits
      * none of that (see `compileWithInjections` for what a dry run still
      * leaves). Either way the context manager is handed the compression tool
-     * definitions. Safe to call regardless of the agent's current status.
+     * definitions. Safe to call regardless of the agent's current status,
+     * except that with `thinkingBinding.binds` a compile that isn't a dry run
+     * writes the context manager's binding record, so while one of the
+     * agent's requests streams, a call to look passes `options.dryRun`.
      * It doesn't wait for the tool-result guard's annotations, so a preview
      * never waits on a workspace write (rollback, undo and redo report one), and
      * may show a withheld stub before its place is added; the activation waits
@@ -495,13 +727,47 @@ export declare class Agent {
     private assembleActivationRequest;
     /**
      * The request fields that come from this agent's own settings: its model
-     * config, prompt caching and cache TTL, prefill message, provider
-     * parameters and participant name. Every request the agent sends takes
-     * them from here, a framework turn's (assembleActivationRequest) and the
-     * direct API's (runInferenceWithInjections), so a setting reaches both or
-     * neither.
+     * config, thinking binding, prompt caching and cache TTL, prefill message,
+     * provider parameters and participant name. Every request the agent sends
+     * takes them from here, a framework turn's (assembleActivationRequest) and
+     * the direct API's (runInferenceWithInjections), so a setting reaches both
+     * or neither.
      */
     private requestSettings;
+    /**
+     * The thinking config a request carries: the agent's own, with the binding
+     * control added when `thinkingBinding.dropBlock` asks for it. A model whose
+     * thinking is always on takes the control whatever `enabled` says, so an
+     * agent with no thinking config of its own still sends one, holding only
+     * the control and `enabled: false`. Membrane sends nothing from it to any
+     * other model, since thinking is off there.
+     */
+    private requestThinking;
+    /** The stream's way to tell the context manager what its later rounds sent, with the head its compile was given:
+     *  where the agent's model binds its thinking (context-manager's `noteRequestSent`). */
+    private requestNotes;
+    /**
+     * The binding a compile of this agent is told of (bindingCompileOptions), and a preview of its context too: the
+     * participant whose messages are its replies is its own name. Undefined where the model doesn't bind.
+     * @internal For the framework's preview and its budget rule; not a host API.
+     */
+    thinkingBindingOption(): {
+        binds: true;
+        dropBlock: boolean;
+        participant: string;
+    } | undefined;
+    /**
+     * What a compile the agent sends tells the context manager when the model binds its thinking
+     * (`thinkingBinding.binds`): the binding as set, with the agent's own name as the participant whose messages
+     * are its replies (an agent stores its replies under its name), and a digest of each part of the request ahead of
+     * its messages, so a changed one can stand for a first difference where the context manager keeps a
+     * thinking-binding record. The system text is the one the request will carry, built from the system-position
+     * injections given to the compile as the kv-unified prefix hash builds it; the tools are the ones it will carry, in
+     * their order; `request` covers the thinking config, `maxTokens` and `providerParams`, where a host puts its own
+     * thinking config and `tool_choice`, and `prefillUserMessage`, which membrane sends as a leading user turn ahead
+     * of a conversation that would begin with the assistant. Nothing without `binds`: the compile is as it was.
+     */
+    private bindingCompileOptions;
     /** The request `assembleActivationRequest` builds (see there), for preview
      * and debug tooling: what this agent's next activation would send. */
     buildActivationRequest(availableTools: ToolDefinition[], injections?: ContextInjection[], budget?: TokenBudget, compressionTools?: ToolDefinition[], options?: ActivationRequestOptions): Promise<NormalizedRequest>;
@@ -530,7 +796,7 @@ export declare class Agent {
      * Add an assistant response to context.
      * Called by framework when stream completes.
      */
-    addAssistantResponse(content: ContentBlock[], metadata?: MessageMetadata): void;
+    addAssistantResponse(content: ContentBlock[], metadata?: MessageMetadata): MessageId | undefined;
     /**
      * Transition back to streaming state after tool results are provided.
      */
@@ -558,7 +824,9 @@ export declare class Agent {
      * one is still ahead; otherwise the next start drops it. `reason` is
      * provenance for the framework's inference:aborted trace and marker
      * metadata (e.g. 'zombie_reclaim', 'subagent_cancel'); it never reaches
-     * the provider.
+     * the provider. When the stream's cancel() throws, the throw goes on to
+     * the caller, and the agent still holds the stream, its cancel record as
+     * it was before the call.
      */
     cancelStream(reason?: string): void;
     /** Collect (and clear) the cancelStream() made while this agent held no