@rulvar/core 1.191.0 → 1.192.0

package/dist/index.d.ts

@@ -2381,6 +2381,14 @@ type AgentEvents = {
   label?: string;
   error: WireError;
   willRetry: boolean;
+} | {
+  type: "quota:denied";
+  agentType: string;
+  label?: string; /** The denied model ref. */
+  model?: string; /** The limiter's reason ('tokensPerMinute 1800000 exhausted'). */
+  reason?: string;
+  retryAfterMs?: number;
+  willRetry: true;
 } | {
   type: "agent:schema-retry";
   agentType: string;
@@ -5192,6 +5200,12 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
   adapter: ProviderAdapter;
   resolved: ResolvedInvocation;
   /**
+  * The versioned compat flag (RV1810): emit the legacy `agent:error`
+  * twin beside `quota:denied` for recoverable pre-wire quota waits.
+  * Default off: the wait speaks its own type only.
+  */
+  quotaDeniedAgentError?: boolean;
+  /**
   * Transport failover chain for the loop phase (M4-T04):
   * resolved fallback targets tried in order on
   * transport or rate-limit failures after retries exhaust. Failover is
@@ -7070,6 +7084,16 @@ interface CreateEngineOptions {
     modelKnowledge?: ModelKnowledgeStore;
   };
   defaults?: EngineDefaults;
+  /**
+  * Telemetry compat posture (RV1810). `quotaDeniedAgentError: true`
+  * restores the legacy `agent:error` twin beside the primary
+  * `quota:denied` event for recoverable pre-wire quota waits, for
+  * consumers still keyed to the old type. Default off: healthy
+  * throttling speaks its own type and never reads as failure.
+  */
+  telemetry?: {
+    quotaDeniedAgentError?: boolean;
+  };
   budgetDefaults?: BudgetDefaults;
   concurrency?: {
     perRun?: number; /** Per-adapter-id caps; unlimited unless configured (Appendix A; M4-T07). */
@@ -10515,6 +10539,10 @@ interface RunInternals {
     gates?: Record<string, MechanicalGateProfile>; /** Engine-wide admission countTokens policy (RV1804); default 'allow'. */
     countTokens?: "allow" | "deny";
   };
+  /** Telemetry compat posture (RV1810). */
+  telemetry?: {
+    /** Emit the legacy agent:error twin beside quota:denied. */quotaDeniedAgentError?: boolean;
+  };
   /** Engine-scoped per-provider keyed limiter (M4-T07). */
   providerLimiter?: KeyedLimiter;
   /**

package/dist/index.js

@@ -12407,7 +12407,25 @@ async function runAgent(options) {
 					const retryAfter = (outcome.wireError?.data)?.retryAfterMs;
 					if (outcome.wireError !== void 0) {
 						if (outcome.quotaDenied !== true) transportRetries += 1;
-						events?.emit({
+						if (outcome.quotaDenied === true) {
+							const denialData = outcome.wireError.data;
+							events?.emit({
+								type: "quota:denied",
+								agentType,
+								label: options.label,
+								model: target.resolved.ref,
+								...typeof denialData?.reason === "string" ? { reason: denialData.reason } : {},
+								...typeof denialData?.retryAfterMs === "number" ? { retryAfterMs: denialData.retryAfterMs } : {},
+								willRetry: true
+							});
+							if (options.quotaDeniedAgentError === true) events?.emit({
+								type: "agent:error",
+								agentType,
+								label: options.label,
+								error: outcome.wireError,
+								willRetry: true
+							});
+						} else events?.emit({
 							type: "agent:error",
 							agentType,
 							label: options.label,
@@ -17579,6 +17597,7 @@ function createCtx(internals, rootWorkflow) {
 			resolved: loopResolved,
 			limits,
 			events: agentSink,
+			...internals.telemetry?.quotaDeniedAgentError === true ? { quotaDeniedAgentError: true } : {},
 			transcript: {
 				mintRef: internals.mintTranscriptRef,
 				put: (ref, blob) => internals.transcripts.put(ref, blob, internals.lease)
@@ -25184,6 +25203,7 @@ function createEngine(options) {
 		if (profile.countTokens !== void 0 && !["allow", "deny"].includes(profile.countTokens)) throw new ConfigError(`createEngine defaults.profiles['${name}'].countTokens must be 'allow' or 'deny'`);
 	}
 	if (options.defaults?.countTokens !== void 0 && !["allow", "deny"].includes(options.defaults.countTokens)) throw new ConfigError("createEngine defaults.countTokens must be 'allow' or 'deny'");
+	if (options.telemetry?.quotaDeniedAgentError !== void 0 && typeof options.telemetry.quotaDeniedAgentError !== "boolean") throw new ConfigError("createEngine telemetry.quotaDeniedAgentError must be a boolean");
 	validateDeterminismConfig(options.determinism);
 	validateEngineQuotaConfig(options.quota);
 	if (options.security?.argsHashSalt !== void 0 && (typeof options.security.argsHashSalt !== "string" || options.security.argsHashSalt === "")) throw new ConfigError("createEngine security.argsHashSalt must be a nonempty string when given");
@@ -25360,6 +25380,7 @@ function createEngine(options) {
 				...defaults.gates === void 0 ? {} : { gates: defaults.gates },
 				...defaults.countTokens === void 0 ? {} : { countTokens: defaults.countTokens }
 			},
+			...options.telemetry === void 0 ? {} : { telemetry: options.telemetry },
 			errorPolicy: wf.errorPolicy,
 			dropped: [],
 			cost: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.191.0",
+  "version": "1.192.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",