@theoremjs/agents 0.3.2 → 0.3.3

package/README.md

@@ -386,6 +386,10 @@ The React server handler creates this service from its atomic session store.
 Use `toolInvocationHash` to compute the same canonical JSON digest as the coordinator.
 Use this evidence to check current resource access before you disclose a cached result.
 For browser effects, `PageToolExecution` issues a dispatch grant only after the claim.
+A page-answered tool needs a claim, so pass `execution` together with `pageExecution`.
+Use `createMemoryToolExecution` when one process serves the whole turn and nothing resumes after a restart.
+It keeps claims and outcomes in memory. Its `MemoryToolExecutionOptions` set `maxOperations` (256 by default), after which it refuses new operations.
+Write your own `ToolExecutionCoordinator` when a turn can resume on another worker.
 `PageToolDispatch` contains the grant ID and a pending `PageAnswer`. Host code supplies result delivery.
 The browser receives the final prepared arguments, then returns a result against that grant.
 Neither profile JSON nor a provider event can supply this service.
@@ -403,7 +407,7 @@ Import from the narrowest entrypoint that has what you need. Each row gives the
 
 | Entrypoint | Purpose |
 | :--- | :--- |
-| `jsr:@theoremjs/agents` / `@theoremjs/agents` | Main kernel API: profiles, schemas, runner, core types, provider constructors, declarative HTTP/MCP tool execution. |
+| `jsr:@theoremjs/agents` / `@theoremjs/agents` | Main kernel API: profiles, schemas, runner, core types, provider constructors, declarative HTTP/MCP tool execution, `createMemoryToolExecution`. |
 | `jsr:@theoremjs/agents/kernel` / `@theoremjs/agents/kernel` | Profile/turn types, tool catalog, `requireModelBinding`, thinking clamps over host model maps, OAuth 2.1 PKCE helpers (`createOAuthPkceFlow`, `exchangeOAuthPkce`, `refreshOAuthToken`). |
 | `jsr:@theoremjs/agents/providers` / `@theoremjs/agents/providers` | Protocols, first-party providers, provider definitions, sign-in helpers, and vault contracts. |
 | `jsr:@theoremjs/agents/guardrails` / `@theoremjs/agents/guardrails` | Sanitization, canary/egress gates, public error mapping, inbound injection/sensitive-data primitives. |

package/esm/mod.d.ts

@@ -65,6 +65,8 @@ export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResum
 export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './src/kernel/stop.js';
 export { authorizeToolReplay } from './src/kernel/tools/execute.js';
 export { GATE_DECISIONS, type GateDecision } from './src/kernel/tools/gate-answer.js';
