Direct gateway traffic needs positive feature identification

[pedroheyerdahl]

Context

PR #307 adds deterministic feature attribution to microdollar_usage_metadata via the X-KILOCODE-FEATURE header. All internal features (extensions, CLI, cloud agents, internal services) will send this header. Direct gateway consumers (external API users) currently show as NULL.

Problem

Direct gateway is a WAU feature that needs a positive signal like all other features. NULL in the feature column is reserved for catching tracking issues (e.g. a misconfigured internal feature). If direct gateway traffic is also NULL, we can't distinguish legitimate unattributed external usage from broken internal attribution.

Currently, external consumers can hit both /api/gateway/ and /api/openrouter/, which makes it difficult to positively identify direct gateway traffic at the infrastructure level.

What's needed

A mechanism to positively identify direct gateway traffic so it gets its own feature value (direct-gateway) rather than falling into the unattributed NULL bucket.

cc @jrf0110 @chrarnoldus

[jrf0110]

We need to align on what "Direct Gateway Traffic" means. Kilocode features hit the gateway the same way that everyone hits the gateway. One difference from kilo features is that we now send the X-KILOCODE-FEATURE header. Any consumer of the gateway can choose to send that header if they want. So this is a best-effort sort of solution and it can't be 100% trusted.

My recommendation is that any request that does not have an X-KILOCODE-FEATURE header should be considered feature: gateway

[pedroheyerdahl]

Direct gateway = external consumers who hit the gateway API directly, without going through the extension, CLI, or any of our other features.

Defaulting missing headers to gateway just moves the problem. It makes the gateway bucket unreliable instead of the NULL bucket. NULL needs to stay as our "something is wrong with tracking" signal. Without that, we can't confidently report any feature's attribution is healthy.

We need a positive signal that a request came from someone hitting the API directly. Even if it's imperfect: yes, a user could spoof a header, but there's zero incentive to do so (it doesn't affect billing or access), and that's a far more marginal case than silently mislabeling all unattributed traffic as gateway

[jrf0110]

Defaulting missing headers to gateway just moves the problem. It makes the gateway bucket unreliable instead of the NULL bucket. NULL needs to stay as our "something is wrong with tracking" signal. Without that, we can't confidently report any feature's attribution is healthy.

I don't think we're going to be able to get around that. There's no good way to reliably differentiate. We could look at both the X-Kiocode-Feature header and the User-Agent header to make sure they are what we expect and if not, use a null value, but that seems like an unnecessary distinction.

If X-Kilocode-Feature is a value we don't know about, we can insert null. If there is no X-Kilocode-Feature, then it should be set to gateway. I don't think there's a better solution here

[pedroheyerdahl]

Agree that there's no perfect way to do this, but there are better ways than patching whatever comes from whatever route as gateway.

All our features use /api/openrouter/. Our docs tell external users to use /api/gateway/. I understand that a handful of users might also end up using /api/openrouter/ directly, but the question is: what's worse? Letting every old CLI version, every broken attribution, and every misconfigured new feature be silently misassigned as direct-gateway? Or undercounting a handful of direct gateway users who happen to use the internal route?

Unless there's a better alternative I'm not seeing, I'd like to go back to the route-based approach I originally proposed.