Built-in AI helpers (how they're powered — paid cloud vs free BYO key)

What it is

Omniscio runs a set of small built-in AI helpers in the background — session titles, AI suggestions, reply drafts, the daily digest, email summaries, and similar utility calls. These are separate from your coding sessions (which run on your own Claude / Codex / other accounts) and from your prepaid jls_sk_ API keys (see api-keys.md). They are cheap utility-model calls that keep the app's small conveniences working.

Where to find it

Two places matter, and neither has a screen of its own. Your own OpenRouter key — the thing that makes the helpers run on your account — is entered in Settings → Accounts & Providers → API Keys, and your plan together with your live usage and next reset date is on Settings → Plan & Usage. The helpers themselves just run in the background.

How it behaves

How they're powered (plan-gated, since 2026-07-20)

The helpers are powered differently depending on your plan, decided per call in this order:

1. Your own key always wins. If you've entered your OpenRouter key (Settings → Accounts & Providers → API Keys → "Your OpenRouter key", an sk-or-… value) — or you have a configured Anthropic API-key account — the helpers run directly on your key. This is true on any plan, free or paid, and your call is never rerouted through Omniscio's infrastructure.
2. Paid plan, no own key → Omniscio's cloud. On a paid plan (Pro / Team / Enterprise), and signed in, the helpers run through Omniscio's company-paid cloud gateway — no key of your own needed. This is the built-in-AI benefit that comes with a paid subscription.
3. Free plan, no own key → the helpers pause. On the free plan with no key of your own, the helpers pause and surface a "Built-in AI helpers are paused" card in the inbox. The rest of the app keeps working; only the built-in AI helpers wait until you add an OpenRouter key. There is no silent fallback onto Omniscio's cloud (that's the paid benefit) and no bundled key.

Signed-out or an unrecognized plan is treated as free (bring your own key) — conservative, so the company cloud is never handed to an unverified plan.

What the limit actually is

The allowance is a money ceiling per user per month, not a request count — PER_USER_MONTHLY_USD_BY_TIER in paid-offering.ts, enforced by the gateway:

Plan	Monthly built-in-AI allowance
Free	$0
Pro	$0
Team	$0
Enterprise	$0

As of 2026-08-25 that allowance is $0 on every plan (owner decision — no free company-funded AI budget on any tier). In practice this means the built-in helpers always run on your own key: general in-app AI declines with a 402 and falls back to your OpenRouter/Anthropic key or your prepaid credit. Three safety-net features — the inbound-email security screen, the keyless Ask-Omniscio help and the new-user onboarding sessions — are exempted from the per-user cap in the gateway (up to a small daily allowance per person) and still run on the shared company pool.

Session titles are included in every paid plan (since 2026-09-30). On Pro, Team or Enterprise with no key of your own, titles run on Omniscio's cloud even though the allowance is $0 — about $0.0002 a title. The per-person daily limit and the company-wide caps still apply. On the free plan with no key of your own, a session is titled from its first words instead.

The meter still resets at the first instant of the next UTC month, and two company-wide ceilings sit above the whole lane: a monthly cap on this internal lane and a $3,000/month Cloud Billing budget. Your live usage and reset date are on Settings → Plan & Usage.

Read the lane cap from the code, never from a number typed into a page. The two ceilings do different jobs and are easy to conflate:

• the lane cap is a hard stop — over it the lane 402s and calls fall back to your own key. Its shipped value is DEFAULT_GLOBAL_MONTHLY_USD in company-ledger.ts.
• the Cloud Billing budget is alert-only — it emails and never halts spend. Its value is GATEWAY_BUDGET_MONTHLY_USD in deploy.sh.

On the lane cap's current value: the owner has deliberately set it ABOVE the Cloud Billing budget, so in practice the alert fires long before anything hard-stops. The mechanism is still armed — it is the only fail-closed money stop in the footprint — it simply no longer binds. This page previously quoted a $150/month figure and then a $300/month one, both now stale; with the cap set that high, any concrete number here would go stale again, which is why this page states the shape and points at the declaration instead.

A missing tier entry means uncapped, not "no allowance" — which is exactly why every tier is listed explicitly at $0 rather than removed. Never delete a tier's entry to express "this tier gets nothing"; that silently makes it unlimited.

The client-side daily safety net (a runaway brake, not your budget)

