@animalabs/agent-framework 0.26.2 → 0.27.0

package/dist/src/agent.js

@@ -1,38 +1,56 @@
 import { isAbortedResponse } from '@animalabs/membrane';
-import { createHash } from 'node:crypto';
 import { ToolResultGuard } from './tool-result-guard.js';
 import { withoutTokenEstimates } from './thinking-token-stamp.js';
+import { placeThinkingDrops } from './thinking-drops.js';
+import { carriedBlock } from './sent-rows.js';
 import { injectionsAsStored } from './text-as-stored.js';
-import { assertBooleanSetting, holdsSettings } from './config-checks.js';
+import { stableHash } from './stable-hash.js';
+import { hasRenderedContent, storedInjectionMarkOf } from './stored-injections.js';
+import { assertBooleanSetting, holdsSettings, kindOf } from './config-checks.js';
 import { CONTINUE_ROW, continueTurn, indexRequestOnlyRows, renderRequestOnlyRows, silentHeartbeatSeparatorTurn, tickKey, toolLoopPrompt, } from './silent-heartbeat.js';
 import { randomUUID } from 'node:crypto';
 import { resolveClockConfig } from './clock-rows.js';
 import { nonErrorResultText, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
-function stableHash(value) {
-    const encode = (item) => {
-        if (Array.isArray(item))
-            return `[${item.map(encode).join(',')}]`;
-        if (item && typeof item === 'object') {
-            const record = item;
-            return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${encode(record[key])}`).join(',')}}`;
-        }
-        return JSON.stringify(item) ?? 'null';
-    };
-    return createHash('sha256').update(encode(value)).digest('hex');
+/** The render stats of the dry compile behind each request a dry run
+ *  assembled (`assembleActivationRequest` with `dryRun`), by that request.
+ *  A request that is sent has none here. Read through the framework's
+ *  `getRequestCompileStats`. */
+const dryCompileStats = new WeakMap();
+/** The render stats of the dry compile that built `request`, or null: see
+ *  `AgentFramework.getRequestCompileStats`. */
+export function dryCompileStatsOf(request) {
+    return dryCompileStats.get(request) ?? null;
+}
+/**
+ * Whether a request's messages, as sanitized, end on `agentName`'s own
+ * message, apart from `injectionTail` stored context injections after it
+ * (counted over the messages the sanitizer keeps).
+ */
+function endsOnOwnMessage(messages, agentName, injectionTail) {
+    const own = messages[messages.length - 1 - injectionTail];
+    return own !== undefined && own.participant === agentName
+        && messages.slice(messages.length - injectionTail).every((m) => m.participant.startsWith('system_context:'));
+}
+/** A digest of a value as a request's JSON carries it (a field whose value is undefined left out, as the wire leaves
+ *  it out), key order aside: the head digests the thinking binding compares, so a change on the wire changes one. */
+function wireDigest(value) {
+    return stableHash(JSON.parse(JSON.stringify(value) ?? 'null'));
 }
 const DEFAULT_CONTEXT_BUDGET_TOKENS = 100_000;
 const DEFAULT_TRANSITION_PACE_TOKENS = 16_000;
 const DEFAULT_SAME_ROUND_THINK_TEXT_POLICY = 'public';
 /**
  * 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 function assertAgentSwitches(config) {
     const agent = `Agent "${config.name}"`;
@@ -40,6 +58,12 @@ export function assertAgentSwitches(config) {
     if (holdsSettings(`${agent} thinking`, config.thinking, '{ enabled: true }')) {
         assertBooleanSetting(`${agent} thinking.enabled`, config.thinking.enabled, 'true asks the provider for extended thinking, and false or leaving it out doesn\'t');
     }
+    if (holdsSettings(`${agent} thinkingBinding`, config.thinkingBinding, '{ binds: true, dropBlock: true }')) {
+        assertBooleanSetting(`${agent} thinkingBinding.dropBlock`, config.thinkingBinding.dropBlock, 'true asks the provider to drop a signed thinking block whose earlier conversation changed rather than refuse the request, ' +
+            'and false or leaving it out sends nothing, so the account\'s default applies');
+        assertBooleanSetting(`${agent} thinkingBinding.binds`, config.thinkingBinding.binds, 'true says the model binds its signed thinking to the conversation before it, so each compile tells the context manager so, ' +
+            'and false or leaving it out compiles as before');
+    }
     if (holdsSettings(`${agent} refusalHandling`, config.refusalHandling, '{ autoRewind: true }')) {
         assertBooleanSetting(`${agent} refusalHandling.autoRewind`, config.refusalHandling.autoRewind, 'true redacts the turn that tripped a refusal and runs again, up to maxRewinds times, ' +
             'and false or leaving it out doesn\'t');
@@ -48,6 +72,46 @@ export function assertAgentSwitches(config) {
         'and false or leaving it out doesn\'t');
     assertBooleanSetting(`${agent} toolWrapperProseGuard`, config.toolWrapperProseGuard, 'true keeps a response whose whole prose is a tool-call-shaped wrapper from running or entering the agent\'s history, ' +
         'and false or leaving it out doesn\'t');
+    resolveAutoContinue(config);
+}
+/** `AutoContinueConfig.maxConsecutive` when left out. */
+export const DEFAULT_AUTO_CONTINUE_MAX = 3;
+/** The most continuations in a row a config may ask for. */
+const MAX_AUTO_CONTINUE_MAX = 20;
+/**
+ * `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 function resolveAutoContinue(config) {
+    const setting = `Agent "${config.name}" autoContinue`;
+    const value = config.autoContinue;
+    if (value === true)
+        return { maxConsecutive: DEFAULT_AUTO_CONTINUE_MAX };
+    if (value !== undefined && value !== null && value !== false && (typeof value !== 'object' || Array.isArray(value))) {
+        throw new Error(`${setting} must be true, false or an object such as { maxConsecutive: 3 }, not ${kindOf(value)}` +
+            (typeof value === 'string' ? ' (true and false go unquoted)' : ''));
+    }
+    if (!holdsSettings(setting, value, '{ maxConsecutive: 3 }'))
+        return undefined;
+    const max = value.maxConsecutive;
+    if (max === undefined)
+        return { maxConsecutive: DEFAULT_AUTO_CONTINUE_MAX };
+    if (typeof max !== 'number' || !Number.isInteger(max) || max < 1 || max > MAX_AUTO_CONTINUE_MAX) {
+        // The value's kind, never the value (config-checks): a `${VAR}` that
+        // lands here could be a credential.
+        const kind = typeof max !== 'number' ? kindOf(max)
+            : !Number.isInteger(max) ? 'a number that isn\'t whole'
+                : max < 1 ? 'a number below 1' : `a number above ${MAX_AUTO_CONTINUE_MAX}`;
+        throw new Error(`${setting}.maxConsecutive must be a whole number from 1 to ${MAX_AUTO_CONTINUE_MAX}, not ${kind}: ` +
+            'the most turns in a row that continue without skip_reply before the agent waits for the next event');
+    }
+    return { maxConsecutive: max };
+}
+/** A branch's key in Agent.unsentSince: its id and when it was created. */
+function branchKey(branch) {
+    return `${branch.id}\u0000${branch.created}`;
 }
 /**
  * An agent wraps a context manager and manages inference state.
@@ -72,6 +136,12 @@ export class Agent {
      * blocks are preserved through Chronicle.
      */
     thinking;
+    /** Whether requests ask the provider to drop signed thinking whose earlier
+     *  conversation changed (see AgentConfig.thinkingBinding.dropBlock). */
+    thinkingDropBlock;
+    /** Whether the model binds its signed thinking to the conversation before
+     *  it (see AgentConfig.thinkingBinding.binds). */
+    thinkingBinds;
     /** Refusal auto-rewind policy (see AgentConfig.refusalHandling). */
     refusalHandling;
     toolResultGuard;
@@ -79,6 +149,9 @@ export class Agent {
     proseRouting;
     /** Exact whole-response known-tool wrapper containment (default off). */
     toolWrapperProseGuard;
+    /** Continuation after a turn the model ends itself (see
+     *  AgentConfig.autoContinue); undefined when off. */
+    autoContinue;
     /** 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). */
@@ -202,10 +275,13 @@ export class Agent {
         this.maxTokens = config.maxTokens ?? 4096;
         this.temperature = config.temperature;
         this.thinking = config.thinking;
+        this.thinkingDropBlock = config.thinkingBinding?.dropBlock === true;
+        this.thinkingBinds = config.thinkingBinding?.binds === true;
         this.refusalHandling = config.refusalHandling;
         this.toolResultGuard = new ToolResultGuard(config.name, contextManager, config.toolResultGuard === true);
         this.proseRouting = config.proseRouting ?? 'locus';
         this.toolWrapperProseGuard = config.toolWrapperProseGuard === true;
+        this.autoContinue = resolveAutoContinue(config);
         this.clock = resolveClockConfig(config.name, config.clock);
         this.cacheTtl = config.cacheTtl ?? '1h';
         this.promptCaching = config.promptCaching !== false;
@@ -213,7 +289,12 @@ export class Agent {
         this.providerParams = config.providerParams;
         this.sameRoundThinkTextPolicy = config.sameRoundThinkTextPolicy;
         this.maxStreamTokens = config.maxStreamTokens ?? 150_000;
-        this.physicalWindowTokens = config.physicalWindowTokens;
+        // The window size converted as the projection's comparison (`projected > window`) converts it, so a string such
+        // as "200000" from a JSON or YAML config is its number, for every rule that reads it. A value whose number isn't
+        // finite is no window: null, NaN and Infinity, which the comparison never passed, and -Infinity, which it always
+        // did, a restart at every boundary.
+        const window = config.physicalWindowTokens == null ? NaN : Number(config.physicalWindowTokens);
+        this.physicalWindowTokens = Number.isFinite(window) ? window : undefined;
         this.contextBudgetTokens = config.contextBudgetTokens;
         this.configuredContextBudgetTokens = config.contextBudgetTokens;
         this.contextManager = contextManager;
@@ -845,6 +926,54 @@ export class Agent {
     getShownWatermark() {
         return this.shownWatermark;
     }
+    /**
+     * 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.
+     */
+    answeredWatermark = null;
+    getAnsweredWatermark() {
+        return this.answeredWatermark;
+    }
+    /** 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) {
+        if (watermark)
+            this.answeredWatermark = watermark;
+    }
+    /**
+     * 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.
+     */
+    publishedThrough = new Map();
+    /** 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, readThrough) {
+        if (!readThrough)
+            return;
+        const noted = this.publishedThrough.get(destination);
+        if (noted && noted.branch === readThrough.branch && noted.sequence >= readThrough.sequence)
+            return;
+        this.publishedThrough.set(destination, readThrough);
+    }
+    /** Whether the agent published into `destination` (its key) having read
+     *  the row stored at `sequence` on `branch`. */
+    publishedAfterReading(destination, branch, sequence) {
+        const noted = this.publishedThrough.get(destination);
+        return !!noted && noted.branch === branch && noted.sequence >= sequence;
+    }
     /** 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). */
@@ -852,7 +981,8 @@ export class Agent {
         // Tolerates partial context-manager doubles (tests build Agents over
         // stubs). Without a watermark, a reader that looks for one takes its own
         // side: the coalescer counts the message as read, and the framework's
-        // deferredWriteReadOrGone and unreadNoticesForPrimary count it as unread.
+        // unreadNoticesForPrimary counts it as unread. A deferred write's wake
+        // reads the answered watermark instead (deferredWriteDone).
         this.consumedWatermark = this.pendingWatermark();
         this.watermarkMarks++;
         this.shownWatermark = this.consumedWatermark;
@@ -920,7 +1050,10 @@ export class Agent {
      * 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. */
     async compileContext(budget) {
         // RFC-006 §3.3: consumption is determined at assembly — a compile that
         // fails assembled nothing, so the watermark moves only on success.
@@ -942,6 +1075,203 @@ export class Agent {
             this.applyCompileWatermark(watermark, marksBefore);
         return result;
     }
+    /**
+     * 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).
+     */
+    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.
+     */
+    unsentSince = new Map();
+    /**
+     * 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;
+    /**
+     * 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) {
+        let newest;
+        try {
+            const branch = branchKey(this.contextManager.currentBranchRef());
+            const since = this.unsentSince.get(branch);
+            if (since === undefined) {
+                const count = this.contextManager.getMessageCount();
+                const top = count > 0 ? this.contextManager.getMessageWindow(count - 1, 1, { resolveBlobs: false }).messages[0]?.sequence ?? 0 : 0;
+                this.unsentSince.set(branch, top);
+                return undefined;
+            }
+            scan: for (let end = this.contextManager.getMessageCount(); end > 0;) {
+                const span = Math.min(end, 64);
+                const { messages } = this.contextManager.getMessageWindow(end - span, span, { resolveBlobs: false });
+                for (let i = messages.length - 1; i >= 0; i--) {
+                    const row = messages[i];
+                    if (row.sequence <= since)
+                        break scan;
+                    const mark = storedInjectionMarkOf(row.metadata);
+                    if (mark?.agent !== this.name || mark.namespace !== namespace)
+                        continue;
+                    // Read from the newest back, the first copy met is the newest
+                    // content; its other parts pool with it.
+                    newest ??= { contentHash: mark.contentHash, parts: mark.parts, held: new Set() };
+                    if (mark.contentHash === newest.contentHash)
+                        newest.held.add(mark.part);
+                }
+                end -= span;
+            }
+        }
+        catch (err) {
+            // Where the rows read before the failure held a copy, the newest of
+            // them is still the newest content (any unread row is older), and a
+            // part it lacks may be unread, so it's stored again at worst. Where
+            // they held none, the last request's record decides, as it did before
+            // this check: a copy a failed start stored is then stored again, or,
+            // where the source has changed back to what that request held, left
+            // newest for one more request. Either way the start goes on, where
+            // failing here would lose its turn.
+            console.error(`[injection] ${this.name}: could not read its window for copies stored since its last request, so ${newest ? 'the rows it read decide' : "that request's record decides"}:`, err);
+            if (!newest)
+                return undefined;
+        }
+        return newest && { contentHash: newest.contentHash, whole: newest.held.size === newest.parts };
+    }
+    /** 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. */
+    noteRenderedInjections(result) {
+        // The host's look at what this request carries (onCompiledToSend).
+        if (this.onCompiledToSend) {
+            try {
+                this.onCompiledToSend(result.messages);
+            }
+            catch (err) {
+                console.error(`[agent] ${this.name}: the host's compile observer failed:`, err);
+            }
+        }
+        const provenance = result.provenance;
+        // The rows stored before this compile on its branch have been compiled
+        // to send, whether the request held them or a fold or the strategy's
+        // window took them (the record below says which): the first plan there
+        // after it, a start's or a preview's, sets the point again
+        // (unsentInjection). Without provenance, which branch isn't known, so
+        // every branch's point goes, rather than one surviving a compile that
+        // held its rows.
+        if (provenance)
+            this.unsentSince.delete(branchKey(provenance.branch));
+        else
+            this.unsentSince.clear();
+        if (!provenance) {
+            this.renderedInjections = undefined;
+            return;
+        }
+        const byNamespace = new Map();
+        for (const [i, source] of provenance.messages.entries()) {
+            // Only a message rendered as an injection's participant can be one, so
+            // the store is read for those alone.
+            if (source.kind !== 'raw' || !result.messages[i]?.participant.startsWith('system_context:'))
+                continue;
+            for (const body of source.bodies) {
+                const mark = this.storedMarkOf(body.messageId);
+                if (!mark)
+                    continue;
+                // A part counts as held when all its shards are there. One the
+                // strategy altered (cut at its per-message cap, an image stripped)
+                // counts too: a new copy would meet the same, so storing again
+                // would only add copies, every start. A part missing shards still
+                // says which content is newest.
+                const held = body.complete || (body.missing !== undefined && !body.missing.includes('shards'));
+                const contents = byNamespace.get(mark.namespace) ?? new Map();
+                byNamespace.set(mark.namespace, contents);
+                // Copies of the same content in view pool what they hold: the agent
+                // has each part that one of them holds.
+                const known = contents.get(mark.contentHash) ?? { parts: mark.parts, held: new Set(), sequence: body.sequence };
+                if (held)
+                    known.held.add(mark.part);
+                known.sequence = Math.max(known.sequence, body.sequence);
+                contents.set(mark.contentHash, known);
+            }
+        }
+        this.renderedInjections = { branch: provenance.branch, byNamespace };
+    }
+    /**
+     * 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) {
+        const rendered = this.renderedInjections;
+        const branch = this.contextManager.currentBranchRef();
+        if (!rendered || rendered.branch.id !== branch.id || rendered.branch.created !== branch.created)
+            return undefined;
+        let newest;
+        for (const entry of rendered.byNamespace.get(namespace) ?? []) {
+            if (!newest || entry[1].sequence > newest[1].sequence)
+                newest = entry;
+        }
+        return newest ? { contentHash: newest[0], whole: newest[1].held.size === newest[1].parts } : 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.
+     */
+    isStoredInjectionRow(result, i) {
+        const source = result.provenance?.messages[i];
+        return source?.kind === 'raw' && source.bodies.length > 0
+            && !!result.messages[i]?.participant.startsWith('system_context:')
+            && source.bodies.every((b) => this.storedMarkOf(b.messageId)?.agent === this.name);
+    }
+    /** 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). */
+    storedMarkOf(id) {
+        try {
+            return storedInjectionMarkOf(this.contextManager.getMessage(id)?.metadata);
+        }
+        catch (err) {
+            console.error(`[injection] ${this.name}: could not read stored row ${id}, so it counts as no stored injection:`, err);
+            return undefined;
+        }
+    }
     /**
      * Compile the context with injections (e.g. from MCPL servers), which the
      * context manager merges into the compiled messages. Without
@@ -953,9 +1283,8 @@ export class Agent {
     async compileWithInjections(budget, injections, opts) {
         // A dry run is a compile that will never be sent. The context manager
         // persists no fold resolutions for it and queues none of the compression
-        // or merge work its fold plan calls for. Its thinking binding
-        // (context-manager#160, not yet released) will commit stamps and add a
-        // compile awaiting acceptance for a committing compile only. Here nothing
+        // or merge work its fold plan calls for, and, with the thinking binding
+        // (`thinkingBinding.binds`), writes no binding record. Here nothing
         // moves either: the agent never read what a dry run assembled, so the
         // consumed watermark stays. A dry run proves nothing about the budget
         // either, so it goes straight to the compile, around
@@ -997,14 +1326,22 @@ export class Agent {
     // ==========================================================================
     /**
      * 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.
      */
     async runInference(availableTools, budget, options = {}) {
         return this.runInferenceWithInjections(availableTools, undefined, budget, options);
     }
     /**
      * 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).
      */
     async runInferenceWithInjections(availableTools, injections, budget, options) {
         if (this._state.status === 'inferring') {
@@ -1037,8 +1374,13 @@ export class Agent {
         // been retried; one whose store still fails is compiled as the bare
         // notice.
         let unguardedResults;
+        const binding = this.bindingCompileOptions(tools, (injections ?? [])
+            .filter((injection) => injection.position === 'system')
+            .flatMap((injection) => injection.content));
         const assemble = async () => {
-            const compiled = await this.toolResultGuard.afterAnnotations(() => this.compileWithInjections(budget, injections));
+            const compiled = await this.toolResultGuard.afterAnnotations(() => this.compileWithInjections(budget, injections, binding.thinkingBinding ? binding : undefined));
+            // What it holds of the stored injections is what the agent last saw.
+            this.noteRenderedInjections(compiled);
             const { systemInjections } = compiled;
             // The framework's own pricing stamp never goes out (thinking-token-stamp.ts).
             const messages = withoutTokenEstimates(compiled.messages);
@@ -1154,7 +1496,10 @@ export 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
@@ -1185,12 +1530,63 @@ export class Agent {
                 system: this.buildSystemPrompt(prospectiveSystemInjections),
             })
             : undefined;
-        let { messages, systemInjections } = await this.compileWithInjections(budget, injections, immutablePrefixHash || options.dryRun
+        const binding = this.bindingCompileOptions(availableTools, prospectiveSystemInjections);
+        const compiledResult = await this.compileWithInjections(budget, injections, immutablePrefixHash || options.dryRun || binding.thinkingBinding
             ? {
                 ...(immutablePrefixHash ? { kvUnifiedImmutablePrefixHash: immutablePrefixHash } : {}),
                 ...(options.dryRun ? { dryRun: true } : {}),
+                ...binding,
             }
             : undefined);
+        let { messages } = compiledResult;
+        const { systemInjections } = compiledResult;
+        // It counts what the compile selected, so a preview's stand-ins
+        // (appendedMessages, below) aren't in it.
+        const { renderStats } = compiledResult;
+        // What the request is built from, as the compile returned it: a block the provider drops is found again in
+        // it, through the copies below, by its signature (placeThinkingDrops).
+        const recordedAfter = compiledResult.thinkingRecordedAfter;
+        const compiled = {
+            messages: compiledResult.messages,
+            ...(compiledResult.provenance ? { provenance: compiledResult.provenance } : {}),
+            ...(recordedAfter !== undefined ? { recordedAfter } : {}),
+        };
+        // Each message's place in the compile, or a preview's stand-in (null),
+        // for the count of stored rows the request ends on, below.
+        let origin = messages.map((_, i) => i);
+        // A request that's sent says which stored injections the agent now has in
+        // view, which the next start's same-content skip reads (stored-injections.ts).
+        if (!options.dryRun)
+            this.noteRenderedInjections(compiledResult);
+        const appended = options.appendedMessages ?? [];
+        if (appended.length > 0) {
+            // Where a start's compile would render them, as the window's newest
+            // rows: last, unless the window has no user message, where the compile
+            // places the injections it's given at the end, after the window.
+            const sources = compiledResult.provenance?.messages;
+            let at = messages.length;
+            if (sources && !messages.some((m, i) => sources[i]?.kind !== 'injection' && m.participant.toLowerCase() === 'user')) {
+                while (at > 0 && sources[at - 1]?.kind === 'injection')
+                    at--;
+            }
+            origin = [...origin.slice(0, at), ...appended.map(() => null), ...origin.slice(at)];
+            messages = [...messages.slice(0, at), ...appended, ...messages.slice(at)];
+        }
+        // The stored context injections the request ends on, counted over the
+        // messages the sanitizer below keeps (hasRenderedContent), since it drops
+        // a message it leaves empty, a placed blank injection among them.
+        // [Continue] goes after them, and a tool loop's prompt is read from
+        // before them: they're context, not what woke the agent. An injection
+        // compile() places ends the tail, as on main, where every one was placed.
+        let injectionTail = 0;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (!hasRenderedContent(messages[i].content))
+                continue;
+            const from = origin[i] ?? null;
+            if (from !== null && !this.isStoredInjectionRow(compiledResult, from))
+                break;
+            injectionTail++;
+        }
         // Sanitize: strip empty/whitespace text blocks and drop messages left with
         // no content. The Anthropic API rejects empty text blocks with 400
         // "messages: text content blocks must be non-empty"; when such a block
@@ -1202,14 +1598,10 @@ export class Agent {
         // 2026-07-10 on a resident agent: one empty block muted the agent's live
         // path entirely; twin of context-manager's stripEmptyTextBlocks on the
         // compression path.)
+        // The same pass a tool boundary applies to what it notes as sent
+        // (sent-rows.ts), so the two can't drift.
         messages = messages
-            .map((m) => ({
-            ...m,
-            content: m.content.filter(
-            // typeof guard is deliberate runtime defense: history loaded from
-            // disk can carry a non-string `text` despite what the types claim.
-            (b) => !(b.type === "text" && (typeof b.text !== "string" || b.text.trim() === ""))),
-        }))
+            .map((m) => ({ ...m, content: m.content.filter(carriedBlock) }))
             .filter((m) => m.content.length > 0);
         // The framework's own pricing stamp never goes out (thinking-token-stamp.ts).
         messages = withoutTokenEstimates(messages);
@@ -1233,23 +1625,31 @@ export class Agent {
             && !rendered.separatedTicks.has(tickKey(options.silentHeartbeat));
         // The [Continue] prompt this request's reply follows, read from the
         // request itself: a new one when it ends on [Continue]; else, when it
-        // ends on tool results, the prompt of the reply that called those tools,
-        // whose tool loop this reply continues; else none. A request that ends
+        // ends on tool results (apart from stored context injections after
+        // them), the prompt of the reply that called those tools, whose tool
+        // loop this reply continues; else none. A request that ends
         // on anything else (a message that arrived during a cooldown, say) gets
         // a reply that follows that message and carries no prompt.
         let continuePrompt;
         if (openingTick) {
             messages = [...messages, silentHeartbeatSeparatorTurn()];
         }
-        else if (messages.length > 0 && messages[messages.length - 1].participant === this.name) {
+        else if (endsOnOwnMessage(messages, this.name, injectionTail)) {
             // Safety: ensure messages don't end with an assistant message.
             // Some models reject trailing assistant messages ("prefill not supported"),
             // and after context compression a stale assistant turn can end up last.
+            // Where stored context injections follow the agent's message, as a
+            // changed one does on a wake with nothing new, [Continue] goes after
+            // them, so the cue stays last: the block isn't taken for what woke
+            // the agent. Its reply's promptedBy puts it there in later compiles too,
+            // where they can recognise the reply (renderRequestOnlyRows).
             messages = [...messages, continueTurn()];
             continuePrompt = { turn: randomUUID(), text: CONTINUE_ROW };
         }
         else {
-            continuePrompt = toolLoopPrompt(messages.at(-1), index);
+            // What the request ends on apart from the stored injections after it,
+            // which aren't something the reply answers.
+            continuePrompt = toolLoopPrompt(messages.at(-1 - injectionTail), index);
         }
         const request = {
             messages: this.toolResultGuard.prepareRequest(messages),
@@ -1258,23 +1658,26 @@ export class Agent {
             ...this.requestSettings(),
             ...(kvUnified ? { cacheMarkers: 'cm-owned' } : {}),
         };
-        return { request, ...(continuePrompt ? { continuePrompt } : {}) };
+        if (options.dryRun)
+            dryCompileStats.set(request, renderStats);
+        return { request, ...(continuePrompt ? { continuePrompt } : {}), compiled, binding };
     }
     /**
      * 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.
      */
     requestSettings() {
+        const thinking = this.requestThinking();
         return {
             config: {
                 model: this.model,
                 maxTokens: this.maxTokens,
                 ...(this.temperature !== undefined && { temperature: this.temperature }),
-                ...(this.thinking !== undefined && { thinking: this.thinking }),
+                ...(thinking !== undefined && { thinking }),
             },
             promptCaching: this.promptCaching,
             cacheTtl: this.cacheTtl,
@@ -1283,6 +1686,70 @@ export class Agent {
             assistantParticipant: this.name,
         };
     }
+    /**
+     * 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.
+     */
+    requestThinking() {
+        if (!this.thinkingDropBlock)
+            return this.thinking;
+        const own = this.thinking !== null && typeof this.thinking === 'object' ? this.thinking : { enabled: false };
+        return { ...own, blockBinding: { prefixMismatchBehavior: 'drop_block' } };
+    }
+    /** 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`). */
+    requestNotes(binding, compiled) {
+        const identity = binding.identity;
+        // Each note names the compile the stream was built from, so a note can't vouch for this stream under a record a
+        // later committing compile with binds wrote. A compile that reports no provenance gives the stream nothing to name, and the
+        // stream notes nothing: its replies go without their thinking at the next compile, never refused.
+        const compileId = compiled.provenance?.compileId;
+        if (!identity || compileId === undefined)
+            return {};
+        const cm = this.contextManager;
+        return { noteRequestSent: (rows) => cm.noteRequestSent(rows, identity, compileId) };
+    }
+    /**
+     * 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() {
+        return this.thinkingBinds ? { binds: true, dropBlock: this.thinkingDropBlock, participant: this.name } : 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.
+     */
+    bindingCompileOptions(tools, systemInjections) {
+        const thinkingBinding = this.thinkingBindingOption();
+        if (!thinkingBinding)
+            return {};
+        const { config, providerParams, prefillUserMessage } = this.requestSettings();
+        return {
+            thinkingBinding,
+            identity: {
+                system: wireDigest(this.buildSystemPrompt(systemInjections)),
+                tools: wireDigest(tools),
+                model: wireDigest(this.model),
+                request: wireDigest({
+                    thinking: config.thinking ?? null, maxTokens: config.maxTokens, providerParams: providerParams ?? null,
+                    prefillUserMessage: prefillUserMessage ?? null,
+                }),
+            },
+        };
+    }
     /** The request `assembleActivationRequest` builds (see there), for preview
      * and debug tooling: what this agent's next activation would send. */
     async buildActivationRequest(availableTools, injections, budget, compressionTools = availableTools, options = {}) {
@@ -1359,7 +1826,7 @@ export class Agent {
         // Compiled only once each withheld stub's annotation has finished,
         // including one that began during the compile, and after a stub edit that
         // failed has been retried (see afterAnnotations).
-        const { request, continuePrompt } = await this.toolResultGuard.afterAnnotations(() => this.assembleActivationRequest(availableTools, injections, budget, compressionTools, options));
+        const { request, continuePrompt, compiled, binding } = await this.toolResultGuard.afterAnnotations(() => this.assembleActivationRequest(availableTools, injections, budget, compressionTools, options));
         request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
         const receiptAware = this.contextManager
             .getStrategy?.();
@@ -1385,6 +1852,12 @@ export class Agent {
             emitTokens: true,
             emitBlocks: false,
             emitUsage: true,
+            // A caller that retries itself (the framework's turns: errorPolicy,
+            // provider holds, stated waits, each attempt a fresh compile a stop can
+            // cancel) has membrane send a failed round once and hand the error up:
+            // since membrane 0.7 its own schedules, ten minutes at a 529, would
+            // otherwise run inside each of the caller's attempts, out of its sight.
+            ...(options.membraneRetries === false ? { retry: false } : {}),
             // Retry a content-policy refusal at the provider seam rather than at
             // the framework level: membrane replays the SAME request immediately
             // (cache-warm), where a framework-level requeue would recompile and
@@ -1403,6 +1876,10 @@ export class Agent {
             stream,
             request,
             ...(continuePrompt ? { continuePrompt } : {}),
+            // Read against the messages the stream sends, which membrane's report indexes (RoundReport's coordinates).
+            placeDrops: (entries) => placeThinkingDrops(entries, request.messages, compiled),
+            ...this.requestNotes(binding, compiled),
+            ...(compiled.recordedAfter !== undefined ? { thinkingRecordedAfter: compiled.recordedAfter } : {}),
             ...(kvEnabled
                 ? {
                     takeKvSubmission: () => kvQueue.shift(),
@@ -1473,9 +1950,9 @@ export class Agent {
             console.error(`[assistant-persist] agent=${this.name}: refusing to store a thinking-only assistant ` +
                 `message (${content.length} block(s), no text and no tool_use) — the turn produced no ` +
                 `output. See the refusal/inference-failed record for why.`);
-            return;
+            return undefined;
         }
-        this.contextManager.addMessage(this.name, content, metadata);
+        return this.contextManager.addMessage(this.name, content, metadata);
     }
     /**
      * Transition back to streaming state after tool results are provided.
@@ -1693,7 +2170,7 @@ export class Agent {
                 toolUseId: r.id,
                 content: isError
                     ? truncateForHistory(typeof error === 'string' ? error.toWellFormed() : error, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS)
-                    : nonErrorResultText(r.result, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS),
+                    : nonErrorResultText(r.result, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, { toolName: r.name }),
                 isError,
             };
         });