@slopus/happy-agent-base 0.0.34 → 0.0.36

package/dist/AgentBase.js

@@ -18,6 +18,10 @@ import { agentToolArgumentsError } from "./AgentToolArgumentsError.js";
 import { setAgentSpanAttributes } from "./AgentSpanAttributes.js";
 /** Race winner when an abort interrupts a wait on the stream or a running tool. */
 const ABORTED = Symbol("aborted");
+/** Race winner when drain or shutdown stops waiting for a steerable tool execution. */
+const STEERABLE_STOPPED = Symbol("steerable-stopped");
+/** Race winner when drain or shutdown leaves a reloadable call for the next process. */
+const RELOADABLE_STOPPED = Symbol("reloadable-stopped");
 /** Marks a provider context measurement that inference preparation has not evaluated yet. */
 const UNPREPARED_CONTEXT = Symbol("unprepared context");
 /**
@@ -122,7 +126,7 @@ const storedToolResultSchema = Type.Object({
  *   results, settle their own calls with error results before appending anything behind them.
  * - A conversation loaded with a call stranded under later messages is repaired atomically at
  *   load, since the answer belongs beside its call rather than at the end.
- * - A non-durable tool never runs twice; a durable one may.
+ * - A tool that is neither durable nor reloadable never runs twice; either retry-safe flag may.
  *
  * ## Compaction
  *
@@ -277,6 +281,8 @@ export class AgentBase {
     #providerToolIds = new Map();
     /** The durable steering queue, in the order its keys sort. */
     #steering = [];
+    /** Steering IDs accepted but not consumed, including ones not yet merged into memory. */
+    #pendingSteeringInterruptions = new Set();
     /** The durable send queue, in the order its keys sort. */
     #sends = [];
     /** A committed outer-transaction queue write not yet merged into the in-memory queues. */
@@ -396,6 +402,20 @@ export class AgentBase {
     #admitted = new Set();
     /** Queue acceptances the run loop must publish before it may decide its queues are empty. */
     #messageAdmissions = new Set();
+    /** Active tool executions whose own definition opts into cooperative steering cancellation. */
+    #steerableToolExecutions = new Set();
+    /** Raised once sticky drain or shutdown stops accepting steerable execution latency. */
+    #stopSteerableToolsController = new AbortController();
+    /** One shared race edge, so completed tools do not leave listeners behind until shutdown. */
+    #stopSteerableTools = new Promise((resolve) => {
+        this.#stopSteerableToolsController.signal.addEventListener("abort", () => resolve(STEERABLE_STOPPED), { once: true });
+    });
+    /** Raised once drain or shutdown may leave reloadable calls pending for the next process. */
+    #stopReloadableToolsController = new AbortController();
+    /** One shared reload edge, avoiding one shutdown listener per completed reloadable tool. */
+    #stopReloadableTools = new Promise((resolve) => {
+        this.#stopReloadableToolsController.signal.addEventListener("abort", () => resolve(RELOADABLE_STOPPED), { once: true });
+    });
     /**
      * Work from an earlier response that is still unwinding: a provider stream that has not
      * finished closing, or a tool that was settled in the conversation by an abort and is still
@@ -978,9 +998,15 @@ export class AgentBase {
                                 : { metadata: request.metadata }),
                             options: request.options,
                         });
+                        if (request.kind === "steering") {
+                            this.#pendingSteeringInterruptions.add(request.id);
+                        }
                     }
                     this.#turnRequested = true;
                     this.#startRun();
+                    if (accepted.some(({ request }) => request.kind === "steering")) {
+                        this.#interruptSteerableTools();
+                    }
                 });
             });
             return results;
@@ -1026,8 +1052,14 @@ export class AgentBase {
         if (staged?.activated === true)
             await this.#announceActivation(ctx, false);
         const offeredIds = batch.map(({ id }) => id);
+        const acceptedSteeringIds = results.flatMap((result, index) => result.accepted === "created" && result.delivery === "steer" ? [batch[index].id] : []);
         afterCommit(ctx, async () => {
-            await this.#activateCommittedMessages(offeredIds, staged);
+            for (const id of acceptedSteeringIds)
+                this.#pendingSteeringInterruptions.add(id);
+            const activated = this.#activateCommittedMessages(offeredIds, staged);
+            if (acceptedSteeringIds.length > 0)
+                this.#interruptSteerableTools();
+            await activated;
         });
         return results;
     }
@@ -1061,6 +1093,9 @@ export class AgentBase {
             this.#offeredMessageIds.add(id);
         if (staged === undefined)
             return;
+        // The queue already committed. Raise the merge marker synchronously so a steerable tool
+        // woken by that commit cannot reach the next inference before the message is visible.
+        this.#committedQueueDirty = true;
         // The commit published the staged activation announcement along with the batch, so the
         // current active period is now an announced one.
         if (staged.activated) {
@@ -1083,11 +1118,15 @@ export class AgentBase {
             if (this.#runPromise === undefined) {
                 this.#adoptPendingState(pending);
             }
-            this.#committedQueueDirty = true;
         });
         this.#turnRequested = true;
         this.#startRun();
     }
+    /** Abort only active tool execution signals that explicitly opted into steering. */
+    #interruptSteerableTools() {
+        for (const execution of this.#steerableToolExecutions)
+            execution.abort();
+    }
     /** Make one committed pending record the exact in-memory lifecycle state. */
     #adoptPendingState(pending) {
         this.#pending = pending;
