feat(llm-gateway): add free onboarding product for wizard cloud runs

[rafaeelaudibert]

Problem

Setup wizard cloud runs (the "run the wizard in the cloud" path from onboarding) create a task with origin_product = "onboarding".
The agent-server has no mapping for that origin, so it falls through to the posthog_code default and every generation the run makes bills into CreditBucket.POSTHOG_CODE_CREDITS.

Two things wrong with that. We charge a customer's PostHog Code credits for onboarding, which is our acquisition spend and happens before they have decided to buy anything. And wizard traffic is indistinguishable from real Code tasks in $ai_generation, so we cannot see what onboarding actually costs.

ai_product cannot be fixed with a header. The gateway re-asserts it from the route in _apply_owned_event_properties precisely so callers cannot spoof it. The route is the only lever, which means a new product.

Changes

A new onboarding gateway product, unbilled (credit_bucket=None), with an explicit cost ceiling so the spend gauge actually gets published for it.

Wizard cloud runs now pin claude-sonnet-5 instead of inheriting the agent-server's claude-opus-4-8 default, and stamp ai_stage="wizard_pr_agent" so the PR agent's generations stay separable inside the product. The pin is what makes the narrow model allowlist workable.

A free product needs a closed door, and origin_product is caller-settable: any task:write holder can POST a task claiming any origin except the three we already reject. So the task API now refuses onboarding too, the same way it refuses image_builder and experiments. Without that, this PR would ship a free LLM endpoint.

That guard is one of two. The other lives in the agent-server: it only routes to the free product when the run also carries the wizard_config state key, which only the server-side wizard flow stamps and which the run PATCH allowlist drops. A task that merely claims the origin stays on posthog_code.

Also fixed one adjacent lie in the gateway README, which still documented a billable=True flag that was replaced by credit_bucket.

Important

This PR is the first half. The agent-server half is PostHog/code#3855, and it must land after this one.
The gateway deploys from its own path-triggered pipeline, so until onboarding exists in PRODUCTS there, any request to that path segment gets a 400 from validate_product. Landing this first is inert, since nothing requests the slug until the agent change ships and the sandbox base image rebuilds.

Note

Model allowlist includes claude-opus-4-8 on purpose. The Claude SDK sets it as fallbackModel for refusal and overload rescue whenever it is not the primary, so a 403 there would fail the run instead of rescuing it. Bedrock ids are in for the same reason, matching posthog_code and background_agents.

How did you test this code?

I (well, Claude) ran these locally, all green:

• services/llm-gateway full suite, 1375 passed. The new product is picked up automatically by the derived TestServerCredentialConfigInvariant, which is what forces requires_server_credential=True on anything sharing the Code OAuth app.
• products/tasks/backend/tests/test_api.py plus posthog/api/wizard/, 660 passed.
• products/tasks/backend/tests/test_facade.py, 31 passed.

New test coverage and the regression each one catches:

Test	Catches
onboarding case added to test_create_task_rejects_internal_origin	Someone drops the API guard and the free route becomes forgeable by any task:write caller. This is the security-relevant one.
test_create_wizard_cloud_run_pins_its_model	The model pin gets dropped, runs go back to the premium default, and every wizard cloud run then 403s at the gateway because that model is not in the product's allowlist.
onboarding added to the two TestServerCredentialRequirement lists	The server-credential marker stops being enforced for this product. Those lists are hand-enumerated, so a new product is not covered without it.

Not tested by me: the end to end run against a real sandbox. That needs both halves deployed plus a sandbox image rebuild, so it has to happen after the agent PR lands. What I would check then is that the run's $ai_generation events carry ai_product = "onboarding", $ai_billable = false, ai_stage = "wizard_pr_agent", and sonnet-5 as the model.

👉 Stay up-to-date with PostHog coding conventions for a smoother review.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

Docs update

Updated services/llm-gateway/README.md in this PR: added the product to the registered products table and corrected the billable reference to credit_bucket. No user-facing docs affected.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Opus 5 in Claude Code, driven by me. Invoked /writing-tests before adding tests.

