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
- Tag every file you create or touch with
GRIDA-GG: <surface>.
- Place new code in a
gg-named location; don't dilute a BYOK or OSS one.
- 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.
- 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.