@@ -1141,11 +1180,14 @@ export class AgentBase {
         this.#startRun();
     }
     /**
-     * Stop this loop at its next durable edge without cancelling its current operation. The mode
-     * is sticky: later queue writes remain durable but cannot start another run in this process.
+     * Stop this loop at its next durable edge. Ordinary current operations finish; a steerable
+     * tool receives a cancelled lifetime and is no longer awaited. The mode is sticky: later
+     * queue writes remain durable but cannot start another run in this process.
      */
     drain() {
         this.#draining = true;
+        this.#stopSteerableToolsController.abort();
+        this.#stopReloadableToolsController.abort();
         this.#drainPromise ??= this.#finishDrain();
         return this.#drainPromise;
     }
@@ -1257,15 +1299,22 @@ export class AgentBase {
         }
     }
     /**
-     * The system prompt for the next request: the mutable state extended by the hook's answer.
-     * Instructions and tools are correctness hooks — a failure here fails the turn loudly
-     * instead of silently running with a wrong configuration.
+     * Resolve one complete provider configuration. Sharing this snapshot between instructions,
+     * the provider descriptor array, and streamed-call policy keeps one inference or compaction
+     * internally consistent even when a hook computes its tools dynamically.
      */
-    async #instructions(ctx) {
-        const hooked = await this.#hooks.instructions?.(this.#workContext(ctx));
-        return [this.state.instructions, hooked ?? ""]
+    async #configuration(ctx) {
+        // Preserve the established correctness-hook order: instructions first, then tools.
+        const hookedInstructions = await this.#hooks.instructions?.(this.#workContext(ctx));
+        const tools = await this.#tools(ctx);
+        const instructions = [
+            this.state.instructions,
+            hookedInstructions ?? "",
+            toolCapabilityInstructions(tools),
+        ]
             .filter((text) => text.length > 0)
             .join("\n\n");
+        return { instructions, tools };
     }
     /**
      * The tools for the next request or execution: the mutable state extended by the hook's
@@ -1277,6 +1326,10 @@ export class AgentBase {
         const tools = [...this.state.tools, ...(hooked ?? [])];
         const names = new Set();
         for (const tool of tools) {
+            if (tool.server === undefined &&
+                (tool.persistInHistory === false || tool.visibleToUser === false)) {
+                throw new Error(`Tool "${tool.name}" may hide publication only when the provider owns it through a server descriptor.`);
+            }
             const key = `${tool.namespace ?? ""}\u0000${tool.name}`;
             if (names.has(key)) {
                 throw new Error(tool.namespace === undefined
@@ -1356,9 +1409,10 @@ export class AgentBase {
         // because the work it would abandon is the caller itself.
         const fromInsideOwnLoop = this.#insideOwnLoop();
         this.#closed = true;
-        // Graceful shutdown stops at the next operation boundary. Do not abort a tool that is
-        // already running; the coordinator's timeout and the daemon's hard exit bound one that
-        // never returns.
+        // Graceful shutdown lets ordinary tools reach the next durable edge, but steerable tools
+        // explicitly opt out of holding shutdown open. A direct close still abandons every tool.
+        this.#stopSteerableToolsController.abort();
+        this.#stopReloadableToolsController.abort();
         if (!fromInsideOwnLoop && !this.#stopAtSafeEdgeRequested()) {
             this.#closeController.abort();
         }
@@ -2087,8 +2141,7 @@ export class AgentBase {
      * arrived before the request was made, since there is no response to account for.
      */
     async #requestInference(ctx, abortPromise) {