The interesting decision was how hard to lock the free route. The first proposal was a dedicated internal OAuth scope minted only for wizard runs and required by the product, mirroring signal_scout_internal. I rejected it as too much machinery for the payoff. What we went with instead is the two-factor gate described above, which reuses markers that already exist and are already protected.

Worth knowing while reviewing: the gateway's own requires_server_credential flag is set here for consistency and to satisfy the config invariant test, but it is not carrying the weight. It is OAuth-only, it is inert unless posthog_code_model_gate_enabled is on, and every sandbox token already carries internal_run:read anyway, so it cannot tell a wizard run from any other task run. The API guard and the wizard_config check are what actually close the door.

One related finding I deliberately left out of scope. Task.internal is settable on create and mutable on PATCH, and isInternal maps to background_agents, which is also unbilled. That looks like the same shape of hole, already open. It may be covered by requires_server_credential depending on what LLM_GATEWAY_POSTHOG_CODE_MODEL_GATE_ENABLED is set to in production, which I could not verify from here. Worth a look, separately.

[rafaeelaudibert]

• feat(llm-gateway): add free onboarding product for wizard cloud runs #74095 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 2 · PR risk: 0/10

[greptile-apps]

Security Review

The onboarding product's server-credential restriction is ineffective while the global model gate is disabled, allowing a matching desktop OAuth token to access unbilled inference. How this was verified: The onboarding route accepts shared PostHog Code application IDs, while the scope check is conditional on a setting that defaults to false.

Prompt To Fix All With AI

### Issue 1
services/llm-gateway/src/llm_gateway/products/config.py:153
**Server credential gate stays disabled**

When `posthog_code_model_gate_enabled` retains its default false value, `requires_server_credential=True` is not enforced for this product, so an ordinary PostHog Code OAuth token from an allowlisted application can send unbilled onboarding inference requests without the required `internal_run:read` scope. **How this was verified:** The onboarding route accepts the shared PostHog Code application IDs, while the server-credential scope check is conditional on a setting that defaults to false.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(llm-gateway): add free onboarding p..." | Re-trigger Greptile}

[stamphog]

Note

🤖 stamphog reviewed 650cd0ebba1a9159ef2dd4b02e3bfd28f2ca715d — verdict: REFUSED

Three independent reviewers (hex-security-app, veria-ai, greptile-apps) all flag the same unresolved, current-head security finding: the new unbilled onboarding product's server-credential requirement is only enforced when a flag that defaults to false is on, letting any ordinary PostHog Code OAuth token hit the free/unbilled endpoint; a second hex-security-app finding on model-pin mutability via PATCH is also unaddressed.

• Author wrote 0% of the modified lines and has 6 merged PRs in these paths (familiarity MODERATE).
• greptile-apps[bot], hex-security-app[bot], veria-ai[bot] reviewed the current head.
• Unresolved high-severity finding (hex-security-app, corroborated by veria-ai and greptile-apps) on services/llm-gateway/src/llm_gateway/products/config.py: requires_server_credential for the onboarding product is only enforced when posthog_code_model_gate_enabled is true, which defaults to false, so a normal PostHog Code OAuth token can call the unbilled onboarding endpoint directly.
• Unresolved medium-severity finding (hex-security-app) on products/tasks/backend/facade/api.py: the onboarding model pin lives in mutable TaskRun.state and PATCH does not protect the 'model' key, so any team member could switch a queued wizard run to a costlier allowlisted model before it's processed.
• Change is in billing/auth-sensitive territory (new unbilled credit bucket, task-origin authorization) with cross-team authorship and only MODERATE familiarity — assurance from reviewers exists but points at real unfixed gaps rather than clearing the change.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	33L, 4F substantive, 67L/8F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1c-medium (67L, 8F, two-areas, feat)
stamphog 2.0.0b3		.stamphog/policy.yml @ 953cac2 · reviewed head 650cd0e

[richardsolomou]

could we also cover removing the four new protected model keys via state_remove_keys? the current test covers overwrites, but deleting model or runtime_adapter could still trigger an unintended fallback

[rafaeelaudibert]

@richardsolomou of course, see it in 376d1e3

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-07-28 19:56 UTC	Run
prod-us	✅ Deployed	2026-07-28 20:12 UTC	Run
prod-eu	✅ Deployed	2026-07-28 20:12 UTC	Run