@theoremjs/agents 0.3.1 → 0.3.2

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">
@@ -441,7 +442,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';

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

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/steps.js

@@ -135,6 +135,7 @@ function releasesNow(event, control, state, buffer) {
 }
 // why: Every other kind is the provider's answer to the request itself (it refused a part, a key, a setting); the same call sent again gets the same answer.
 const PASSING_ERROR_KINDS = new Set([
+    'busy',
     'unavailable',
     'bad_response',
     'network',

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

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

package/esm/src/kernel/schema.js

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

package/esm/src/observability/trace-catalog.js

@@ -96,7 +96,8 @@ const ERROR_KIND_OPTIONS = {
     },
     rate_limit: { label: 'Rate limit', doc: 'Too many requests, or a quota used up.' },
     unsupported: { label: 'Unsupported', doc: 'The model or route cannot serve this request.' },
-    unavailable: { label: 'Unavailable', doc: 'The provider is down or overloaded.' },
+    busy: { label: 'Busy', doc: 'The provider is up but too busy for the call.' },
+    unavailable: { label: 'Unavailable', doc: 'The provider is down.' },
     bad_response: {
         label: 'Unusable response',
         doc: 'The provider answered with something that cannot be used.',

package/esm/src/providers/gemini/interactions-protocol.js

@@ -1,9 +1,8 @@
 import { z } from 'zod';
-import { kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
 import { asRecord } from '../../kernel/engine/record.js';
 import { jsonObjectSchema } from '../../kernel/json.js';
 import { defineProtocol, } from '../../kernel/protocols/mod.js';
-import { readGeminiApiError } from '../google/api-error.js';
+import { readGeminiApiError, statedOrStatusError } from '../google/api-error.js';
 import { googleBuiltins } from '../google/builtins.js';
 import { thoughtSignature, toInteractionsBody, } from '../google/interactions/framing.js';
 import { finalizeStructured, foldBody, foldPayload, missingMediaError, newStreamFold, openStepEvents, } from '../google/interactions/stream.js';
@@ -68,10 +67,8 @@ export const geminiInteractions = defineProtocol({
     continuation: { version: 1, schema: state, keyOptions: ['store', 'persistViaInteractionId'] },
     reasoning: thoughtSignature,
     error(failure) {
-        const kind = kindOfHttpStatus(failure.status);
         const record = asRecord(failure.body);
-        const stated = record ? readGeminiApiError(record) : null;
-        return new TheoremError(stated?.kind === 'auth' ? 'auth' : kind, stated?.message ?? `Gemini HTTP ${failure.status}`);
+        return statedOrStatusError(record ? readGeminiApiError(record) : null, failure.status, `Gemini HTTP ${failure.status}`);
     },
     create(context) {
         return {

package/esm/src/providers/google/api-error.d.ts

@@ -6,3 +6,5 @@ import { TheoremError } from '../../guardrails/error.js';
 export declare function readGeminiApiError(record: Record<string, unknown>): TheoremError | null;
 /** The kind is the HTTP status's, unless the body names a refused key. */
 export declare function readNonOkError(response: Response): Promise<TheoremError>;
+/** A non-OK reply's error: the body's own when it names a refused key, else the status's with the body's message. */
+export declare function statedOrStatusError(stated: TheoremError | null, status: number, fallback: string): TheoremError;

package/esm/src/providers/google/api-error.js

@@ -72,13 +72,15 @@ const BLOCKED_CODES = new Set([
  * codes (`malformed_function_call`, `no_image`, …) and any code Google adds later
  * are `bad_response`.
  */
-function kindOfNamedCode(code) {
+function namedCodeError(code, message) {
     if (code === 'cancelled')
-        return 'cancelled';
+        return new TheoremError('cancelled', message);
     if (BLOCKED_CODES.has(code))
-        return 'safety';
+        return new TheoremError('safety', message);
     const status = NAMED_CODE_STATUS[code];
-    return status === undefined ? 'bad_response' : kindOfHttpStatus(status);
+    return status === undefined
+        ? new TheoremError('bad_response', message)
+        : new TheoremError(kindOfHttpStatus(status), message);
 }
 /**
  * Interactions (SSE `error` rows, non-OK bodies) and Live (error frames) both send
@@ -90,28 +92,34 @@ export function readGeminiApiError(record) {
         return null;
     }
     const { code, message, status, details } = error;
-    const kind = refusesKey(details)
-        ? 'auth'
-        : typeof code === 'number' && code >= HTTP_STATUS_MIN && code <= HTTP_STATUS_MAX
-            ? kindOfHttpStatus(code)
-            : typeof code === 'string'
-                ? kindOfNamedCode(code)
-                : 'bad_response';
-    if (typeof message !== 'string' || message.length === 0) {
-        return new TheoremError(kind, 'Gemini returned an error.');
+    const text = typeof message !== 'string' || message.length === 0
+        ? 'Gemini returned an error.'
+        : typeof status === 'string'
+            ? `${status}: ${message}`
+            : message;
+    if (refusesKey(details))
+        return new TheoremError('auth', text);
+    if (typeof code === 'number' && code >= HTTP_STATUS_MIN && code <= HTTP_STATUS_MAX) {
+        return new TheoremError(kindOfHttpStatus(code), text);
     }
-    return new TheoremError(kind, typeof status === 'string' ? `${status}: ${message}` : message);
+    return typeof code === 'string'
+        ? namedCodeError(code, text)
+        : new TheoremError('bad_response', text);
 }
 /** The kind is the HTTP status's, unless the body names a refused key. */
 export async function readNonOkError(response) {
-    const kind = kindOfHttpStatus(response.status);
     const text = await response.text().catch(() => '');
     if (!text.trim()) {
-        return new TheoremError(kind, `HTTP ${response.status}`);
+        return new TheoremError(kindOfHttpStatus(response.status), `HTTP ${response.status}`);
     }
     const parsed = parseRecord(text);
-    const stated = parsed ? readGeminiApiError(parsed) : null;
-    return new TheoremError(stated?.kind === 'auth' ? 'auth' : kind, stated?.message ?? `Gemini HTTP ${response.status}: ${text}`);
+    return statedOrStatusError(parsed ? readGeminiApiError(parsed) : null, response.status, `Gemini HTTP ${response.status}: ${text}`);
+}
+/** A non-OK reply's error: the body's own when it names a refused key, else the status's with the body's message. */
+export function statedOrStatusError(stated, status, fallback) {
+    if (stated?.kind === 'auth')
+        return stated;
+    return new TheoremError(kindOfHttpStatus(status), stated?.message ?? fallback);
 }
 function parseRecord(text) {
     try {

package/esm/src/providers/google/live/stream.js

@@ -8,7 +8,7 @@ const CLOSE_KINDS = {
     1007: 'unsupported',
     1008: 'unsupported',
     1011: 'unavailable',
-    1013: 'unavailable',
+    1013: 'busy',
 };
 /**
  * Google refuses an over-quota Live key with code 1011 (`unavailable`) and a reason

package/esm/src/providers/shared/retry.d.ts

@@ -4,6 +4,7 @@ export type Wait = (ms: number, signal?: AbortSignal | null) => Promise<void>;
 export declare const WAIT_BUDGET_MS = 5000;
 export declare const waitDefault: Wait;
 export declare function isTransientHttp(status: number): boolean;
+/** A rejected send that never got a response: a network failure, by `networkError`'s rule. An abort, a timeout, or any other kind is not. */
 export declare function isTransientThrown(err: unknown): boolean;
 export declare function backoffMs(attempt: number): number;
 /** `retry-after-ms`, else `Retry-After` in seconds or as a date; undefined when absent or unreadable. */

package/esm/src/providers/shared/retry.js

@@ -1,12 +1,12 @@
-import { isAbortError, isTimeoutError } from '../../guardrails/error.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { networkError } from './upstream-tap.js';
 const BACKOFF_MS = [1000, 2000, 4000, 8000];
 /** All the waiting one call may do between tries; a wait that would pass it sends the last answer back. */
 export const WAIT_BUDGET_MS = 5000;
 /** The most tries after the first: a `Retry-After: 0` costs no wait, so the budget alone never ends it. */
 const MAX_RETRIES = BACKOFF_MS.length;
 const MS_PER_SECOND = 1000;
-const TRANSIENT_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
-const TRANSIENT_THROWN_RE = /name resolution|dns|econnreset|econnrefused|etimedout|connection (?:refused|reset)|error sending request|network|fetch failed|temporarily unavailable|socket|503|502|504/i;
+const TRANSIENT_STATUSES = new Set([408, 429, 500, 502, 503, 504, 529]);
 export const waitDefault = (ms, signal) => new Promise((resolve, reject) => {
     if (signal?.aborted) {
         reject(abortReason(signal));
@@ -28,11 +28,10 @@ function abortReason(signal) {
 export function isTransientHttp(status) {
     return TRANSIENT_STATUSES.has(status);
 }
+/** A rejected send that never got a response: a network failure, by `networkError`'s rule. An abort, a timeout, or any other kind is not. */
 export function isTransientThrown(err) {
-    if (isAbortError(err) || isTimeoutError(err)) {
-        return false;
-    }
-    return TRANSIENT_THROWN_RE.test(String(err));
+    const failure = networkError(err);
+    return failure instanceof TheoremError && failure.kind === 'network';
 }
 export function backoffMs(attempt) {
     return BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)];

package/package.json

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