@theoremjs/agents 0.3.1 → 0.3.3

package/esm/src/kernel/engine/runner/steps.js

@@ -7,7 +7,7 @@ import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
 import { replyIsJudged } from '../../../guardrails/progressive-yield.js';
 import { recordTaint } from '../../../guardrails/tool-result.js';
 import { waitDefault } from '../../../providers/shared/retry.js';
-import { historyToolCalls } from '../../interaction-parts.js';
+import { stepReplyMessages } from '../../interaction-parts.js';
 import { profileTurnOutputs } from '../../registry/profile-outputs.js';
 import { providerCompleteRequest } from '../../registry/provider-request.js';
 import { injectWouldExceedMaxSteps } from '../../stages.js';
@@ -19,7 +19,7 @@ import { profileToolsParallel } from '../../tools/resolve.js';
 import { findLast } from '../../util/find-last.js';
 import { startToolTrace } from '../tool-trace.js';
 import { startCallTrace } from '../turn-trace.js';
-import { applyStageInjects } from './stages.js';
+import { applyStageInjects, recordReply } from './stages.js';
 import { recordStepEvent } from './state.js';
 import { inStep, runSideBySide, stepOrder } from './step-order.js';
 import { isWithheldOnBlock, StructuredDrafts, yieldProviderEvents, } from './stream.js';
@@ -112,10 +112,28 @@ function tallyCallEvent(event, tally, call) {
         call.guardrail(event.guardrail);
     if (event.type === 'structured')
         tally.latestStructured = event.structured;
+    if (event.type === 'text')
+        tally.text += event.text;
     if (REPLY_EVENTS.has(event.type))
         tally.replied = true;
     return false;
 }
