@theoremjs/agents 0.3.1 → 0.3.3

package/README.md

@@ -21,6 +21,7 @@
   <a href="https://jsr.io/@theoremjs/agents/score"><img src="https://jsr.io/badges/@theoremjs/agents/score" alt="JSR score"></a>
   <a href="https://www.npmjs.com/package/@theoremjs/agents"><img src="https://img.shields.io/npm/v/@theoremjs/agents?logo=npm&label=npm&color=cb3837" alt="npm"></a>
   <a href="https://github.com/masudl-hub/theoremai/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+  <a href="https://deepwiki.com/masudl-hub/theoremai"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
 <p align="center">
@@ -385,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.
@@ -402,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. |
@@ -441,7 +446,7 @@ Named exports from the root barrel (same symbols hosts get from `@theoremjs/agen
 | Guardrail vocabulary | `AdvisoryLevel`, `TrustLevel`, `GuardrailStage`, `Severity`, `GuardrailHit`, `Verdict`, `GuardrailAction`, `GuardrailContext`, `GuardrailEvent`, `guardrailEventSchema`, `OutboundPayload`, `Provenance`, `ToolOrigin`, `ScanText`, `BlockedReplySpec`, `BlockedReplyOnBlock`, `ResolvedBlockedReply`, `UrlAllow`, `NameAllow`, `UrlDetector`, `ResolvedAllow`, `ProfileGuardrailsSpec`, `HostGuardrailsSpec`, `NetworkGuardrailSpec`, `QuotaGuardrailSpec`, `ResolvedGuardrailPolicy`, `SensitiveGroup`, `SensitiveSelection`, `SensitiveSwitches`, `GuardedToolText`, `TurnTaint`, `TaintGate`, `TaintGuardrailSpec`, `TurnDestinations`, `DestinationGate`, `DestinationVerdict`, `TRUST_LEVELS`, `GUARDRAIL_STAGES`, `SEVERITIES`, `TOOL_ORIGINS` |
 | Guardrail policy | `resolveGuardrailPolicy`, `BLOCKED_REPLY_ON_BLOCK`, `hitRules`, `EGRESS_RULES` |
 | Tool boundary | `guardToolResult`, `guardToolFailureText`, `inspectToolArguments`, `toolCallEvent`, `wrapToolData`, `isRemoteOrigin`, `composeToolText`, `checkTaintGate`, `recordTaint`, `isTainted`, `isSuspicious`, `checkDestinationGate`, `turnDestinations`, `addGivenDestinations`, `addHistoryDestinations`, `addRequestDestinations`, `addResultDestinations`, `DESTINATION_GATES`, `directives`, `advisoryLevel`, `DIRECTIVE_SIGNALS`, `Directive`, `DirectiveSignal`, `ADVISORY_LEVELS`, `TOOL_CLOSE`, `TOOL_ORIGINS`, `TAINT_GATES`, `InspectedToolArguments`, `textForScan`, `scanTextOf` |
-| Quota | `QuotaSlotStatus`, `clientIp`, `quotaExhausted`, `releaseSlot`, `resetSlots`, `skipQuota`, `takeSlot` |
+| Quota | `QuotaSlotStatus`, `clientIp`, `quotaBusy`, `quotaExhausted`, `releaseSlot`, `resetSlots`, `skipQuota`, `takeSlot` |
 | Labels | `LABEL_KEYS`, `LabelKey`, `CLIENT_LABEL_KEYS`, `ClientLabelKey`, `LabelOverrides`, `LabelParams`, `labelDefault`, `labelText`, `overrideLabels`, `resetLabels` |
 | Sanitize | `sanitizeProjectId`, `sanitizeTurnRequest`, `sanitizeTurnRequestWithEvents`, `SanitizedTurnRequest`, `guardrailFromHits`, `guardrailFromVerdict`, `guardrailTurnEvent`, `projectGuardrailTurnEvent`, `hitFromSpan`, `projectGuardrailEvent` |
 | Canary / egress | `mintCanary`, `bindCanary`, `wrapUserData`, `scanTextForCanaryLeak`, `scanTextForPromptEcho`, `PROMPT_ECHO_WORDS`, `redactCanary`, `OMIT_CANARY`, `createCanaryStreamGate`, `eventHasCanary`, `createCanaryGateSession`, `filterCanaryGatedEvents`, `CanaryGateResult`, `CanaryGateSession`, `CanaryStreamGate`, `GivenUrls`, `createOutboundProgressiveGate`, `createProgressiveYieldGate`, `createLiveOutboundGateSession`, `processLiveOutboundBatch`, `finalizeLiveOutboundTurn`, `abortLiveOutboundTurn`, `LiveHeldOutput`, `LiveOutboundBatchResult`, `LiveOutboundGateSession`, `ProgressiveYieldGate`, `ProgressiveYieldGateOptions`, `ProgressiveYieldResult` |

package/esm/mod.d.ts

@@ -19,7 +19,7 @@ export { ADVISORY_LEVELS, abortLiveOutboundTurn, addGivenDestinations, addHistor
 export type { DnsOverHttpsOptions, GuardedFetchOptions, ResolveHost, } from './src/guardrails/network.js';
 export { assertSafeUrl, dnsOverHttpsResolver, fetchGuarded, isLocalhostName, isPrivateOrLocalAddress, } from './src/guardrails/network.js';
 export type { QuotaSlotStatus } from './src/guardrails/quota.js';
-export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
+export { clientIp, quotaBusy, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
 export type { SanitizedTurnRequest } from './src/guardrails/sanitize.js';
 export { sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, } from './src/guardrails/sanitize.js';
 export type { ProviderStateRebuilt } from './src/kernel/checkpoint.js';
@@ -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

@@ -14,7 +14,7 @@ export { hitFromSpan, projectGuardrailEvent, } from './src/guardrails/hits.js';
 export { CLIENT_LABEL_KEYS, LABEL_KEYS, labelDefault, labelText, overrideLabels, resetLabels, } from './src/guardrails/labels.js';
 export { ADVISORY_LEVELS, abortLiveOutboundTurn, addGivenDestinations, addHistoryDestinations, addRequestDestinations, addResultDestinations, BLOCKED_REPLY_ON_BLOCK, bindCanary, checkDestinationGate, checkTaintGate, composeToolText, createCanaryGateSession, createCanaryStreamGate, createLiveOutboundGateSession, createOutboundProgressiveGate, createProgressiveYieldGate, DESTINATION_GATES, DIRECTIVE_SIGNALS, directives, EGRESS_RULES, eventHasCanary, filterCanaryGatedEvents, finalizeLiveOutboundTurn, GUARDRAIL_STAGES, guardToolFailureText, guardToolResult, hitRules, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, mintCanary, OMIT_CANARY, processLiveOutboundBatch, recordTaint, redactCanary, resolveGuardrailPolicy, SEVERITIES, scanTextForCanaryLeak, scanTextOf, TAINT_GATES, TOOL_CLOSE, TOOL_ORIGINS, TRUST_LEVELS, textForScan, toolCallEvent, turnDestinations, wrapToolData, wrapUserData, } from './src/guardrails/mod.js';
 export { assertSafeUrl, dnsOverHttpsResolver, fetchGuarded, isLocalhostName, isPrivateOrLocalAddress, } from './src/guardrails/network.js';
-export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
+export { clientIp, quotaBusy, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
 export { sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, } from './src/guardrails/sanitize.js';
 export { historyHash, providerCheckpointSchema, providerContinuationSchema, providerWarningSchema, } from './src/kernel/checkpoint.js';
 export { clearProfiles, compactHistory, getProfile, getProvider, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listProtocols, listProviders, listTools, projectProfile, registerProfile, registerProfiles, registerProvider, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTool, runToolStep, runTurn, } from './src/kernel/default-scope.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/guardrails/error.d.ts

@@ -10,7 +10,7 @@ declare function isTimeoutError(err: unknown): boolean;
 declare function throwIfAborted(signal?: AbortSignal): void;
 /** Anything that is not a `TheoremError` or an abort escaped every boundary that names kinds: a THEOREM bug. */
 declare function errorKind(err: unknown): ErrorKind;
-/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 429 `rate_limit`; 500 and above `unavailable`; the rest `unsupported`. */
+/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 429 `rate_limit`; 503 and 529 (overloaded) `busy`; 500 and above `unavailable`; the rest `unsupported`. */
 declare function kindOfHttpStatus(status: number): ErrorKind;
 /** The named reasons an error carries, one line each, in the profile's wording. */
 declare function errorCopyText(copy: ErrorCopies, labels?: LabelOverrides): string;

package/esm/src/guardrails/error.js

@@ -32,7 +32,7 @@ function errorKind(err) {
         return 'cancelled';
     return 'internal';
 }
-/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 429 `rate_limit`; 500 and above `unavailable`; the rest `unsupported`. */
+/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 429 `rate_limit`; 503 and 529 (overloaded) `busy`; 500 and above `unavailable`; the rest `unsupported`. */
 function kindOfHttpStatus(status) {
     if (status === 401 || status === 402 || status === 403)
         return 'auth';
@@ -40,6 +40,8 @@ function kindOfHttpStatus(status) {
         return 'timeout';
     if (status === 429)
         return 'rate_limit';
+    if (status === 503 || status === 529)
+        return 'busy';
     if (status >= 500)
         return 'unavailable';
     return 'unsupported';

package/esm/src/guardrails/labels.d.ts

@@ -1,7 +1,7 @@
 /** Values that fill a label template's `{param}` placeholders. */
 export type LabelParams = Record<string, string | number>;
 /** Keys are stable API. */
-export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "input.too_long", "attachments.limits_unconfigured", "quota.exhausted", "error.config", "error.request", "error.input", "error.action", "error.auth", "error.rate_limit", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "compaction.request", "compaction.tool_call", "compaction.tool_result", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.injection", "detect.hint.tool_instructions", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
+export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "input.too_long", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "compaction.request", "compaction.tool_call", "compaction.tool_result", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.injection", "detect.hint.tool_instructions", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
 /** One of {@linkcode LABEL_KEYS}. */
 export type LabelKey = (typeof LABEL_KEYS)[number];
 /**
@@ -10,7 +10,7 @@ export type LabelKey = (typeof LABEL_KEYS)[number];
  * puts into history. Only these overrides travel to the browser; the rest
  * (repair prompts, canary, taint, egress) stay on the host.
  */
-export declare const CLIENT_LABEL_KEYS: readonly ["attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "input.too_long", "attachments.limits_unconfigured", "detect.blocked", "error.config", "error.request", "error.input", "error.action", "error.auth", "error.rate_limit", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "session.abandon_gated", "session.tool_denied", "session.sign_in", "session.gate_expired", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "tool.awaiting_user", "tool.completed_hidden", "tool.execution_uncertain", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "composer.model", "composer.effort"];
+export declare const CLIENT_LABEL_KEYS: readonly ["attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "input.too_long", "attachments.limits_unconfigured", "detect.blocked", "error.config", "error.request", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "session.abandon_gated", "session.tool_denied", "session.sign_in", "session.gate_expired", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "tool.awaiting_user", "tool.completed_hidden", "tool.execution_uncertain", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "composer.model", "composer.effort"];
 /** One of {@linkcode CLIENT_LABEL_KEYS}. */
 export type ClientLabelKey = (typeof CLIENT_LABEL_KEYS)[number];
 /** Host-supplied replacement templates, `{param}` placeholders included. */

package/esm/src/guardrails/labels.js

@@ -67,12 +67,14 @@ export const LABEL_KEYS = [
     'input.too_long',
     'attachments.limits_unconfigured',
     'quota.exhausted',
+    'quota.busy',
     'error.config',
     'error.request',
     'error.input',
     'error.action',
     'error.auth',
     'error.rate_limit',
+    'error.busy',
     'error.unsupported',
     'error.unavailable',
     'error.bad_response',
@@ -229,6 +231,7 @@ export const CLIENT_LABEL_KEYS = [
     'error.action',
     'error.auth',
     'error.rate_limit',
+    'error.busy',
     'error.unsupported',
     'error.unavailable',
     'error.bad_response',
@@ -382,12 +385,14 @@ const DEFAULTS = {
     'quota.exhausted': (params) => params.perDay === 1
         ? "You've reached today's limit of 1 message."
         : `You've reached today's limit of ${String(params.perDay)} messages.`,
+    'quota.busy': 'Sorry, your last message is still being answered. Please wait for it to finish.',
     'error.config': 'Sorry, something went wrong.',
     'error.request': 'Sorry, something went wrong.',
     'error.input': "Sorry, that file can't be used here.",
     'error.action': "Sorry, that isn't available here.",
     'error.auth': "Sorry, the assistant can't connect at the moment.",
     'error.rate_limit': 'Sorry, the usage limit has been reached. Please try again later.',
+    'error.busy': 'Sorry, the model is busy right now. Please try again in a moment.',
     'error.unsupported': "Sorry, that isn't something the assistant can do.",
     'error.unavailable': "Sorry, the model isn't available at the moment. Please try again shortly.",
     'error.bad_response': "Sorry, that reply didn't come through properly. Please try again.",
@@ -592,14 +597,16 @@ export const LABEL_NOTES = {
     'input.too_long': 'Shown to the user when one text a turn sends, such as the message or a text file, is longer than Theorem reads. Takes {maxChars}.',
     'attachments.limits_unconfigured': 'Shown to the user who sends a file to an agent whose file limits are not set.',
     'quota.exhausted': 'Shown to the user who has used up the daily message cap. Takes {perDay}.',
+    'quota.busy': 'Shown to the user who sends a message while their last one is still being answered (`quotaBusy`).',
     'error.config': "Shown to the user when the turn fails because the agent's profile, a tool, or a schema is set up wrong. Takes {tool} when one step failed.",
     'error.request': 'Shown to the user when the turn fails because the host called Theorem wrongly. Takes {tool} when one step failed.',
     'error.input': 'Shown to the user when they sent something the agent does not accept. Takes {tool} when one step failed.',
     'error.action': 'Shown to the user when they asked for something the agent does not allow. Takes {tool} when one step failed.',
     'error.auth': 'Shown to the user when a model key is missing or rejected, or its account cannot be billed. Takes {tool} when one step failed.',
     'error.rate_limit': 'Shown to the user when the model provider reports too many requests, or a quota is used up. Takes {tool} when one step failed.',
+    'error.busy': 'Shown to the user when the model provider is up but too busy for the call (HTTP 503 or 529). Takes {tool} when one step failed.',
     'error.unsupported': 'Shown to the user when the model or its route cannot serve the request. Takes {tool} when one step failed.',
-    'error.unavailable': 'Shown to the user when the model provider is down or overloaded. Takes {tool} when one step failed.',
+    'error.unavailable': 'Shown to the user when the model provider is down. Takes {tool} when one step failed.',
     'error.bad_response': 'Shown to the user when the model provider answers with something that cannot be used. Takes {tool} when one step failed.',
     'error.network': 'Shown to the user when the request never reached the model provider. Takes {tool} when one step failed.',
     'error.timeout': 'Shown to the user when the model takes longer than the host allows. Takes {tool} when one step failed.',

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

@@ -36,7 +36,7 @@ export type { ProgressiveYieldGate, ProgressiveYieldGateOptions, ProgressiveYiel
 export { createOutboundProgressiveGate, createProgressiveYieldGate } from './progressive-yield.js';
 export { PROMPT_ECHO_WORDS, scanTextForPromptEcho } from './prompt-echo.js';
 export type { QuotaSlotStatus } from './quota.js';
-export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
+export { clientIp, quotaBusy, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
 export type { GuardrailRule } from './rules.js';
 export { DETECT_RULES, detectRule, EGRESS_RULES, NETWORK_RULES, TOOL_RULES, } from './rules.js';
 export type { SanitizedTurnRequest } from './sanitize.js';

package/esm/src/guardrails/mod.js

@@ -23,7 +23,7 @@ export { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutbo
 export { resolveGuardrailPolicy } from './policy.js';
 export { createOutboundProgressiveGate, createProgressiveYieldGate } from './progressive-yield.js';
 export { PROMPT_ECHO_WORDS, scanTextForPromptEcho } from './prompt-echo.js';
-export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
+export { clientIp, quotaBusy, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
 export { DETECT_RULES, detectRule, EGRESS_RULES, NETWORK_RULES, TOOL_RULES, } from './rules.js';
 export { sanitizeHistory, sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, } from './sanitize.js';
 export { sensitiveSpans } from './sensitive.js';

package/esm/src/guardrails/quota.d.ts

@@ -15,7 +15,9 @@ declare function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotS
 declare function releaseSlot(profile: Profile, ip: string): void;
 /** `undefined` when the profile has no quota configured. */
 declare function quotaExhausted(profile: Profile): TheoremError | undefined;
+/** A turn already holds this client's slot (`takeSlot` returned `busy`): worded by the labels' `quota.busy`. */
+declare function quotaBusy(profile: Profile): TheoremError;
 /** Clears all process-local quota counters; intended for tests or host resets. */
 declare function resetSlots(): void;
 export type { QuotaSlotStatus };
-export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };
+export { clientIp, quotaBusy, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/guardrails/quota.js

@@ -73,8 +73,13 @@ function quotaExhausted(profile) {
     return new TheoremError('rate_limit', `${profile.id} used its daily quota of ${quota.perDay} turns`, // labels-exempt: internal diagnostic; the user reads the copy key
     { copy: { key: 'quota.exhausted', params: { perDay: quota.perDay } } });
 }
+/** A turn already holds this client's slot (`takeSlot` returned `busy`): worded by the labels' `quota.busy`. */
+function quotaBusy(profile) {
+    return new TheoremError('rate_limit', `${profile.id} is already running a turn for this client`, // labels-exempt: internal diagnostic; the user reads the copy key
+    { copy: { key: 'quota.busy' } });
+}
 /** Clears all process-local quota counters; intended for tests or host resets. */
 function resetSlots() {
     slots.clear();
 }
-export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };
+export { clientIp, quotaBusy, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/guardrails/theorem-error.d.ts

@@ -5,7 +5,7 @@ export type { ErrorCopies, ErrorCopy };
  * the builder in code and traces (`errorKind`, `error.type`), the user through
  * the kind's wording (`error.<kind>` in the labels).
  */
-export declare const ERROR_KINDS: readonly ["config", "request", "input", "action", "auth", "rate_limit", "unsupported", "unavailable", "bad_response", "network", "timeout", "safety", "blocked", "declined", "failed", "cancelled", "internal"];
+export declare const ERROR_KINDS: readonly ["config", "request", "input", "action", "auth", "rate_limit", "busy", "unsupported", "unavailable", "bad_response", "network", "timeout", "safety", "blocked", "declined", "failed", "cancelled", "internal"];
 /** Why an operation failed; the user's wording and the HTTP status follow from it. */
 export type ErrorKind = (typeof ERROR_KINDS)[number];
 /** Options for a `TheoremError`: the cause and, optionally, wording for the user. */

package/esm/src/guardrails/theorem-error.js

@@ -17,9 +17,11 @@ export const ERROR_KINDS = [
     'auth',
     /** Too many requests, or a quota used up. */
     'rate_limit',
+    /** The provider is up but too busy for the call; another key or a moment later may serve it. */
+    'busy',
     /** The model or route cannot serve this request. */
     'unsupported',
-    /** The provider is down or overloaded. */
+    /** The provider is down. */
     'unavailable',
     /** The provider answered with something that cannot be used. */
     'bad_response',

package/esm/src/host/reply.js

@@ -14,6 +14,7 @@ const STATUS_BY_KIND = {
     action: 403,
     auth: 401,
     rate_limit: HTTP_BUSY,
+    busy: 503,
     unsupported: 422,
     unavailable: 503,
     bad_response: 502,

package/esm/src/kernel/engine/decision.js

@@ -370,6 +370,7 @@ function decisionProviderError(error) {
         auth: 'authentication',
         rate_limit: 'rate_limited',
         network: 'network',
+        busy: 'unavailable',
         unavailable: 'unavailable',
         timeout: 'timeout',
         cancelled: 'cancelled',

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 };