Separately from the gateway's per-user monthly ceiling above, the shared helper path carries a client-side daily net: once a helper has spent $25 in one local-midnight day under its own label, that helper stops calling and resumes the next day. Session titles, suggestion chips, reply drafts, hub/app/skill descriptions and the other small assists all run through the one shared path, so this is the net under all of them.

Read what it is before treating it as a budget. The constant describes itself as "a safety net, not a tuning knob" and is deliberately high — normal use of these helpers is cents a day, so the net exists to stop a genuine runaway (a supervisor loop re-firing on a stuck session all day), not to meter you. It is counted per label, per cost source, summed across accounts, and it is not the per-user spend ceiling: when a helper routes through the company gateway, the authoritative per-user ceiling is enforced server-side there and answers 402 before the call is forwarded. This is also a different limit from the two "helpers stopped" cards below, which are about the monthly allowance.

The two "helpers stopped" cards are different

One inbox row (dedupKey pooled-ai-monthly-limit), but two honest messages — they must never be swapped, because only one of them involves anything actually being spent:

• "Built-in AI helpers are paused" (no-plan-allowance) — the free-plan pause above. Nothing was consumed and no allowance ever existed, so this card never says an allowance was "used". It offers both routes out: upgrade, or paste your own key.
• "Monthly AI allowance used" (allowance-exhausted) — a real gateway 402. A genuine allowance ran out; the card names the reset date, and the amount too when there is a real one to name. Because every tier sits at $0 today, the amount is omitted rather than printed — a card reading "you have used your $0" would be the same species of lie these two variants exist to prevent.

Both name the helpers that stopped (session titles, suggested replies, Plain Speak summaries, the daily digest, email summaries) and confirm your Claude coding sessions, projects, inbox and automations are unaffected. The button opens Settings → Plan & Usage. The tier behind the copy is read with currentEffectiveCachedTier(), so signed-out and lapsed-paid users both get the free card with its upgrade path — see internal-ai-gateway-routing-contract.md I9.

The card lands at most once a month

The allowance is monthly, so the notice is too — it cannot reach the user more than once per billing period, which takes two separate caps because the producer fires constantly by design (every helper that touches the spent pool 402s and calls it):

• Within an app run — a once-per-run latch in pooled-ai-limit-notice.ts. Without it each 402 coalesced into the live row, and because bumpDedupCount touches updated_at while the inbox lists ORDER BY updated_at DESC, the same card re-floated to the top all day.
• Across restarts and dismissals — a 30-day floor on pooled-ai-monthly-limit in the central alert cadence registry. On the generic 24h default a dismissed card came back the next day, every day, for the rest of the month.

Past 30 days it re-raises normally: a monthly cap must not become permanent silence, because the pool resets and the user is entitled to hear about the new month's.

Adding your OpenRouter key (free plan)

Create a key at openrouter.ai/keys, then paste it into Settings → Accounts & Providers → API Keys → "Your OpenRouter key". It's stored encrypted like every other credential (never synced in plaintext, never sent to the renderer or a CLI export). Once saved, the built-in helpers run on your OpenRouter account — Omniscio maps each helper's model to its OpenRouter equivalent automatically, so you don't pick models. Your key takes priority the moment it's set.

The old "Route internal AI through the cloud (test)" toggle is gone

Through mid-2026 an experimental toggle ("Route internal AI through the cloud (test)") let you flip the helpers between the bundled keys and your cloud account. That toggle has been removed — routing is now decided by your plan, not a manual switch, so there's nothing to toggle. Paid plans get the cloud automatically; free plans bring a key. (The old setting name routeInternalAiThroughGateway still exists internally as an inert default and is no longer user-facing.)

If you haven't added an API key yet (new installs)

The first time a helper can't run because no usable Anthropic API key is saved, you get one inbox card that says exactly that — "Add an API key to turn on AI helpers" — with an Add API key button that opens Settings → Accounts and scrolls straight to the Anthropic key box. It does not blame a provider outage, because nothing is down: the key was simply never added. A claude login account alone is not enough here — the Messages API these helpers use doesn't accept OAuth tokens, so they need a key even when your coding sessions are signed in and running fine.

You get one card, not a stream: it's raised at most once per app run and coalesced under a single dedup key, so dismissing it sticks. Everything else keeps working while it's up, and it clears itself the moment the helpers succeed after you paste your key.

