The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
/**
* Classifier for user-actionable runtime errors (#3931).
*
* Maps an error *signal* (the user-facing message + error type that already
* flow through the chat runtime / RPC layers) to a typed {@link UserErrorDescriptor}.
* Only the two #3913 expected-user-states are recognised in this first slice:
*
* - `budget_exceeded` — managed backend 400 / `USER_INSUFFICIENT_CREDITS`
* ("Insufficient budget")
* - `insufficient_credits` — BYO provider 402 / OpenRouter out of balance
* ("requires more credits")
*
* Anything else returns `null` (NOT user-actionable → stays in normal error
* flow / Sentry). This is deliberately conservative: a generic error must never
* be promoted into the panel.
*
* NOTE: matching raw text here is a bootstrap. The intended end state is core
* emitting a structured kind so the app does not pattern-match prose — see the
* follow-ups in the #3931 PR. Keeping the rules in this one pure module makes
* that migration a drop-in.
*/
import type { UserErrorDescriptor, UserErrorScope } from '../../types/userError';
export interface RuntimeErrorSignal {
/** User-facing message produced upstream (e.g. chat `event.message`). */
message?: string | null;
/** Coarse error type/code when available (e.g. chat `event.error_type`). */
errorType?: string | null;
/** Where the signal came from; defaults to `chat`. */
scope?: UserErrorScope;
/** Originating core domain (metadata only). */
sourceDomain?: string;
/** Provider slug when known (metadata only, never secrets). */
provider?: string;
}
/**
* A third-party integration is failing, so the connection state on screen is
* stale (#composio).
*
* Unlike the matchers below this does not sniff the prose: the caller already
* knows the integration errored, and the message is the backend's own
* user-facing explanation. It rides on `detail` verbatim rather than being
* pattern-matched into a billing entry — "your credits are exhausted" and
* "your connected tools have silently stopped" are different things to tell
* someone, and only the second explains why their agent stopped acting.
*
* @param message The integration client's user-facing error text.
* @param provider Integration slug (e.g. `composio`) — metadata only.
*/
export function classifyIntegrationError(
message: string | null | undefined,
provider: string
): UserErrorDescriptor | null {
const detail = message?.trim();
if (!detail) return null;
return {
id: userErrorId('integration_degraded', 'integration', provider),
kind: 'integration_degraded',
severity: 'warning',
scope: 'integration',
sourceDomain: provider,
provider,
titleKey: 'userErrors.integrationDegraded.title',
bodyKey: 'userErrors.integrationDegraded.body',
detail,
action: 'open_connections',
};
}
/**
* #6034: a completed reply that reached neither writer, so there is nothing to
* render and nothing to re-read.
*
* The caller already knows this happened — it just failed an append and a
* refetch — so, like the two constructors above, this takes the fact rather
* than sniffing prose. Scoped per thread so two different lost replies are two
* entries, and one thread failing repeatedly is one entry with a count.
*/
export function classifyReplyDeliveryFailure(threadId: string): UserErrorDescriptor | null {
const thread = threadId?.trim();
if (!thread) return null;
return {
id: userErrorId('reply_delivery_failed', 'chat', thread),
kind: 'reply_delivery_failed',
severity: 'error',
scope: 'chat',
sourceDomain: 'chat',
titleKey: 'userErrors.replyDeliveryFailed.title',
bodyKey: 'userErrors.replyDeliveryFailed.body',
action: 'dismiss',
};
}
/** Build the stable dedupe identity for an error. */
export function userErrorId(
kind: UserErrorDescriptor['kind'],
scope: UserErrorScope,
provider?: string
): string {
return `${kind}:${scope}:${provider ?? 'unknown'}`;
}
function haystack(signal: RuntimeErrorSignal): string {
return `${signal.message ?? ''}\n${signal.errorType ?? ''}`.toLowerCase();
}
/**
* Classify a runtime error signal. Returns a descriptor for a recognised
* user-actionable state, or `null` when the error is not one.
*/
export function classifyUserActionableError(
signal: RuntimeErrorSignal
): UserErrorDescriptor | null {
const text = haystack(signal);
if (!text.trim()) return null;
const scope: UserErrorScope = signal.scope ?? 'chat';
// Managed-budget exhaustion first: "insufficient budget" contains the word
// "insufficient", so it must win over the BYO-credits rule below.
const isBudget =
text.includes('user_insufficient_credits') ||
text.includes('insufficient budget') ||
text.includes('budget_exceeded') ||
text.includes('managed budget');
if (isBudget) {
return {
id: userErrorId('budget_exceeded', scope, signal.provider),
kind: 'budget_exceeded',
severity: 'warning',
scope,
sourceDomain: signal.sourceDomain,
provider: signal.provider,
titleKey: 'userErrors.budgetExceeded.title',
bodyKey: 'userErrors.budgetExceeded.body',
action: 'open_billing',
};
}
// BYO provider out of credits (OpenRouter 402, "requires more credits", etc).
const isCredits =
text.includes('requires more credits') ||
text.includes('out of balance') ||
text.includes('insufficient credits') ||
text.includes('insufficient_credits') ||
(text.includes('402') && text.includes('credit'));
if (isCredits) {
return {
id: userErrorId('insufficient_credits', scope, signal.provider),
kind: 'insufficient_credits',
severity: 'warning',
scope,
sourceDomain: signal.sourceDomain,
provider: signal.provider,
titleKey: 'userErrors.insufficientCredits.title',
bodyKey: 'userErrors.insufficientCredits.body',
action: 'open_provider_settings',
};
}
// Provider configured but no API key set — a deterministic credential-guard
// failure (no HTTP). Matches the stable `api_key_missing` kind token emitted
// by core (e.g. cron `user_error`) AND the verbatim guard prose, mirroring
// the Rust single-source matcher `is_api_key_unset_message` (observability.rs)
// so a wording drift on either side fails its own test rather than silently
// dropping the signal (TAURI-RUST-HCK / #4165).
const isApiKeyMissing =
text.includes('api_key_missing') ||
text.includes('api key not set') ||
text.includes('missing api key') ||
text.includes('no api key is configured') ||
text.includes('no api key supplied');
if (isApiKeyMissing) {
return {
id: userErrorId('api_key_missing', scope, signal.provider),
kind: 'api_key_missing',
severity: 'warning',
scope,
sourceDomain: signal.sourceDomain,
provider: signal.provider,
titleKey: 'userErrors.apiKeyMissing.title',
bodyKey: 'userErrors.apiKeyMissing.body',
action: 'open_provider_settings',
};
}
// The local model runtime a workload depends on is unusable — Ollama is not
// running, or the configured model was never pulled (#5354). Emitted by core
// as the stable `local_model_unavailable` kind token (memory embedder health
// gate); the prose variants match the wording the local embedder itself
// produces, so a signal that arrives with a message instead of a token still
// classifies. Deliberately last: it is the narrowest rule, and a provider
// that is out of credits should keep its billing remediation even when the
// message happens to name Ollama.
// Each prose matcher is anchored on the FULL producer wording, never a bare
// `daemon unreachable at`: backend connection-health logs in other domains
// emit that phrase too, and promoting one of those into an "install Ollama"
// panel entry would be worse than showing nothing. Mirrors the same
// deliberate anchoring in the Rust matcher `is_ollama_user_config_rejection`.
const isLocalModelUnavailable =
text.includes('local_model_unavailable') ||
// tinyagents embedder, daemon not listening.
text.includes('is ollama running') ||
// tinyagents embedder, model never pulled — the second shape the Rust
// classifier recognises, so the two sides stay symmetric.
(text.includes('ollama embedding model') && text.includes('is not installed at')) ||
// platform doctor report.
text.includes('ollama daemon unreachable') ||
// memory embedder health gate.
text.includes('ollama embeddings opted-in but daemon unreachable at');
if (isLocalModelUnavailable) {
return {
id: userErrorId('local_model_unavailable', scope, signal.provider),
kind: 'local_model_unavailable',
severity: 'warning',
scope,
sourceDomain: signal.sourceDomain,
provider: signal.provider,
titleKey: 'userErrors.localModelUnavailable.title',
bodyKey: 'userErrors.localModelUnavailable.body',
// Local AI + embedding provider selection both live behind
// `/settings/llm`, which redirects to Connections → API keys.
action: 'open_provider_settings',
};
}
return null;
}