-        const instructions = await this.#instructions(ctx);
-        const tools = await this.#tools(ctx);
+        const { instructions, tools } = await this.#configuration(ctx);
         const session = await this.#ensureSession(instructions, tools);
         // Nothing from the previous response may still be holding the session — but that
         // unwinding was detached from an earlier abort precisely so it could never hold a
@@ -2127,7 +2180,7 @@ export class AgentBase {
             ...(this.#effort === undefined ? {} : { effort: this.#effort }),
             ...(this.#serviceTier === undefined ? {} : { serviceTier: this.#serviceTier }),
         });
-        const { content, state, errorMessage, tokens } = await this.#collect(ctx, stream, abortPromise);
+        const { content, state, errorMessage, tokens } = await this.#collect(ctx, stream, abortPromise, tools);
         // A cancellation or a stream ending without a done event did not answer an appended
         // notice. Keep that obligation and reopen it under a fresh turn scope. Every terminal
         // provider outcome counts as the response, including an error.
@@ -2253,8 +2306,8 @@ export class AgentBase {
             return;
         try {
             await this.#enterStage(ctx, "compaction");
-            const instructions = await this.#instructions(ctx);
-            const session = await this.#ensureSession(instructions, await this.#tools(ctx));
+            const { instructions, tools } = await this.#configuration(ctx);
+            const session = await this.#ensureSession(instructions, tools);
             const snapshot = this.#messagesForProvider(this.#messages);
             await this.#settled();
             const compactionStart = {
@@ -2416,9 +2469,9 @@ export class AgentBase {
                         const result = entry.committed;
                         await this.#appendRecord(txCtx, toolContextRecord(result, this.#providerToolIds));
                         await this.#persistence.deleteValue(txCtx, entry.key);
-                        // A result the conversation records is a result the hook sees, however
-                        // little of a run produced it. A hook that fails here leaves the calls
-                        // unsettled, which is what lets a later attempt answer them properly.
+                        // Every Base-executed result reaches correctness and security observers.
+                        // Publication suppression is intentionally limited to provider-owned
+                        // server calls, which never enter the execution path.
                         await this.#invokeToolTransactHook(txCtx, entry.id, this.#hooks.afterToolCallTransact, result);
                         await this.#kv.scoped("call", entry.id).clear(txCtx);
                     }
@@ -2571,8 +2624,16 @@ export class AgentBase {
             // The durable queue, not memory, decides what is left to consume after a restart.
             const durable = new Set((await this.#persistence.readValues(lockCtx, prefix)).map(({ key }) => key));
             const remaining = queue.filter((entry) => durable.has(entry.key));
-            if (remaining.length !== queue.length)
+            if (remaining.length !== queue.length) {
+                if (kind === "steering") {
+                    for (const entry of queue) {
+                        if (!durable.has(entry.key)) {
+                            this.#pendingSteeringInterruptions.delete(entry.id);
+                        }
+                    }
+                }
                 queue.splice(0, queue.length, ...remaining);
+            }
             if (queue.length === 0)
                 return false;
             const count = mode === "all" ? queue.length : 1;
@@ -2771,6 +2832,10 @@ export class AgentBase {
                 ...(entry.metadata === undefined ? {} : { metadata: entry.metadata }),
             })));
             queue.splice(0, count);
+            if (kind === "steering") {
+                for (const entry of batch)
+                    this.#pendingSteeringInterruptions.delete(entry.id);
+            }
             if (reset) {
                 this.#messages = injected === undefined ? [] : [injected];
                 this.#providerToolIds.clear();
@@ -2887,6 +2952,9 @@ export class AgentBase {
             const measured = context[0]?.value;
             this.#contextTokens = measured?.tokens;
             this.#steering = steering.map(({ key, value }) => this.#restoreQueueEntry(key, value));
+            for (const entry of this.#steering) {
+                this.#pendingSteeringInterruptions.add(entry.id);
+            }
             this.#sends = sends.map(({ key, value }) => this.#restoreQueueEntry(key, value));
             this.#injections = injections.map(({ key, value }) => ({
                 key,
@@ -2933,9 +3001,9 @@ export class AgentBase {
      * result. All calls run in parallel, but results land strictly in call order: a finished
      * result waits until every earlier call in the batch has committed, and each commit appends
      * the tool record and removes the pending entry in one transaction before memory changes.
-     * On resume, only durable tools execute again; the rest become error results. An abort
-     * settles every call still running as an aborted error result, so the batch always leaves a
-     * complete context behind.
+     * On resume, durable and reloadable tools execute again; the rest become error results. An
+     * abort settles every call still running as an aborted error result, so the batch always
+     * leaves a complete context behind.
      */
     async #runToolBatch(ctx, entries, resume, signal, abortPromise) {
         return await this.#span(ctx, "agent.tools", { "agent.tool.count": entries.length, "agent.tool.resume": resume }, (batchCtx) => this.#dispatchToolBatch(batchCtx, entries, resume, signal, abortPromise));
@@ -2966,6 +3034,7 @@ export class AgentBase {
         // Every execution actually started, whether or not its result reached the conversation.
         const running = [];
         let closedDuringTools = false;
+        let reloadableStopped = false;
         let committed = 0;
         // A failed commit blocks the turn with its pending calls intact for resume. A sibling
         // still running at that moment no longer owns the append-only tail: its result could
@@ -3037,7 +3106,7 @@ export class AgentBase {
             if (entry.committed !== undefined) {
                 outcome = entry.committed;
             }
-            else if (resume && !(await this.#isDurable(ctx, entry.call))) {
+            else if (resume && !(await this.#isRetryable(ctx, entry.call))) {
                 outcome = toolFailure(entry.id, "The tool call was interrupted by a restart and was not retried.");
             }
             else {
@@ -3055,6 +3124,10 @@ export class AgentBase {
                 running.push(execution);
                 outcome = await Promise.race([execution, abortPromise, this.#closingTools()]);
             }
+            if (outcome === RELOADABLE_STOPPED) {
+                reloadableStopped = true;
+                return;
+            }
             if (outcome === ABORTED && !signal.aborted)
                 closedDuringTools = true;
             results[index] =
@@ -3085,7 +3158,7 @@ export class AgentBase {
         // An abort or failure may settle the conversation or block the batch without settling the
         // actual execution. Track that unwinding so another in-process attempt cannot overlap it;
         // the batch itself does not wait, so an uncooperative tool cannot hold this turn open.
-        return closedDuringTools;
+        return closedDuringTools || reloadableStopped;
     }
     /**
      * Settles once close begins, so a batch stops waiting for tools that a shutdown may itself
@@ -3101,10 +3174,10 @@ export class AgentBase {
             });
         });
     }
-    /** Whether this call's tool may safely be executed again after a restart interrupted it. */
-    async #isDurable(ctx, call) {
+    /** Whether this call's tool may safely execute again after a crash or deliberate reload. */
+    async #isRetryable(ctx, call) {
         const tool = (await this.#tools(ctx)).find((candidate) => candidate.name === call.name && candidate.namespace === call.namespace);
-        return tool?.durable === true;
+        return tool?.durable === true || tool?.reloadable === true;
     }
     /** Every client tool call in the conversation that has no matching result yet. */
     #unansweredCalls(messages) {
@@ -3406,46 +3479,81 @@ export class AgentBase {
                 const runCtx = decision?.permissionMode === undefined
                     ? callCtx
                     : withAgentPermissionMode(callCtx, decision.permissionMode);
-                const executionCtx = withLifetime(runCtx, AbortSignal.any(runCtx.lifetime === undefined
-                    ? [callLifetime.signal]
-                    : [runCtx.lifetime, callLifetime.signal]));
+                const reloadable = ran.reloadable === true;
+                const steeringLifetime = ran.steerable === true ? new AbortController() : undefined;
+                const executionCtx = withLifetime(runCtx, AbortSignal.any([
+                    ...(runCtx.lifetime === undefined ? [] : [runCtx.lifetime]),
+                    callLifetime.signal,
+                    ...(steeringLifetime === undefined
+                        ? []
+                        : [steeringLifetime.signal, this.#stopSteerableToolsController.signal]),
+                    ...(reloadable ? [this.#stopReloadableToolsController.signal] : []),
+                ]));
                 const toolCall = {
                     id: entry.id,
                     kv: boundedCallKV,
                     commit,
                 };
-                const returned = ran.transactional === true
-                    ? this.#persistence.transaction(executionCtx, async (txCtx) => {
-                        const result = await ran.execute(txCtx, ranArguments, toolCall);
-                        if (!Value.Check(ran.returnType, result)) {
+                if (steeringLifetime !== undefined) {
+                    this.#steerableToolExecutions.add(steeringLifetime);
+                    if (this.#pendingSteeringInterruptions.size > 0)
+                        steeringLifetime.abort();
+                }
+                try {
+                    const returned = ran.transactional === true
+                        ? this.#persistence.transaction(executionCtx, async (txCtx) => {
+                            const result = await ran.execute(txCtx, ranArguments, toolCall);
+                            if (!Value.Check(ran.returnType, result)) {
+                                throw new Error(`Tool "${ran.name}" returned an invalid result.`);
+                            }
+                            return await commit(txCtx, result);
+                        })
+                        : Promise.resolve(ran.execute(executionCtx, ranArguments, toolCall));
+                    const execution = returned.then((result) => ({ type: "returned", result }), (error) => ({ type: "threw", error }));
+                    const settled = await Promise.race([
+                        execution,
+                        committed.then((committed) => ({ type: "committed", committed })),
+                        ...(reloadable
+                            ? [this.#stopReloadableTools]
+                            : steeringLifetime === undefined
+                                ? []
+                                : [this.#stopSteerableTools]),
+                    ]);
+                    if (settled === RELOADABLE_STOPPED) {
+                        throw RELOADABLE_STOPPED;
+                    }
+                    else if (settled === STEERABLE_STOPPED) {
+                        throw new Error("The tool call was interrupted while the agent was stopping.");
+                    }
+                    else if (settled.type === "committed") {
+                        outcome = settled.committed;
+                    }
+                    else if (settled.type === "threw") {
+                        throw settled.error;
+                    }
+                    else if (committedOutcome !== undefined) {
+                        outcome = committedOutcome;
+                    }
+                    else {
+                        if (!Value.Check(ran.returnType, settled.result)) {
                             throw new Error(`Tool "${ran.name}" returned an invalid result.`);
                         }
-                        return await commit(txCtx, result);
-                    })
-                    : Promise.resolve(ran.execute(executionCtx, ranArguments, toolCall));
-                const execution = returned.then((result) => ({ type: "returned", result }), (error) => ({ type: "threw", error }));
-                const settled = await Promise.race([
-                    execution,
-                    committed.then((committed) => ({ type: "committed", committed })),
-                ]);
-                if (settled.type === "committed") {
-                    outcome = settled.committed;
-                }
-                else if (settled.type === "threw") {
-                    throw settled.error;
-                }
-                else if (committedOutcome !== undefined) {
-                    outcome = committedOutcome;
+                        outcome = outcomeFor(settled.result);
+                    }
                 }
-                else {
-                    if (!Value.Check(ran.returnType, settled.result)) {
-                        throw new Error(`Tool "${ran.name}" returned an invalid result.`);
+                finally {
+                    if (steeringLifetime !== undefined) {
+                        this.#steerableToolExecutions.delete(steeringLifetime);
+                        steeringLifetime.abort();
                     }
-                    outcome = outcomeFor(settled.result);
                 }
             }
         }
         catch (error) {
+            if (error === RELOADABLE_STOPPED) {
+                callLifetime.abort();
+                return RELOADABLE_STOPPED;
+            }
             outcome =
                 committedOutcome ??
                     {
@@ -3515,13 +3623,15 @@ export class AgentBase {
      * the model actually finished saying: a response cut off mid-block keeps the finished blocks
      * alone, so memory never differs from what a reload would rebuild.
      */
-    async #collect(ctx, stream, abortPromise) {
+    async #collect(ctx, stream, abortPromise, tools) {
         const content = [];
         // Blocks that finished and were durably appended. An abort keeps exactly these, so the
         // in-memory assistant message never diverges from what a reload would rebuild.
         const persisted = [];
         const toolCallIndexes = new Map();
         const toolResultIndexes = new Map();
+        const toolPolicies = new Map();
+        const deferredToolCalls = new Map();
         // Provider IDs remain only in the private context blocks. Every event and transactional
         // projection leaving this method uses the generated Base ID instead.
         const responseToolIds = new Map();
@@ -3542,6 +3652,24 @@ export class AgentBase {
             });
             persisted.push(block);
         };
+        const persistPair = async (call, callEvent, result) => {
+            const callRecord = assistantContextRecord(call, this.#providerToolIds);
+            const resultRecord = assistantContextRecord(result, this.#providerToolIds);
+            await this.#runPersistenceStep(this.#workContext(ctx), (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
+                await this.#appendRecord(txCtx, callRecord);
+                await this.#appendRecord(txCtx, resultRecord);
+                if (callEvent !== undefined) {
+                    await this.#withTransactionalContext(txCtx, (hookCtx) => this.#hooks.onEventTransact?.(hookCtx, callEvent));
+                }
+            }));
+            persisted.push(call, result);
+        };
+        const flushCompletedCallOnlyTools = async () => {
+            for (const deferred of deferredToolCalls.values()) {
+                await persist(deferred.block, undefined);
+            }
+            deferredToolCalls.clear();
+        };
         const iterator = stream[Symbol.asyncIterator]();
         // A response usually ends before its stream does — at the done event, or at an abort —
         // and the provider holds a connection behind that stream. Whichever way this method
@@ -3563,7 +3691,20 @@ export class AgentBase {
                 }
                 const providerEvent = next.value;
                 const event = baseSessionEvent(providerEvent, responseToolIds, this.#providerToolIds);
-                await this.#emit(ctx, event);
+                if (event.type === "toolcall_start") {
+                    const tool = tools.find((candidate) => candidate.name === event.name &&
+                        candidate.namespace === event.namespace);
+                    const policy = {
+                        persistInHistory: event.server !== true || tool?.persistInHistory !== false,
+                        persistWithResult: event.server === true && tool?.persistInHistory === false,
+                        visibleToUser: event.server !== true || tool?.visibleToUser !== false,
+                    };
+                    toolPolicies.set(event.callId, policy);
+                }
+                const policyCallId = toolLifecycleCallId(event);
+                const toolPolicy = policyCallId === undefined ? undefined : toolPolicies.get(policyCallId);
+                if (toolPolicy?.visibleToUser !== false)
+                    await this.#emit(ctx, event);
                 switch (event.type) {
                     case "text_start":
                         content.push({ type: "text", text: "" });
@@ -3580,6 +3721,10 @@ export class AgentBase {
                     }
                     case "text_end": {
                         const last = content[content.length - 1];
+                        // Provider-owned results precede the model synthesis. If the provider
+                        // exposes no result block, commit its completed call immediately before
+                        // that synthesis so restart replay preserves the logical output order.
+                        await flushCompletedCallOnlyTools();
                         await persist(last?.type === "text" ? last : undefined, last?.type === "text" ? { ...event, block: last } : undefined);
                         break;
                     }
@@ -3606,6 +3751,7 @@ export class AgentBase {
                                     : { reasoning: event.reasoning }),
                             };
                             content[content.length - 1] = finished;
+                            await flushCompletedCallOnlyTools();
                             await persist(finished, { ...event, block: finished });
                         }
                         break;
@@ -3631,22 +3777,34 @@ export class AgentBase {
                         break;
                     }
                     case "toolcall_end": {
+                        if (providerEvent.type !== "toolcall_end") {
+                            throw new Error("The provider tool-call end changed event type.");
+                        }
                         const index = toolCallIndexes.get(event.callId);
                         const block = index === undefined ? undefined : content[index];
                         if (index !== undefined && block?.type === "tool_call") {
+                            const finalVendor = providerEvent.vendor;
                             const finished = {
                                 ...block,
                                 arguments: event.arguments,
+                                ...(finalVendor === undefined ? {} : { vendor: finalVendor }),
                                 ...(event.incomplete === undefined
                                     ? {}
                                     : { incomplete: event.incomplete }),
                             };
                             content[index] = finished;
                             const { vendor: _vendor, ...publicBlock } = finished;
-                            await persist(finished, {
-                                ...event,
-                                block: publicBlock,
-                            });
+                            const persistedEvent = { ...event, block: publicBlock };
+                            const policy = toolPolicies.get(event.callId);
+                            if (policy?.persistWithResult === true) {
+                                deferredToolCalls.set(event.callId, {
+                                    block: finished,
+                                    event: persistedEvent,
+                                });
+                            }
+                            else {
+                                await persist(finished, policy?.persistInHistory === false ? undefined : persistedEvent);
+                            }
                         }
                         break;
                     }
@@ -3692,10 +3850,30 @@ export class AgentBase {
                                 : { incomplete: event.incomplete }),
                         };
                         content[resultIndex] = finished;
-                        await persist(finished, undefined);
+                        const policy = toolPolicies.get(event.callId);
+                        if (policy?.persistWithResult === true) {
+                            const deferred = deferredToolCalls.get(event.callId);
+                            if (deferred === undefined) {
+                                throw new Error("A provider-local tool result has no completed call to persist.");
+                            }
+                            await persistPair(deferred.block, policy.persistInHistory ? deferred.event : undefined, finished);
+                            deferredToolCalls.delete(event.callId);
+                        }
+                        else {
+                            await persist(finished, undefined);
+                        }
                         break;
                     }
                     case "done":
+                        if (event.state === "normal" ||
+                            event.state === "tool_call" ||
+                            event.state === "length") {
+                            // Some provider-owned tools, notably Claude Code built-ins, consume
+                            // their result internally and expose only a completed call. Keep that
+                            // call after a successful response, while an interrupted response
+                            // retains neither half of a call/result pair.
+                            await flushCompletedCallOnlyTools();
+                        }
                         return {
                             // Only blocks that finished, which are exactly the blocks that were
                             // durably appended. A response ending mid-block leaves half of
@@ -3771,6 +3949,40 @@ export class AgentBase {
         }
     }
 }
+/** A model-facing section derived from one resolved tool array. */
+function toolCapabilityInstructions(tools) {
+    const capabilities = [];
+    const seen = new Set();
+    for (const tool of tools) {
+        for (const raw of tool.capabilities ?? []) {
+            const capability = raw.trim();
+            if (capability.length === 0)
+                continue;
+            const key = capability.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            capabilities.push(capability);
+        }
+    }
+    if (capabilities.length === 0)
+        return "";
+    return ["Tool capabilities:", ...capabilities.map((capability) => `- ${capability}`)].join("\n");
+}
+/** The Base call identity carried by provider call/result lifecycle events. */
+function toolLifecycleCallId(event) {
+    switch (event.type) {
+        case "toolcall_start":
+        case "toolcall_delta":
+        case "toolcall_end":
+        case "toolcall_result_start":
+        case "toolcall_result_delta":
+        case "toolcall_result_end":
+            return event.callId;
+        default:
+            return undefined;
+    }
+}
 /** The result that stands in for a call the agent could not, or must not, carry out. */
 function toolFailure(id, reason) {
     return {
@@ -3797,6 +4009,7 @@ function sessionConfigKey(provider, model, instructions, tools) {
             tool.description ?? null,
             tool.parameters ?? null,
             tool.defer ?? null,
+            tool.searchKeywords ?? null,
             tool.server ?? null,
             tool.grammar ?? null,
         ]),