Before this shipped, the Messages-API helpers refused silently on a keyless install — no card, no explanation, nothing to click — and the only card you could eventually get came from an unrelated code path and blamed a temporary outage.

If the main AI provider has a bad stretch

The built-in helpers run on a cheap, shared AI provider. If that provider has a rough patch (an outage, or its account running low), you might briefly see an "AI features are using a backup provider" notice in your inbox. Nothing is broken — the helpers automatically shift to a backup so titles and suggestions keep working; they may just be a little slower or, now and then, a touch less polished. The notice clears itself once the main provider recovers, and there's nothing you need to do. (And if the AI titler can't reach any provider at all, a new session simply gets a short title made from your first message instead of a smart one.)

For agents

• The routing decision funnels through one pure function, resolveGatewayRouting (+ its raw-fetch twin resolveProviderFetchTarget), and the chat() wiring in llm-provider-service.ts. Both callers pass the tier; a free tier makes the gateway resolve to null (direct path).

• Tier source is getCachedAuth()?.tier — the Firebase-verified plan claim, un-forgeable client-side. It is read fail-safe to free: any error, or a background subprocess where auth is unreachable, resolves to "free" (no company gateway) so a free/unidentifiable user is never billed to the company pool.

• A free-plan BYOK OpenRouter key forces provider='openrouter' and maps a pinned model (e.g. a Groq or bare-Anthropic id) to its OpenRouter slug via toOpenRouterModelId, so a helper that pinned a non-OpenRouter model still resolves.

• The free-no-key pause reuses the existing pooled-ai-limit-notice inbox alert and throws the existing AnthropicFallbackUnavailableError so the helper pauses cleanly.

• The "no key saved" card has ONE owner, reached from TWO detectors. ai-no-api-key-notice.ts owns the ai-helpers-no-api-key dedup key, its copy, and a raised-once-per-run latch (the refusal fires on every keyless call, so an unlatched raiser would stamp the card "×2,431"). Its two callers:

  • ai-suggestion-service.resolveCredentialFor — the immediate path. Both "This feature requires an Anthropic API key" branches call notifyAiHelpersNeedApiKey(). This return happens before the circuit breaker, so it recorded no failure, opened no circuit, and raised nothing — the silent dead end. One notify per refusal is repo-wide enforced by ai-no-api-key-refusal-notifies.test.ts.
  • ai-call-guard.ts — the breaker path. On a circuit open it probes resolveApiKeyForAiFeatures() and defers to the same owner when nothing resolves, instead of raising ai-suggestion-service-outage. The probe fails safe to the outage copy, so an unreadable config never accuses the user of skipping setup.

  Raising either variant retires the other (contradictory diagnoses never co-exist), and recovery clears both and re-arms the latch. The one-click Add API key button is a registry row in alert-actions/accounts.ts targeting the api-key-setup card (inbox-alert-contract I20).

• The daily digest follows the same rule — a free user's digest requires their own key (see daily-digest-credential-contract.md).

• A dead/dry primary provider is surfaced even behind the fallback. Because a failed cheap call succeeds via the Anthropic fallback, a sustained primary-provider outage is otherwise invisible; a per-provider health signal in llm-provider-service.ts counts cheap failures BEFORE the fallback and, after 5 in a row that ALSO persist for ~3 min (a brief burst that self-heals inside the window is suppressed — no card flash), raises the self-clearing, confidentiality-safe "backup provider" notice (ai-provider-degraded:<provider>) + an operator ai_provider_degraded metric log. For a keyless PAID user, session titles also get a company-gateway Haiku backstop when the cheap provider is down — its breaker open, or the cheap call hit a definitive non-timeout failure (title-gen-recovery I5/I6; the gateway-routing "unmask" §).

• Full invariants (I1–I9), including the plan gate and BYOK precedence: internal-ai-gateway-routing-contract.md.

This is distinct from the spawn-session company-credit path (the Omniscio credits row of a model family's supply list, the user-prepaid /v1 lane) — a different billing model, where the order of that family's list decides whether your key or your credits pay first.

Related

What each plan includes, and how to change it, is on the plan and billing page. The coding accounts these background helpers are separate from are on the API keys page, and the daily digest — one of the helpers named here — has its own credential and source rules on the Daily Digest page.