@rise-so/pi-grok-build 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viktor Taranenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# pi-grok-build
+
+xAI Grok Build for [pi](https://github.com/earendil-works/pi): OAuth login
+(Grok subscription) plus Grok chat models over the OpenAI Responses API.
+**OAuth only — API keys are deliberately unsupported in this project.**
+
+One dependency-free core with two adapters:
+
+| Entry point | File | Use it for |
+|---|---|---|
+| `@rise-so/pi-grok-build/extension` | `src/extension.ts` | pi coding-agent extension: `/login` offers "xAI (Grok subscription)", `pi --list-models` shows the models |
+| `@rise-so/pi-grok-build` | `src/provider.ts` | a pi-ai `Provider<"openai-responses">` for programs composing their own `Models` registry (pi-ai / pi-agent core) |
+| `@rise-so/pi-grok-build/core` | `src/xai-grok-build.ts` | the raw OAuth flow (`loginXai`, `refreshXai`) and model metadata, no pi-ai runtime imports |
+
+## Models
+
+| Model | Context | Pricing (per Mtok in/out/cache-read) | Notes |
+|---|---|---|---|
+| `grok-build-0.1` | 256k | $1.00 / $2.00 / $0.20 | flagship; aliases `grok-code-fast-1` upstream; pricing live-verified |
+| `grok-4.3` | 1M | $1.25 / $2.50 / $0.20 | reasoning model; pricing live-verified; live pricing doubles past 200k tokens (pi records the base tier) |
+| `grok-composer-2.5-fast` | 200k | $3.00 / $15.00 / $0.50 | responds on `/responses` but is **absent from the live `/models` catalog**; context/output metadata from third-party registries |
+
+### Media models (not wired up)
+
+The subscription credential also sees `grok-imagine-image`,
+`grok-imagine-image-quality`, `grok-imagine-video`, and
+`grok-imagine-video-1.5` (per live `GET /v1/models`; run `pnpm smoke:models`).
+They use xAI's `/images/*` and `/videos/*` endpoints — a different protocol
+from `/responses` — so they are deliberately not registered. If wanted later,
+they need a pi-ai images-api adapter, not entries in the chat model list.
+
+## Use as a pi extension
+
+For development, load the extension directly from a checkout:
+
+```sh
+pi -e /path/to/pi-grok-build
+```
+
+For a permanent install, copy the project into pi's extensions directory —
+a copy gives pi a stable snapshot that won't shift underneath it as the
+checkout changes:
+
+```sh
+cp -R /path/to/pi-grok-build ~/.pi/agent/extensions/pi-grok-build
+```
+
+Then pick a model:
+
+```sh
+pi --model xai-grok-build/grok-build-0.1
+pi --model xai-grok-build/grok-4.3 -p "one-shot prompt"
+```
+
+No `npm install` is needed for pi imports — pi's loader aliases
+`@earendil-works/pi-*` to its own bundled copies. The extension registers the
+provider id `xai-grok-build`; log in with `/login` (OAuth is the only
+credential — the provider intentionally has no API-key path).
+
+### Install as a pi package
+
+This repo is a pi package (`package.json` declares the extension under the
+`pi` key), so `pi install` can manage it — pi records the source in
+`~/.pi/agent/settings.json` and loads the extension on every run:
+
+```sh
+pi install /path/to/pi-grok-build                # from a local checkout
+pi install git:github.com/rise-so/pi-grok-build  # from a git remote (@tag to pin)
+
+pi list                                      # confirm it's installed
+pi remove /path/to/pi-grok-build             # uninstall
+```
+
+Add `-l` to `pi install` to record it in the project's `.pi/settings.json`
+instead of your user settings.
+
+## Use as a library provider
+
+```ts
+import { createModels } from "@earendil-works/pi-ai";
+import { xaiGrokBuildResponsesProvider } from "@rise-so/pi-grok-build";
+
+const models = createModels({ credentials: myCredentialStore }); // holds the OAuth credential
+models.setProvider(
+  xaiGrokBuildResponsesProvider({
+    // referrer: "my-app", // authorize-URL referrer param
+  }),
+);
+
+const model = models.getModel("xai-grok-build", "grok-build-0.1");
+if (!model) throw new Error("model not registered");
+const reply = await models.completeSimple(model, {
+  messages: [{ role: "user", content: "hello", timestamp: Date.now() }],
+});
+```
+
+The host owns credential storage: pass a `CredentialStore` holding the OAuth
+credential (obtained via the provider's `auth.oauth.login`), and pi-ai handles
+refresh through the provider's own `refresh`. `live/support.ts` has a working
+file-backed example. Model constants (`GROK_MODELS`, `GROK_BUILD_MODEL`, …)
+are exported from the package root.
+
+`@earendil-works/pi-ai` is a peer dependency (pinned to `>=0.80.0 <0.81.0`).
+The package exports built output (`dist/`, `.js` + `.d.ts`), so it installs
+cleanly from npm, a tarball, or a git dependency — Node refuses to type-strip
+raw `.ts` under `node_modules`, so the build step is what makes copy-based
+installs work. `pnpm install` builds `dist/` automatically (`prepare` script),
+as does pnpm when consuming this repo as a git dependency.
+
+## Provider id: `xai-grok-build`, never `xai`
+
+Credentials live in pi's shared `~/.pi/agent/auth.json`, keyed by provider id.
+Registering OAuth under `"xai"` would capture pi's built-in xAI provider:
+every built-in Grok model would be billed to the subscription token,
+`registerProvider` would wipe pi's built-in xAI models, and `/login` would
+offer an API-key row that silently overwrites the OAuth credential. A distinct
+id makes all of that structurally impossible.
+
+## Load-bearing constraint (extension path)
+
+`src/extension.ts` — and everything it imports at runtime — must never import
+a `@earendil-works/pi-ai` subpath (`api/*`, `providers/*`) and must never
+import `src/provider.ts`. pi's extension loader aliases the bare package
+prefix to its compat bundle, so subpath specifiers resolve to nonexistent
+paths: silent at typecheck, fatal at extension load. `extension.test.ts`
+guards this with an import grep; keep it green.
+
+## Caveats
+
+- The OAuth flow borrows the Grok CLI's public client id and fixed loopback
+  port 56121 (xAI has no public client registration). xAI can break it at any
+  time; a concurrent Grok CLI login collides on the port.
+- OAuth is the only auth path, by policy. There is no `$XAI_API_KEY` handling,
+  no API-key login row, and no reading of other programs' credential files.
+- Context windows and pricing for `grok-build-0.1` / `grok-4.3` are confirmed
+  by xAI's live `GET /v1/models` (see `pnpm smoke:models`). `maxTokens` output
+  caps are registry metadata only. `grok-composer-2.5-fast` is unlisted in the
+  live catalog (it serves anyway); its context/output figures come from
+  third-party registries and its pricing is maintainer-supplied.
+
+## Development
+
+```sh
+pnpm install          # also builds dist/ via the prepare script
+pnpm check            # tsc --noEmit + unit tests (offline, always safe)
+pnpm build            # emit dist/ (.js + .d.ts) for library consumers
+pnpm test:live        # live acceptance against api.x.ai (skips without a credential)
+pnpm smoke:models     # print the live model catalog for your credential
+pnpm smoke:extension  # end-to-end through a real `pi` binary
+```
+
+The pi extension path (`pi -e`, `pi install`, the extensions directory) needs
+no build: pi's loader executes `src/extension.ts` directly, per the `pi` key
+in `package.json`. Only library consumers go through `dist/`.
+
+Unit tests (`src/*.test.ts`) run offline with fetch stubbed; live tests
+(`live/*.test.ts`) hit api.x.ai with the stored pi OAuth credential and are
+never part of `pnpm check`. Acceptance criteria and the full test layering are
+documented in `ACCEPTANCE.md`.

package/dist/extension.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function xaiGrokBuild(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -0,0 +1,63 @@
+// pi extension adapter: registers the Grok Build provider with pi's coding
+// agent so /login offers "xAI (Grok subscription)" and the model lists.
+//
+// LOAD-BEARING CONSTRAINT: this module must never import anything under
+// `@earendil-works/pi-ai/(api|providers)/` — pi's extension loader aliases the
+// bare `@earendil-works/pi-ai` prefix to its own compat bundle, which mangles
+// subpath specifiers into paths that do not exist. That failure typechecks
+// clean and only surfaces at extension load. It must not import provider.ts
+// either (which needs a pi-ai subpath at runtime). extension.test.ts guards
+// this with an import grep.
+import { GROK_MODELS, XAI_BASE_URL, XAI_PROVIDER_ID, loginXai, refreshXai, requireXaiOAuthCredential, } from "./xai-grok-build.js";
+// Identify as pi in the authorize URL.
+const EXTENSION_OPTS = { referrer: "pi" };
+// `usesCallbackServer` lives on OAuthProviderInterface and survives pi's
+// registration spread, but ProviderConfig's inline `oauth` type omits it.
+// Typing the const as Omit<…, "id"> gets it checked and dodges excess-property
+// checking at the use site.
+const oauth = {
+    name: "xAI (Grok subscription)",
+    usesCallbackServer: true,
+    async login(callbacks) {
+        return loginXai(toHost(callbacks), EXTENSION_OPTS);
+    },
+    async refreshToken(credentials) {
+        return refreshXai(requireXaiOAuthCredential(credentials));
+    },
+    getApiKey(credentials) {
+        // Sync and string-only, so the provider-level baseUrl below carries what
+        // the library adapter's toAuth() returns alongside the key.
+        return requireXaiOAuthCredential(credentials).access;
+    },
+};
+// Register synchronously inside the factory: pi drains pending registrations
+// before any session exists, which is what makes `pi --list-models` and
+// /login both see the provider.
+export default function xaiGrokBuild(pi) {
+    pi.registerProvider(XAI_PROVIDER_ID, {
+        name: "xAI Grok Build",
+        baseUrl: XAI_BASE_URL,
+        // OAuth only, on purpose: no `apiKey` entry means pi never offers an
+        // API-key row for this provider and env keys are ignored. The Grok
+        // subscription token is the sole credential in this project.
+        api: "openai-responses",
+        models: GROK_MODELS.map((model) => ({
+            id: model.id,
+            name: model.name,
+            reasoning: model.reasoning,
+            input: [...model.input],
+            cost: { ...model.cost },
+            contextWindow: model.contextWindow,
+            maxTokens: model.maxTokens,
+            compat: { ...model.compat },
+        })),
+        oauth,
+    });
+}
+function toHost(cb) {
+    return {
+        authUrl: (url, instructions) => cb.onAuth({ url, instructions }),
+        progress: (message) => cb.onProgress?.(message),
+        ...(cb.signal !== undefined ? { signal: cb.signal } : {}),
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,4 @@
+import { type Provider } from "@earendil-works/pi-ai";
+import { type XaiOptions } from "./xai-grok-build.js";
+export { GROK_43_MODEL, GROK_BUILD_MODEL, GROK_COMPOSER_MODEL, GROK_MODELS, XAI_BASE_URL, XAI_MODEL_ID, XAI_PROVIDER_ID, type XaiOptions, } from "./xai-grok-build.js";
+export declare function xaiGrokBuildResponsesProvider(options?: XaiOptions): Provider<"openai-responses">;

package/dist/provider.js

@@ -0,0 +1,44 @@
+// pi-ai library adapter for the Grok Build core: import this from server-side
+// code that composes a pi-ai / pi-agent Models registry. Keep it free of app
+// imports and side effects, and never import it from client code. The
+// extension adapter (extension.ts) must NOT import this module — the pi-ai
+// subpath import below is fatal under pi's extension loader.
+//
+// Auth is OAuth-only by design: API keys are not supported anywhere in this
+// project. The Grok subscription token is the sole credential.
+import { createProvider, } from "@earendil-works/pi-ai";
+import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
+import { GROK_MODELS, XAI_BASE_URL, XAI_PROVIDER_ID, loginXai, refreshXai, requireXaiOAuthCredential, } from "./xai-grok-build.js";
+export { GROK_43_MODEL, GROK_BUILD_MODEL, GROK_COMPOSER_MODEL, GROK_MODELS, XAI_BASE_URL, XAI_MODEL_ID, XAI_PROVIDER_ID, } from "./xai-grok-build.js";
+export function xaiGrokBuildResponsesProvider(options = {}) {
+    const opts = { ...options };
+    return createProvider({
+        id: XAI_PROVIDER_ID,
+        name: "xAI Grok Build",
+        baseUrl: XAI_BASE_URL,
+        auth: { oauth: xaiOAuthAuth(opts) },
+        models: [...GROK_MODELS],
+        api: openAIResponsesApi(),
+    });
+}
+function xaiOAuthAuth(opts) {
+    return {
+        name: "xAI (Grok subscription)",
+        async login(callbacks) {
+            return { type: "oauth", ...(await loginXai(toHost(callbacks), opts)) };
+        },
+        async refresh(credential) {
+            return { type: "oauth", ...(await refreshXai(requireXaiOAuthCredential(credential))) };
+        },
+        async toAuth(credential) {
+            return { apiKey: requireXaiOAuthCredential(credential).access, baseUrl: XAI_BASE_URL };
+        },
+    };
+}
+function toHost(cb) {
+    return {
+        authUrl: (url, instructions) => cb.notify({ type: "auth_url", url, instructions }),
+        progress: (message) => cb.notify({ type: "progress", message }),
+        ...(cb.signal !== undefined ? { signal: cb.signal } : {}),
+    };
+}

package/dist/xai-grok-build.d.ts

@@ -0,0 +1,161 @@
+export declare const XAI_PROVIDER_ID = "xai-grok-build";
+export declare const XAI_MODEL_ID = "grok-build-0.1";
+export declare const XAI_BASE_URL = "https://api.x.ai/v1";
+export declare const GROK_BUILD_MODEL: {
+    id: string;
+    name: string;
+    api: "openai-responses";
+    provider: string;
+    baseUrl: string;
+    reasoning: false;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    compat: {
+        readonly sendSessionIdHeader: false;
+        readonly supportsLongCacheRetention: false;
+    };
+};
+export declare const GROK_43_MODEL: {
+    id: string;
+    name: string;
+    api: "openai-responses";
+    provider: string;
+    baseUrl: string;
+    reasoning: true;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    compat: {
+        readonly sendSessionIdHeader: false;
+        readonly supportsLongCacheRetention: false;
+    };
+};
+export declare const GROK_COMPOSER_MODEL: {
+    id: string;
+    name: string;
+    api: "openai-responses";
+    provider: string;
+    baseUrl: string;
+    reasoning: false;
+    input: "text"[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    compat: {
+        readonly sendSessionIdHeader: false;
+        readonly supportsLongCacheRetention: false;
+    };
+};
+export declare const GROK_MODELS: readonly [{
+    id: string;
+    name: string;
+    api: "openai-responses";
+    provider: string;
+    baseUrl: string;
+    reasoning: false;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    compat: {
+        readonly sendSessionIdHeader: false;
+        readonly supportsLongCacheRetention: false;
+    };
+}, {
+    id: string;
+    name: string;
+    api: "openai-responses";
+    provider: string;
+    baseUrl: string;
+    reasoning: true;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    compat: {
+        readonly sendSessionIdHeader: false;
+        readonly supportsLongCacheRetention: false;
+    };
+}, {
+    id: string;
+    name: string;
+    api: "openai-responses";
+    provider: string;
+    baseUrl: string;
+    reasoning: false;
+    input: "text"[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    compat: {
+        readonly sendSessionIdHeader: false;
+        readonly supportsLongCacheRetention: false;
+    };
+}];
+export type XaiOptions = {
+    /**
+     * Authorization-URL `referrer` param identifying the host application.
+     * Defaults to "pi-grok-build"; the pi extension adapter passes "pi".
+     */
+    referrer?: string;
+};
+/**
+ * Everything the login flow needs from its host. Deliberately smaller than
+ * either pi surface: xAI's flow never prompts, only notifies.
+ */
+export type XaiLoginHost = {
+    authUrl(url: string, instructions: string): void;
+    progress(message: string): void;
+    signal?: AbortSignal;
+};
+/**
+ * `type`, not `interface` — needs an implicit index signature to be assignable
+ * to pi's OAuthCredential / OAuthCredentials (`[key: string]: unknown`).
+ * Exactly these four fields, nothing more: pi coding-agent's refresh path does
+ * a FULL REPLACE of the stored credential, so anything refresh omits is gone
+ * forever. Identity fields (idToken/email/subject) are deliberately not
+ * persisted — nothing reads them and the refresh grant may omit id_token.
+ */
+export type XaiOAuthCredential = {
+    access: string;
+    refresh: string;
+    expires: number;
+    tokenEndpoint: string;
+};
+/** pi hands back `Record<string, unknown>`. Narrow at the boundary; fail fast. */
+export declare function requireXaiOAuthCredential(value: Record<string, unknown>): XaiOAuthCredential;
+export declare function loginXai(host: XaiLoginHost, opts?: XaiOptions): Promise<XaiOAuthCredential>;
+export declare function refreshXai(credential: XaiOAuthCredential): Promise<XaiOAuthCredential>;