gg — Grida Gateway

Grida Gateway (GG) is Grida's first-party AI gateway: the path by which a signed-in client runs AI — text, image, video — without a user-supplied model key (no BYOK), billed to the organization's prepaid credit. It is one coherent, extractable surface, marked so a single grep finds all of it, and it is designed to spin out of this repo into a standalone service at grida.gg. Treat every touch as work on a product that will one day live on its own.

Canonical spec: Hosted AI (metered, no-BYOK). Security boundary: GRIDA-SEC-006 in SECURITY.md.

What counts as GG

The test: does this code exist to let a keyless client spend org credit on a Grida-hosted model? If yes, it is GG. Four surfaces:

• token — the scoped-token mint + verify. A purpose-scoped, short-lived, org-bound JWT (audience gg:ai) is the only credential the gateway accepts. This surface is also GRIDA-SEC-006.
• gateway — the server endpoints: the OpenAI-compatible text surface (chat completions, models) and the native image/video generation surfaces. They verify the gg:ai token and meter through the billing seam; they carry no billing logic of their own.
• provider — the client-side gg provider kind (in the agent package) that resolves to the gateway, plus its in-memory session store, factories, and media adapters. It is the consumer of GG.
• desktop — the renderer lifecycle that mints/re-mints the token and pushes it to the sidecar (memory-only custody), and the daemon gg capability/namespace that receives it.

Not GG: the billing ledger itself (that is ee-billing / grida_billing); the billing seam's providerOptions.grida namespace (Grida-billing's key, shared with GRIDA-SEC-003); BYOK providers (the carve-out GG sits beside).

The GRIDA-GG marker

Like GRIDA-EE, the surface is grep-able. Tag every file that exists only for GG, with the surface as the sub-label:

// GRIDA-GG: token — scoped-token mint/verify (also GRIDA-SEC-006)
// GRIDA-GG: gateway — OpenAI-compatible chat completions
// GRIDA-GG: provider — the `gg` client provider kind
// GRIDA-GG: desktop — renderer token lifecycle

Sub-labels are surface names (token / gateway / provider / desktop), not ids. The grep is the index:

grep -rn 'GRIDA-GG' editor packages desktop

Tag the file header when the whole file is GG; tag inline when only a branch is (e.g. the gg arm inside a shared provider resolver). The canonical name is Grida Gateway (GG); write it that way in prose.

The naming map (canonical identifiers)

One brand, several forms — consistent with how the repo already names (GRIDA-EE marker + grida_billing schema + descriptive symbols):

concept	identifier
grep marker	GRIDA-GG: <surface>
token audience (wire)	gg:ai
signing secret (env)	GG_TOKEN_SECRET (+ GG_TOKEN_SECRET_PREVIOUS)
client provider kind (wire)	gg
provider id / metadata (code)	GG_PROVIDER_ID, GG_PROVIDER_METADATA, isGgProviderId
daemon capability / namespace	gg (tag gg@1)
TS symbols	GridaGateway* (e.g. GridaGatewaySessionStore)
files	gg-*.ts
future public host	grida.gg (endpoint paths stay /api/v1/ai/* for now)

Deliberate carve-outs (not renamed, on purpose): the public endpoint paths (/api/v1/ai/*) — a versioned REST contract whose brand is the host, not the path; and providerOptions.grida — the billing seam's key.

Working on GG

1. Tag every file you create or touch with GRIDA-GG: <surface>.
2. Place new code in a gg-named location; don't dilute a BYOK or OSS one.
3. Direction of dependency: consumers → GG contract, not GG → consumers. The gateway must not import desktop/renderer code; the client provider depends on the wire contract, not the server internals. This is what makes the spin-out cheap.
4. The gateway meters through the existing billing seam — it never grows its own billing logic. Pre-flight entitlement gate, post-flight usage ingest, sold at cost. See ee-billing.

When GG crosses security

The token surface (mint + verify + custody) is GRIDA-SEC-006. Any file on that surface carries both markers:

// GRIDA-SEC-006 — see /SECURITY.md
// GRIDA-GG: token — scoped-token mint/verify

Touching it runs the security review first (the boundary contract, fail-closed secret handling, audience pinning), then this skill (the surface-organization pass). The invariant to protect: the credential a native process holds for AI is worth at most 15 minutes of AI calls on one org's credit — and nothing more.

Precedence is stated here and cross-referenced from GRIDA-SEC-006 in SECURITY.md, so a reader entering from either side lands in the other.

See also: security (the GRIDA-SEC-006 half), ee-billing (the credit ledger GG spends), ee (the EE marker pattern this mirrors), agent-system and desktop (the two hosts), naming.