+/** What sets one model call's text apart from the reply text before it: a blank line. */
+const CALL_BREAK = '\n\n';
+/**
+ * The call's first text, set apart from the attempt's reply before it.
+ *
+ * why: Each model call writes as if it starts the message, so a reply that goes on after tools or
+ * an inject would otherwise run its first word into the last one ("…full picture.Here's").
+ */
+function withCallBreak(event, tally, state, generation) {
+    if (tally.text)
+        return event;
+    const before = state.replyText;
+    const breaks = before && generation.structured === null && !/\s$/.test(before) && !/^\s/.test(event.text);
+    tally.replyAt = before.length + (breaks ? CALL_BREAK.length : 0);
+    return breaks ? { ...event, text: `${CALL_BREAK}${event.text}` } : event;
+}
 /** Records an event the call gave. True when the host gets it now. */
 function releasesNow(event, control, state, buffer) {
     recordStepEvent(event, state);
@@ -125,8 +143,10 @@ function releasesNow(event, control, state, buffer) {
         state.withheldVisible = true;
         return false;
     }
-    if (event.type === 'text')
+    if (event.type === 'text') {
         state.released += event.text;
+        state.replyText += event.text;
+    }
     // why: Text and media stream via progressive-yield under egress, thoughts
     // stream unguarded; holdLate only buffers non-visible events (e.g.
     // structured) for validation.
@@ -135,6 +155,7 @@ function releasesNow(event, control, state, buffer) {
 }
 // why: Every other kind is the provider's answer to the request itself (it refused a part, a key, a setting); the same call sent again gets the same answer.
 const PASSING_ERROR_KINDS = new Set([
+    'busy',
     'unavailable',
     'bad_response',
     'network',
@@ -174,7 +195,7 @@ async function* executeAutonomousStep(args, state, buffer = {
 }) {
     const { profile, generation, system, provider, signal } = args;
     const { usage, genForStep, request, call } = startProviderCall(generation, system, state, isAnswerOnlyStep(profile, generation, state.stepCount));
-    const tally = { calls: [], reasoning: [], failures: [], replied: false };
+    const tally = { calls: [], reasoning: [], text: '', failures: [], replied: false };
     const control = {
         withholdVisible: false,
         ...(state.canaryCarry ? { canaryCarry: state.canaryCarry } : {}),
@@ -219,11 +240,13 @@ async function* executeAutonomousStep(args, state, buffer = {
                     yield event;
                 continue;
             }
+            // why: The model's history keeps what it wrote; only the reply the host gets is set apart.
+            const next = event.type === 'text' ? withCallBreak(event, tally, state, genForStep) : event;
             if (tallyCallEvent(event, tally, call))
                 continue;
-            if (!releasesNow(event, control, state, buffer))
+            if (!releasesNow(next, control, state, buffer))
                 continue;
-            yield* shown.show(event);
+            yield* shown.show(next);
         }
     }
     catch (err) {
@@ -249,7 +272,9 @@ async function* executeAutonomousStep(args, state, buffer = {
     return {
         calls: tally.calls,
         reasoning: tally.reasoning,
+        text: tally.text,
         latestStructured: tally.latestStructured,
+        ...(tally.replyAt === undefined ? {} : { replyAt: tally.replyAt }),
         ...(resume ? { resume } : {}),
     };
 }
@@ -356,6 +381,14 @@ function* applyToolSettlement(settlement, state, call) {
     }
     return 'continue';
 }
+/** A step's reply as the model reads it back: its text, then its calls with the reasoning before them. */
+function stepReply(outcome) {
+    return stepReplyMessages({
+        text: outcome.text,
+        structured: outcome.latestStructured,
+        calls: outcome.calls.map((call, index) => index === 0 ? { ...call, reasoning: outcome.reasoning } : call),
+    });
+}
 /**
  * Run the model's calls. Each reaches the host as its raw call first, all of them before
  * any runs; their phases then arrive as each tool gives them. With `tools.parallel` they
@@ -370,10 +403,10 @@ function* applyToolSettlement(settlement, state, call) {
  * After the step, any gate stops the turn. A call a stage cancelled stops the turn too,
  * once every result that did come back is recorded.
  */
-async function* handleModelCalls({ calls: upstreamCalls, reasoning }, generation, profile, state, system, { onStage, signal, credentials, resolveHost } = {}) {
-    if (upstreamCalls.length > 0) {
-        state.currentHistory.push(historyToolCalls(upstreamCalls.map((call, index) => (index === 0 ? { ...call, reasoning } : call))));
-    }
+async function* handleModelCalls(outcome, generation, profile, state, system, { onStage, signal, credentials, resolveHost } = {}) {
+    const { calls: upstreamCalls, reasoning } = outcome;
+    if (upstreamCalls.length > 0)
+        recordReply(state, stepReply(outcome), outcome.replyAt);
     const stepId = crypto.randomUUID();
     const leakScope = {
         canary: generation.canary,
@@ -485,6 +518,9 @@ async function* handleModelCalls({ calls: upstreamCalls, reasoning }, generation
 async function* executeAttempt(args) {
     const { profile, generation, system, provider, state } = args;
     let latestStructured;
+    // why: The answer that ends the attempt is not in turn history; a `before_end` inject puts it there first.
+    let reply = [];
+    let replyAt;
     // why: Text streams via progressive-yield under egress, thoughts unguarded; validation and egress
     // both hold non-visible events (structured) until the attempt gate, so a policy
     // sees the structured payload before any of it reaches the host.
@@ -505,6 +541,8 @@ async function* executeAttempt(args) {
         if (stepResult.latestStructured !== undefined) {
             latestStructured = stepResult.latestStructured;
         }
+        reply = stepResult.calls.length > 0 ? [] : stepReply(stepResult);
+        replyAt = stepResult.replyAt;
         const executed = yield* handleModelCalls(stepResult, generation, profile, state, system, args.safe);
         if (!executed) {
             break;
@@ -514,6 +552,6 @@ async function* executeAttempt(args) {
             state.lastStop = { kind: 'step_limit' };
         }
     }
-    return { latestStructured };
+    return { latestStructured, reply, ...(replyAt === undefined ? {} : { replyAt }) };
 }
 export { executeAttempt };

package/esm/src/kernel/interaction-parts.d.ts

@@ -9,5 +9,17 @@ export declare function isMediaRefPart(part: InteractionPart): part is Interacti
  * Neither field replaces the other.
  */
 export declare function historyMessageParts(msg: TurnHistoryMessage): InteractionPart[];
+/**
+ * One model call's reply as the model reads it back later in its turn: what it
+ * wrote (its structured reply, when it gave one), then the calls it made. Turn
+ * history and a provider checkpoint both build it here, so the checkpoint
+ * covers exactly the history the turn's next call sends.
+ */
+export declare function stepReplyMessages(reply: {
+    text: string;
+    structured?: unknown;
+    calls: Parameters<typeof historyToolCalls>[0];
+}): TurnHistoryMessage[];
 /** One step's calls as the assistant message that made them, with the reasoning written before them. */
-export declare function historyToolCalls(calls: readonly Pick<import('./turn-events.js').ToolCallRequest, 'callId' | 'name' | 'arguments' | 'reasoning'>[]): TurnHistoryMessage;
+declare function historyToolCalls(calls: readonly Pick<import('./turn-events.js').ToolCallRequest, 'callId' | 'name' | 'arguments' | 'reasoning'>[]): TurnHistoryMessage;
+export {};

package/esm/src/kernel/interaction-parts.js

@@ -21,8 +21,21 @@ export function historyMessageParts(msg) {
     const parts = msg.parts ?? [];
     return msg.content ? [{ type: 'text', text: msg.content }, ...parts] : [...parts];
 }
+/**
+ * One model call's reply as the model reads it back later in its turn: what it
+ * wrote (its structured reply, when it gave one), then the calls it made. Turn
+ * history and a provider checkpoint both build it here, so the checkpoint
+ * covers exactly the history the turn's next call sends.
+ */
+export function stepReplyMessages(reply) {
+    const content = reply.structured !== undefined ? JSON.stringify(reply.structured) : reply.text;
+    return [
+        ...(content ? [{ role: 'assistant', content }] : []),
+        ...(reply.calls.length ? [historyToolCalls(reply.calls)] : []),
+    ];
+}
 /** One step's calls as the assistant message that made them, with the reasoning written before them. */
-export function historyToolCalls(calls) {
+function historyToolCalls(calls) {
     const reasoning = calls.flatMap((call) => call.reasoning ?? []);
     const tool_calls = [];
     for (const call of calls) {

package/esm/src/kernel/mod.d.ts

@@ -60,6 +60,8 @@ export { systemPromptProblem } from './system-parts.js';
 export { activityLabelProblem } from './tools/activity-label.js';
 export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
 export { type AnsweredGate, answerGatedCall, GATE_DECISIONS, type GateAnswerRequest, type GateDecision, gateExpired, type HeldGatedCall, resolveGateTtlMs, sessionPermissionsAfterApproval, type ToolGateAuth, } from './tools/gate-answer.js';
+export type { MemoryToolExecutionOptions } from './tools/memory-execution.js';
+export { createMemoryToolExecution } from './tools/memory-execution.js';
 export type { CredentialQuery, McpProtocolVersion, McpRpcResponse, ToolRegistry, } from './tools/mod.js';
 export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
 export type { BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationUncertainty, } from './tools/operation.js';

package/esm/src/kernel/mod.js

@@ -36,6 +36,7 @@ export { systemPromptProblem } from './system-parts.js';
 export { activityLabelProblem } from './tools/activity-label.js';
 export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
 export { answerGatedCall, GATE_DECISIONS, gateExpired, resolveGateTtlMs, sessionPermissionsAfterApproval, } from './tools/gate-answer.js';
+export { createMemoryToolExecution } from './tools/memory-execution.js';
 export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
 export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './tools/operation.js';
 export { jsonSchemaFromZod } from './tools/schema.js';

package/esm/src/kernel/protocols/runtime.js

@@ -309,7 +309,7 @@ function isKind(error, kind) {
 }
 /**
  * Runs one call with the kernel's retries, all before the first event: once on the fallback slot
- * when the first key is out of quota, and once after an `auth` refusal with the minted token
+ * when the first key is out of quota or its model is busy, and once after an `auth` refusal with the minted token
  * dropped. A fallback starts clean: it may be another account, so it never sends the first key's
  * state.
  */
@@ -330,7 +330,7 @@ async function* withKeys(setup, run) {
         catch (error) {
             if (started)
                 throw error;
-            if (isKind(error, 'rate_limit') &&
+            if ((isKind(error, 'rate_limit') || isKind(error, 'busy')) &&
                 fallback &&
                 slot !== fallback &&
                 holdsKey(setup, fallback)) {

package/esm/src/kernel/provider-runtime.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { isAbortError, TheoremError, throwIfAborted, } from '../guardrails/error.js';
 import { labelText } from '../guardrails/labels.js';
 import { historyHash, providerCheckpointSchema, } from './checkpoint.js';
-import { historyToolCalls } from './interaction-parts.js';
+import { stepReplyMessages } from './interaction-parts.js';
 import { jsonObjectSchema, jsonValueSchema } from './json.js';
 import { keySlotsOf, protocolOf, } from './protocols/binding.js';
 import { resolveProviderLimits } from './protocols/limits.js';
@@ -409,12 +409,7 @@ async function* consumeModelStep(events, signal) {
     const pending = [];
     const reasoning = [];
     let text = '';
-    const outputs = [];
-    const flushText = () => {
-        if (text)
-            outputs.push({ role: 'assistant', content: text });
-        text = '';
-    };
+    let structured;
     const iterator = events[Symbol.asyncIterator]();
     let exhausted = false;
     try {
@@ -435,8 +430,7 @@ async function* consumeModelStep(events, signal) {
                     text += event.text;
                     break;
                 case 'structured':
-                    flushText();
-                    outputs.push({ role: 'assistant', content: JSON.stringify(event.structured) });
+                    structured = event.structured;
                     break;
                 case 'reasoning': {
                     const { type: _type, ...part } = event;
@@ -446,7 +440,6 @@ async function* consumeModelStep(events, signal) {
                 case 'tool_call':
                     if (pending.some((call) => call.callId === event.call.callId))
                         throw new TheoremError('bad_response', labelText('provider.duplicate_call'));
-                    flushText();
                     if (event.call.wireCallId)
                         wireCallIds[event.call.callId] = event.call.wireCallId;
                     pending.push(kernelCall(event.call));
@@ -467,8 +460,15 @@ async function* consumeModelStep(events, signal) {
         if (!exhausted && iterator.return)
             void Promise.resolve(iterator.return()).catch(() => undefined);
     }
-    flushText();
-    return { terminal, failed, pending, reasoning, outputs, wireCallIds };
+    return {
+        terminal,
+        failed,
+        pending,
+        reasoning,
+        text,
+        ...(structured !== undefined ? { structured } : {}),
+        wireCallIds,
+    };
 }
 /**
  * A profile's model as the engine calls it: each step one guarded protocol call, with the
@@ -489,7 +489,7 @@ export function registeredTurnModel(provider, binding, profileType, host, initia
                 yield { type: 'provider_warning', warning: restored.warning };
             }
             const call = guardedCall(provider, binding, profileType, host, req);
-            const { terminal, failed, pending, reasoning, outputs, wireCallIds } = yield* consumeModelStep(call.complete(protocolRequest(req, protocol, restored)), req.signal);
+            const { terminal, failed, pending, reasoning, text, structured, wireCallIds } = yield* consumeModelStep(call.complete(protocolRequest(req, protocol, restored)), req.signal);
             throwIfAborted(req.signal);
             if (!terminal) {
                 yield { type: 'done', stop: { kind: failed ? 'provider_error' : 'stream_incomplete' } };
@@ -501,8 +501,6 @@ export function registeredTurnModel(provider, binding, profileType, host, initia
                 yield { type: 'done', stop: terminal.stop };
                 return;
             }
-            if (pending.length)
-                outputs.push(historyToolCalls(pending.map((entry, index) => (index === 0 ? { ...entry, reasoning } : entry))));
             const history = [...(req.history ?? [])];
             if (req.input.length)
                 history.push(req.input.every((part) => part.type === 'text')
@@ -513,7 +511,11 @@ export function registeredTurnModel(provider, binding, profileType, host, initia
                     : { role: 'user', parts: req.input });
             const checkpoint = await checkpointProviderState(provider, binding, call.keySlot(), terminal.state, [
                 ...history,
-                ...(pending.length ? outputs.filter((message) => message.tool_calls) : outputs),
+                ...stepReplyMessages({
+                    text,
+                    structured,
+                    calls: pending.map((entry, index) => (index === 0 ? { ...entry, reasoning } : entry)),
+                }),
             ], { ...restored.wireCallIds, ...wireCallIds });
             active = checkpoint;
             for (const entry of pending)

package/esm/src/kernel/schema.d.ts

@@ -126,7 +126,7 @@ export declare const AWAITING_USER_INPUT_KINDS: readonly ["confirm", "choice", "
 /** One of {@linkcode AWAITING_USER_INPUT_KINDS}. */
 export type AwaitingUserInputKind = (typeof AWAITING_USER_INPUT_KINDS)[number];
 /** Why a stage handler's result was partly or wholly ignored. */
-export declare const STAGE_APPLY_WARNING_CODES: readonly ["affordance_not_allowed", "inject_not_allowed", "inject_rejected_max_steps", "inject_invalid_messages", "inject_id_invalid", "deny_invalid", "confirm_invalid", "mutate_invalid", "label_failed_invalid", "abort_invalid", "wait_for_invalid", "unknown_field", "result_invalid"];
+export declare const STAGE_APPLY_WARNING_CODES: readonly ["affordance_not_allowed", "inject_not_allowed", "inject_rejected_max_steps", "inject_invalid_messages", "inject_id_invalid", "inject_released_invalid", "deny_invalid", "confirm_invalid", "mutate_invalid", "label_failed_invalid", "abort_invalid", "wait_for_invalid", "unknown_field", "result_invalid"];
 /** One of {@linkcode STAGE_APPLY_WARNING_CODES}. */
 export type StageApplyWarningCode = (typeof STAGE_APPLY_WARNING_CODES)[number];
 /** The `status` of a tool output that asks the user a question. */

package/esm/src/kernel/schema.js

@@ -140,6 +140,7 @@ export const STAGE_APPLY_WARNING_CODES = [
     'inject_rejected_max_steps',
     'inject_invalid_messages',
     'inject_id_invalid',
+    'inject_released_invalid',
     'deny_invalid',
     'confirm_invalid',
     'mutate_invalid',
@@ -513,7 +514,7 @@ export const PROFILE_FIELDS = withScopeAndPresence({
     'models.*.protocol': field('string', 'The API shape this model is spoken to in.'),
     'models.*.provider': field('string', 'The service that runs the model or routes requests to one, such as Gemini or OpenRouter. Its registration supplies the endpoint and authentication.'),
     'models.*.keySlot': field('KeySlot', "The key slot this model's calls are signed with, instead of the provider's. Use it to bill one model to a different key. Absent: the provider's primary slot."),
-    'models.*.fallbackKeySlot': field('KeySlot', "The key slot tried once after a rate limit on the primary slot, instead of the provider's fallback. Must differ from the primary slot. Absent: the provider's fallback slot, if it has one."),
+    'models.*.fallbackKeySlot': field('KeySlot', "The key slot tried once after a rate limit or a busy model on the primary slot, instead of the provider's fallback. Must differ from the primary slot. Absent: the provider's fallback slot, if it has one."),
     'models.*.options': field('JsonObject', "Settings only this model's protocol has, such as a task type or vector size. Each is checked when the profile loads. Any left out keep the provider's default."),
     providerContinuation: field('ProviderContinuationPolicy', 'Who holds the conversation a saved provider state continues.'),
     'providerContinuation.history': field("'host' | 'stateless' | 'provider'", 'Who holds the conversation a checkpoint continues: the host passes history back, the provider keeps it and the checkpoint travels alone, or the profile is stateless and every request stands alone.', ['host', 'stateless', 'provider']),

package/esm/src/kernel/stages.d.ts

@@ -55,6 +55,13 @@ export interface StageResult {
      * non-string id refuses the inject whole.
      */
     injectId?: string;
+    /**
+     * With `inject`, at `post_tool` or `before_end`: how many characters of the attempt's reply text,
+     * as the turn gave it, the user already has. The rest is a draft they never got: it leaves the
+     * turn's history and its reply when the inject lands, so the model answers everything afresh
+     * after the part they have. Left out, they have all of it.
+     */
+    released?: number;
     abort?: boolean | {
         reason?: string;
     };
@@ -105,6 +112,8 @@ export interface StageApplyInput {
 export interface InjectUnit {
     id?: string;
     messages: TurnHistoryMessage[];
+    /** {@linkcode StageResult.released}: the reply text the user has when this inject lands. */
+    released?: number;
 }
 /** A stage handler's result after validation: the parts the turn will act on. */
 export interface StageApplyOutput {
@@ -139,16 +148,18 @@ export type StageEventExtra = {
     injected?: {
         id: string;
     }[];
+    released?: number;
 };
 /** Build a stream `stage` event. Unknown extra keys are not copied. */
 export declare function stageEventFields(stage: TurnStage, extra?: Partial<StageEventExtra>): TurnEventOf<'stage'>;
 export declare function injectMessages(units: readonly InjectUnit[]): TurnHistoryMessage[];
 /**
  * The `stage` event recording that `units` landed, naming the ones the host
- * named; `undefined` when none was named. Emit it where the messages land,
- * never before: an inject that never lands is never reported.
+ * named, and the reply text the user has when they dropped a draft (`released`);
+ * `undefined` when there is neither. Emit it where the messages land, never
+ * before: an inject that never lands is never reported.
  */
-export declare function injectedStageEvent(stage: TurnStage, units: readonly InjectUnit[], extra?: Pick<StageEventExtra, 'callId' | 'toolName'>): TurnEventOf<'stage'> | undefined;
+export declare function injectedStageEvent(stage: TurnStage, units: readonly InjectUnit[], extra?: Pick<StageEventExtra, 'callId' | 'toolName' | 'released'>): TurnEventOf<'stage'> | undefined;
 export declare function injectWouldExceedMaxSteps(stepCount: number, maxSteps: number | undefined): boolean;
 export interface RunStageArgs extends StageCallBag {
     stage: TurnStage;

package/esm/src/kernel/stages.js

@@ -26,7 +26,7 @@ export const STAGE_AFFORDANCE_MATRIX = Object.freeze({
     before_end: Object.freeze(['inject', 'abort']),
     post_turn: Object.freeze([]),
 });
-const STAGE_RESULT_KEYS = new Set([...STAGE_AFFORDANCES, 'injectId']);
+const STAGE_RESULT_KEYS = new Set([...STAGE_AFFORDANCES, 'injectId', 'released']);
 /** True when the affordance is physically allowed at `stage` (ignores inject gate). */
 export function stageAllowsAffordance(stage, affordance) {
     return STAGE_AFFORDANCE_MATRIX[stage].includes(affordance);
@@ -102,15 +102,26 @@ function coerceHistoryMessages(raw, warnings) {
     }
     return out.length > 0 ? out : undefined;
 }
+/** `released` as a count of characters; anything else is a warning, and the user has the whole reply. */
+function injectReleased(raw, warnings) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === 'number' && Number.isInteger(raw) && raw >= 0)
+        return raw;
+    warn(warnings, 'inject_released_invalid', 'released', 'released must be a whole number of characters, 0 or more; ignored');
+    return undefined;
+}
 /** The inject's messages under its id; an unusable id refuses the inject whole. */
 function injectUnit(result, warnings) {
     const messages = coerceHistoryMessages(result.inject, warnings);
     if (!messages)
         return undefined;
+    const released = injectReleased(result.released, warnings);
+    const unit = { messages, ...(released === undefined ? {} : { released }) };
     if (result.injectId === undefined)
-        return { messages };
+        return unit;
     if (typeof result.injectId === 'string' && result.injectId.trim()) {
-        return { id: result.injectId, messages };
+        return { id: result.injectId, ...unit };
     }
     warn(warnings, 'inject_id_invalid', 'injectId', 'injectId must be a non-empty string; inject refused');
     return undefined;
@@ -120,6 +131,9 @@ function applyInjectField(result, input, out) {
         if (result.injectId !== undefined) {
             warn(out.warnings, 'inject_id_invalid', 'injectId', 'injectId without inject ignored'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
+        if (result.released !== undefined) {
+            warn(out.warnings, 'inject_released_invalid', 'released', 'released without inject ignored'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
         return;
     }
     const { stage, injectAllowed, injectWouldExceedMaxSteps } = input;
@@ -305,6 +319,8 @@ export function stageEventFields(stage, extra) {
         event.stop = extra.stop;
     if (extra.injected !== undefined)
         event.injected = extra.injected;
+    if (extra.released !== undefined)
+        event.released = extra.released;
     return event;
 }
 export function injectMessages(units) {
@@ -312,14 +328,15 @@ export function injectMessages(units) {
 }
 /**
  * The `stage` event recording that `units` landed, naming the ones the host
- * named; `undefined` when none was named. Emit it where the messages land,
- * never before: an inject that never lands is never reported.
+ * named, and the reply text the user has when they dropped a draft (`released`);
+ * `undefined` when there is neither. Emit it where the messages land, never
+ * before: an inject that never lands is never reported.
  */
 export function injectedStageEvent(stage, units, extra) {
     const injected = units.flatMap((unit) => (unit.id === undefined ? [] : [{ id: unit.id }]));
-    if (injected.length === 0)
+    if (injected.length === 0 && extra?.released === undefined)
         return undefined;
-    return stageEventFields(stage, { ...extra, injected });
+    return stageEventFields(stage, { ...extra, ...(injected.length > 0 ? { injected } : {}) });
 }
 export function injectWouldExceedMaxSteps(stepCount, maxSteps) {
     if (maxSteps === undefined || maxSteps <= 0)

package/esm/src/kernel/tools/memory-execution.d.ts

@@ -0,0 +1,11 @@
+import { type ToolExecutionCoordinator } from './operation.js';
+export interface MemoryToolExecutionOptions {
+    /** The most operations it holds. A full coordinator refuses dispatch and keeps what it has. */
+    maxOperations?: number;
+}
+/**
+ * A coordinator that keeps claims and outcomes in process memory.
+ * Use one per turn or per process when nothing needs to resume after a restart.
+ * A host that resumes across requests or workers supplies its own `ToolExecutionCoordinator`.
+ */
+export declare function createMemoryToolExecution(options?: MemoryToolExecutionOptions): ToolExecutionCoordinator;

package/esm/src/kernel/tools/memory-execution.js

@@ -0,0 +1,59 @@
+import { operationUnavailable, } from './operation.js';
+/** How many operations a memory coordinator tracks before it refuses new ones. */
+const DEFAULT_MEMORY_EXECUTION_LIMIT = 256;
+/**
+ * A coordinator that keeps claims and outcomes in process memory.
+ * Use one per turn or per process when nothing needs to resume after a restart.
+ * A host that resumes across requests or workers supplies its own `ToolExecutionCoordinator`.
+ */
+export function createMemoryToolExecution(options = {}) {
+    const limit = options.maxOperations ?? DEFAULT_MEMORY_EXECUTION_LIMIT;
+    const records = new Map();
+    // invariant: callId and operationId never contain a NUL byte, so the joined key is unambiguous.
+    const keyOf = (operation) => `${operation.callId}\0${operation.operationId}`;
+    const known = (operation) => {
+        const record = records.get(keyOf(operation));
+        if (!record)
+            return undefined;
+        if (record.state === 'settled')
+            return { kind: 'settled', outcome: record.outcome };
+        return { kind: record.state };
+    };
+    const holds = (claim) => {
+        const record = records.get(keyOf(claim));
+        return record?.state === 'running' && record.claimToken === claim.claimToken;
+    };
+    return {
+        lookup: (operation) => Promise.resolve(known(operation)),
+        begin: (operation) => {
+            const earlier = known(operation);
+            if (earlier)
+                return Promise.resolve(earlier);
+            if (records.size >= limit)
+                return Promise.reject(operationUnavailable());
+            const claimToken = crypto.randomUUID();
+            records.set(keyOf(operation), { state: 'running', claimToken });
+            return Promise.resolve({ kind: 'acquired', claimToken });
+        },
+        settle: (claim, outcome) => {
+            if (!holds(claim))
+                return Promise.reject(operationUnavailable());
+            records.set(keyOf(claim), { state: 'settled', outcome });
+            return Promise.resolve();
+        },
+        settleNotStarted: (operation, outcome) => {
+            if (records.has(keyOf(operation)))
+                return Promise.reject(operationUnavailable());
+            if (records.size >= limit)
+                return Promise.reject(operationUnavailable());
+            records.set(keyOf(operation), { state: 'settled', outcome });
+            return Promise.resolve();
+        },
+        markUncertain: (claim) => {
+            if (!holds(claim))
+                return Promise.reject(operationUnavailable());
+            records.set(keyOf(claim), { state: 'uncertain' });
+            return Promise.resolve();
+        },
+    };
+}

package/esm/src/kernel/tools/operation.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 import { TheoremError } from '../../guardrails/error.js';
 import { type JsonObject, type JsonValue } from '../json.js';
+import type { InjectUnit } from '../stages.js';
 import type { GateReference, TurnEventOf } from '../turn-events.js';
-import type { TurnHistoryMessage } from '../types.js';
 import type { ModelToolResult, PageAnswer, ToolFailure } from './types.js';
 export type TerminalToolEvent = TurnEventOf<'tool'> & {
     tool: Extract<TurnEventOf<'tool'>['tool'], {
@@ -43,10 +43,7 @@ export interface ToolOperationOutcome {
         aborted?: boolean | {
             reason?: string;
         };
-        pendingInject?: {
-            id?: string;
-            messages: TurnHistoryMessage[];
-        }[];
+        pendingInject?: InjectUnit[];
     };
 }
 export type ToolOperationUncertainty = 'execution_interrupted' | 'settlement_write_failed' | 'worker_lost';

package/esm/src/kernel/tools/operation.js

@@ -64,7 +64,11 @@ export const toolOperationOutcomeSchema = z.strictObject({
         callNotStarted: z.boolean().optional(),
         aborted: z.union([z.boolean(), z.strictObject({ reason: z.string().optional() })]).optional(),
         pendingInject: z
-            .array(z.strictObject({ id: z.string().optional(), messages: z.array(turnHistoryMessageSchema) }))
+            .array(z.strictObject({
+            id: z.string().optional(),
+            messages: z.array(turnHistoryMessageSchema),
+            released: z.number().int().nonnegative().optional(),
+        }))
             .optional(),
     }),
 });

package/esm/src/kernel/turn-events.d.ts

@@ -690,6 +690,12 @@ export type TurnEvent = {
     injected?: {
         id: string;
     }[];
+    /**
+     * An inject at this stage dropped a draft the user never got: of the reply text since the
+     * turn began or its last `attempt`, only the first `released` characters stay the reply.
+     * {@linkcode keptReply} drops the rest.
+     */
+    released?: number;
 }
 /**
  * A tool call the model is still writing: the next piece of its arguments' JSON text, in order,
@@ -770,7 +776,8 @@ export declare const TURN_EVENT_SCHEMAS: {
 };
 /**
  * `events` without the replies a retry threw away: each `attempt` drops the text, media and
- * structured output before it, back to the turn's start or its last `done`. Tool calls, thoughts
- * and everything else stay, since they happened.
+ * structured output before it, back to the turn's start or its last `done`. A `stage` event with
+ * `released` keeps only that much of the reply's text, and drops what followed it. Tool calls,
+ * thoughts and everything else stay, since they happened.
  */
 export declare function keptReply(events: readonly TurnEvent[]): TurnEvent[];