+export type { MemoryToolExecutionOptions } from './src/kernel/tools/memory-execution.js';
+export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
 export type { CredentialQuery, McpProtocolVersion, McpRpcResponse, ToolRegistry, } from './src/kernel/tools/mod.js';
 export { askUserTool, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
 export type { BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationUncertainty, } from './src/kernel/tools/operation.js';

package/esm/mod.js

@@ -41,6 +41,7 @@ export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllo
 export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './src/kernel/stop.js';
 export { authorizeToolReplay } from './src/kernel/tools/execute.js';
 export { GATE_DECISIONS } from './src/kernel/tools/gate-answer.js';
+export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
 export { askUserTool, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
 export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './src/kernel/tools/operation.js';
 export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';

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

@@ -409,6 +409,9 @@ async function* executeSingleAttemptCycle(args) {
     // invariant: Fresh maxSteps budget per validation/egress attempt. before_end inject
     // re-entry inside this cycle still accumulates stepCount (do not reset there).
     state.stepCount = 0;
+    // invariant: The attempt's reply spans its before_end re-entries; only a new attempt starts it again.
+    state.replyText = '';
+    state.replyMessages = [];
     let latestStructured;
     for (;;) {
         state.attemptEvents = [];
@@ -439,6 +442,8 @@ async function* executeSingleAttemptCycle(args) {
             state,
             stage: 'before_end',
             step: Math.max(state.stepCount, 1),
+            reply: attempt.reply,
+            ...(attempt.replyAt === undefined ? {} : { replyAt: attempt.replyAt }),
             onStage: flow.currentReq.onStage,
             signal: flow.currentReq.signal,
             host: flow.currentGen.host,

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

@@ -1,5 +1,5 @@
 import { type InjectUnit, type StageApplyWarning, type StageCallBag, type StageContext, type StageHandler } from '../../stages.js';
-import type { Profile, ResolvedGeneration, TurnEvent, TurnStage } from '../../types.js';
+import type { Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnStage } from '../../types.js';
 import type { StepExecutionState } from './state.js';
 export interface ApplyTurnStageArgs extends StageCallBag {
     profile: Profile;
@@ -12,7 +12,16 @@ export interface ApplyTurnStageArgs extends StageCallBag {
     /** Another provider step would exceed maxSteps — reject inject. */
     injectWouldExceedMaxSteps?: boolean;
     host?: unknown;
+    /** `before_end`: the answer the model just wrote, which goes into turn history ahead of an inject. */
+    reply?: readonly TurnHistoryMessage[];
+    /** Where that answer's text begins in the attempt's reply. */
+    replyAt?: number;
 }
+/**
+ * A model call's reply joins turn history. Its text message, whose text begins at `at` in the
+ * attempt's reply, is the one an inject's drop cuts.
+ */
+export declare function recordReply(state: StepExecutionState, reply: readonly TurnHistoryMessage[], at: number | undefined): void;
 export interface ApplyTurnStageResult {
     abort?: boolean | {
         reason?: string;
@@ -20,7 +29,10 @@ export interface ApplyTurnStageResult {
     injectCount: number;
     warnings: StageApplyWarning[];
 }
-/** Sanitized stage injects extend portable history. */
+/**
+ * Sanitized stage injects extend portable history. An inject whose host says the user has only
+ * part of the attempt's reply drops the rest first (`StageResult.released`).
+ */
 export declare function applyStageInjects(state: StepExecutionState, stage: TurnStage, units: readonly InjectUnit[], extra?: {
     callId?: string;
     toolName?: string;

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

@@ -1,13 +1,87 @@
 import { throwIfAborted } from '../../../guardrails/error.js';
 import { injectedStageEvent, injectMessages, runStage, } from '../../stages.js';
 import { profileAllowsInject } from '../../stop.js';
-/** Sanitized stage injects extend portable history. */
+/**
+ * A model call's reply joins turn history. Its text message, whose text begins at `at` in the
+ * attempt's reply, is the one an inject's drop cuts.
+ */
+export function recordReply(state, reply, at) {
+    state.currentHistory.push(...reply);
+    if (at === undefined)
+        return;
+    for (const message of reply) {
+        if (typeof message.content === 'string')
+            state.replyMessages.push({ message, at });
+    }
+}
+/** The least of the reply text any of `units` says the user has; `undefined` when none says. */
+function releasedOf(units) {
+    const counts = units.flatMap((unit) => (unit.released === undefined ? [] : [unit.released]));
+    return counts.length > 0 ? Math.min(...counts) : undefined;
+}
+/** `events` less their last `count` characters of reply text, cut from the end. */
+function withoutTextTail(events, count) {
+    const out = [...events];
+    let left = count;
+    for (let index = out.length - 1; index >= 0 && left > 0; index -= 1) {
+        const event = out[index];
+        if (event?.type !== 'text')
+            continue;
+        const keep = Math.max(0, event.text.length - left);
+        left -= event.text.length - keep;
+        if (keep === 0)
+            out.splice(index, 1);
+        else
+            out[index] = { ...event, text: event.text.slice(0, keep) };
+    }
+    return out;
+}
+/**
+ * Drops the draft past the `released` characters of the attempt's reply the user has: from its
+ * history messages, from what the attempt gate reads, and from the reply. Returns `released` when
+ * a draft was dropped.
+ *
+ * invariant: A message that keeps no text leaves history; a call it made stays on its own message.
+ */
+function dropDraft(state, released) {
+    if (released === undefined || released >= state.replyText.length)
+        return undefined;
+    const dropped = state.replyText.length - released;
+    state.replyText = state.replyText.slice(0, released);
+    state.released = state.released.slice(0, Math.max(0, state.released.length - dropped));
+    state.attemptEvents = withoutTextTail(state.attemptEvents, dropped);
+    const kept = [];
+    for (const { message, at } of state.replyMessages) {
+        const text = typeof message.content === 'string' ? message.content : '';
+        const keep = text.slice(0, Math.max(0, released - at));
+        const index = state.currentHistory.indexOf(message);
+        if (index < 0)
+            continue;
+        if (keep) {
+            const cut = keep === text ? message : { ...message, content: keep };
+            state.currentHistory[index] = cut;
+            kept.push({ message: cut, at });
+        }
+        else
+            state.currentHistory.splice(index, 1);
+    }
+    state.replyMessages = kept;
+    return released;
+}
+/**
+ * Sanitized stage injects extend portable history. An inject whose host says the user has only
+ * part of the attempt's reply drops the rest first (`StageResult.released`).
+ */
 export function* applyStageInjects(state, stage, units, extra) {
     const inject = injectMessages(units);
     if (inject.length === 0)
         return 0;
+    const released = dropDraft(state, releasedOf(units));
     state.currentHistory.push(...inject);
-    const landed = injectedStageEvent(stage, units, extra);
+    const landed = injectedStageEvent(stage, units, {
+        ...extra,
+        ...(released === undefined ? {} : { released }),
+    });
     if (landed) {
         state.allEmittedEvents.push(landed);
         yield landed;
@@ -15,7 +89,7 @@ export function* applyStageInjects(state, stage, units, extra) {
     return inject.length;
 }
 export async function* applyTurnStage(args) {
-    const { profile, generation, state, onStage, host, ...call } = args;
+    const { profile, generation, state, onStage, host, reply, replyAt, ...call } = args;
     throwIfAborted(call.signal);
     const run = runStage({
         ...call,
@@ -33,6 +107,9 @@ export async function* applyTurnStage(args) {
         next = await run.next();
     }
     const out = next.value;
+    // why: The model goes on after the inject, so it reads the answer it wrote before it.
+    if (reply && injectMessages(out.inject).length > 0)
+        recordReply(state, reply, replyAt);
     return {
         abort: out.abort,
         injectCount: yield* applyStageInjects(state, call.stage, out.inject),

package/esm/src/kernel/engine/runner/state.d.ts

@@ -35,6 +35,19 @@ interface StepExecutionState {
     withheldVisible?: boolean;
     /** The reply text the stream's gate released this attempt, as it released it. */
     released: string;
+    /**
+     * The attempt's reply text as the host has it, across `before_end` re-entries, less any draft an
+     * inject dropped (`InjectUnit.released`).
+     */
+    replyText: string;
+    /**
+     * The messages in `currentHistory` that hold the model's text of `replyText`, each with where its
+     * text begins there: what an inject's drop cuts.
+     */
+    replyMessages: {
+        message: TurnHistoryMessage;
+        at: number;
+    }[];
     /** The canary opening the last provider call ended on, read in front of the next call's reply. */
     canaryCarry?: string;
     /** What the last provider call's thoughts ended on, read in front of the next call's thoughts. */

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

@@ -34,6 +34,8 @@ function openTurnState(args) {
         allEmittedEvents: args.allEmittedEvents ?? [],
         attemptEvents: [],
         released: '',
+        replyText: '',
+        replyMessages: [],
         givenUrls: givenUrlSets(),
         destinations: turnDestinations(),
         canaryGiven: false,

package/esm/src/kernel/engine/runner/steps.d.ts

@@ -1,5 +1,5 @@
 import type { BoundSystem } from '../../system-parts.js';
-import type { Profile, ResolvedGeneration, TurnEvent, TurnModel, TurnRequest } from '../../types.js';
+import type { Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnModel, TurnRequest } from '../../types.js';
 import { type StepExecutionState } from './state.js';
 declare function executeAttempt(args: {
     safe: TurnRequest;
@@ -10,5 +10,7 @@ declare function executeAttempt(args: {
     state: StepExecutionState;
 }): AsyncGenerator<TurnEvent, {
     latestStructured?: unknown;
+    reply: TurnHistoryMessage[];
+    replyAt?: number;
 }>;
 export { executeAttempt };

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.
@@ -175,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 } : {}),
@@ -220,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) {
@@ -250,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 } : {}),
     };
 }
@@ -357,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
@@ -371,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,
@@ -486,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.
@@ -506,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;
@@ -515,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/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',

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[];

package/esm/src/kernel/turn-events.js

@@ -464,6 +464,7 @@ const TURN_EVENTS = {
             .array(z.object({ id: z.string().regex(/\S/) }))
             .min(1)
             .optional(),
+        released: z.number().int().nonnegative().optional(),
     }),
     tool_draft: z.object({
         type: z.literal('tool_draft'),
@@ -522,10 +523,33 @@ function isReply(event) {
         event.type === 'structured' ||
         event.type === 'structured_draft');
 }
+/**
+ * `reply` with only its first `released` characters of text: the text past them, and every
+ * media and structured output that came after, are a draft the user never got.
+ */
+function cutReply(reply, released) {
+    const out = [];
+    let left = released;
+    for (const event of reply) {
+        if (!isReply(event))
+            out.push(event);
+        else if (event.type !== 'text') {
+            if (left > 0)
+                out.push(event);
+        }
+        else if (left > 0) {
+            const text = event.text.slice(0, left);
+            left -= text.length;
+            out.push(text === event.text ? event : { ...event, text });
+        }
+    }
+    return out;
+}
 /**
  * `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 function keptReply(events) {
     const kept = [];
@@ -535,6 +559,9 @@ export function keptReply(events) {
             const before = kept.splice(turnStart);
             kept.push(...before.filter((each) => !isReply(each)));
         }
+        if (event.type === 'stage' && event.released !== undefined) {
+            kept.push(...cutReply(kept.splice(turnStart), event.released));
+        }
         kept.push(event);
         if (event.type === 'done')
             turnStart = kept.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",