dsh-plugin-subscriptions 0.1.0

package/lib/providers/grok.js

@@ -0,0 +1,337 @@
+/**
+ * Grok (X Premium / xAI) subscription provider: OIDC-discovered OAuth against
+ * auth.x.ai with the Grok CLI client id, and streaming against the xAI
+ * Responses-style endpoint.
+ */
+import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
+import { decodeJwtPayload } from '../auth/jwt.js';
+import { resolveImages } from '../translate/resolved.js';
+import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
+export const GROK_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828';
+export const GROK_DISCOVERY_URL = 'https://auth.x.ai/.well-known/openid-configuration';
+export const GROK_API_URL = 'https://api.x.ai/v1/responses';
+const GROK_SCOPE = 'openid profile email offline_access grok-cli:access api:access';
+const GROK_CALLBACK_PATH = '/callback';
+const GROK_CONTEXT_WINDOW = 256_000;
+const GROK_DEFAULT_MAX_TOKENS = 32_000;
+/** Refresh when the access token has less than this much life left. */
+export const GROK_PREEMPT_MS = 2 * 60_000;
+/** A discovered URL must be https on x.ai or a subdomain; anything else is a hostile document. */
+function assertXaiEndpoint(url, field) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`grok OIDC discovery returned an invalid ${field}`);
+    }
+    if (parsed.protocol !== 'https:'
+        || (parsed.hostname !== 'x.ai' && !parsed.hostname.endsWith('.x.ai'))) {
+        throw new Error(`grok OIDC discovery returned a non-x.ai ${field}: ${url}`);
+    }
+    return url;
+}
+let discoveryCache;
+/**
+ * Resolve the xAI OIDC endpoints (cached after the first fetch).
+ * @returns validated authorization and token endpoints.
+ */
+export async function grokDiscovery() {
+    if (discoveryCache !== undefined)
+        return discoveryCache;
+    const response = await fetch(GROK_DISCOVERY_URL);
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'grok OIDC discovery');
+    const document = await response.json();
+    if (typeof document.authorization_endpoint !== 'string' || typeof document.token_endpoint !== 'string') {
+        throw new Error('grok OIDC discovery document is missing endpoints');
+    }
+    discoveryCache = {
+        authorizationEndpoint: assertXaiEndpoint(document.authorization_endpoint, 'authorization_endpoint'),
+        tokenEndpoint: assertXaiEndpoint(document.token_endpoint, 'token_endpoint'),
+    };
+    return discoveryCache;
+}
+/**
+ * Build the grok flow facts for the OAuth flow engine (async because the
+ * authorize URL comes from OIDC discovery).
+ * @returns the flow spec for one attempt.
+ */
+export async function grokFlow() {
+    const discovery = await grokDiscovery();
+    return {
+        callbackPath: GROK_CALLBACK_PATH,
+        listen: { host: '127.0.0.1', ports: [56121] },
+        buildAuthorizeUrl({ redirectUri, state, pkce, nonce }) {
+            const params = new URLSearchParams({
+                response_type: 'code',
+                client_id: GROK_CLIENT_ID,
+                redirect_uri: redirectUri,
+                scope: GROK_SCOPE,
+                code_challenge: pkce.challenge,
+                code_challenge_method: 'S256',
+                state,
+                nonce,
+                plan: 'generic',
+                referrer: 'dsh-plugin-subscriptions',
+            });
+            return `${discovery.authorizationEndpoint}?${params.toString()}`;
+        },
+    };
+}
+/** Pick a display account from an id token's claims. */
+function grokAccount(idToken) {
+    const payload = idToken === undefined ? undefined : decodeJwtPayload(idToken);
+    const claim = payload?.email ?? payload?.preferred_username ?? payload?.name ?? payload?.sub;
+    return typeof claim === 'string' && claim.length > 0 ? claim : undefined;
+}
+/** Build a session from a token response. */
+function grokSession(tokens, tokenEndpoint, fallbackRefreshToken) {
+    if (typeof tokens.access_token !== 'string' || tokens.access_token.length === 0) {
+        throw new Error('grok token endpoint returned no access token');
+    }
+    const refreshToken = tokens.refresh_token ?? fallbackRefreshToken;
+    if (refreshToken === undefined)
+        throw new Error('grok token endpoint returned no refresh token');
+    if (typeof tokens.expires_in !== 'number' || tokens.expires_in <= 0) {
+        throw new Error('grok token endpoint returned no usable expiry');
+    }
+    const account = grokAccount(tokens.id_token);
+    return {
+        accessToken: tokens.access_token,
+        refreshToken,
+        expiresAt: Date.now() + tokens.expires_in * 1000,
+        tokenEndpoint,
+        ...typeof tokens.scope === 'string' ? { scopes: tokens.scope } : {},
+        ...account === undefined ? {} : { account },
+    };
+}
+/**
+ * Exchange an authorization code for a grok session (form-encoded grant that
+ * echoes the PKCE challenge as well as the verifier, per the xAI flow).
+ * A 403 here means the X plan lacks the API OAuth entitlement.
+ * @param code - the authorization code from the callback.
+ * @param verifier - the PKCE verifier minted for the attempt.
+ * @param redirectUri - the attempt's redirect URI.
+ * @param challenge - the PKCE challenge sent at authorize time.
+ * @returns the session to store.
+ */
+export async function exchangeGrokCode(code, verifier, redirectUri, challenge) {
+    const discovery = await grokDiscovery();
+    const response = await fetch(discovery.tokenEndpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: GROK_CLIENT_ID,
+            code,
+            redirect_uri: redirectUri,
+            code_verifier: verifier,
+            code_challenge: challenge,
+            code_challenge_method: 'S256',
+        }).toString(),
+    });
+    if (response.status === 403) {
+        throw new OAuthEndpointError('grok token endpoint refused the exchange (HTTP 403): your X plan does not include '
+            + 'the API OAuth entitlement; an X Premium or xAI subscription with API access is required', 403);
+    }
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'grok');
+    return grokSession(await response.json(), discovery.tokenEndpoint);
+}
+/**
+ * Refresh a grok session (form-encoded grant).
+ * @param session - the stored session.
+ * @returns the fresh session to store.
+ */
+export async function refreshGrok(session) {
+    const response = await fetch(session.tokenEndpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'refresh_token',
+            client_id: GROK_CLIENT_ID,
+            refresh_token: session.refreshToken,
+        }).toString(),
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'grok');
+    const next = grokSession(await response.json(), session.tokenEndpoint, session.refreshToken);
+    return {
+        ...next,
+        ...session.account === undefined ? {} : { account: session.account },
+        ...next.scopes === undefined && session.scopes !== undefined ? { scopes: session.scopes } : {},
+    };
+}
+/**
+ * Whether a grok refresh failure means the login is permanently gone.
+ * @param error - the thrown refresh error.
+ * @returns true when re-login is the only fix.
+ */
+export function isGrokPermanentRefreshError(error) {
+    return error instanceof OAuthEndpointError && error.oauthCode === 'invalid_grant';
+}
+export const GROK_MODELS_URL = 'https://api.x.ai/v1/models';
+/**
+ * Input modalities for one grok model: chat models (grok-4 family) accept
+ * images; code and embedding models are text-only.
+ */
+function grokModalities(id) {
+    return /code|embed/i.test(id) ? ['text'] : ['text', 'image'];
+}
+/**
+ * The /v1/models list also serves generation models that cannot chat
+ * (grok-imagine-image*, grok-imagine-video*) and embedding models; the picker
+ * must not offer them. Heuristic over the id substring, verified against the
+ * live catalog (grok-build-0.1 and the grok-4 family pass).
+ */
+function isChatModel(id) {
+    return !/imagine|image-|video|embed/i.test(id);
+}
+/**
+ * Fetch the live grok model list.
+ * @param session - the stored session (used as-is; never refreshed here).
+ * @param fetchFn - fetch implementation (injectable for tests).
+ * @returns discovered chat models in endpoint order (id doubles as the name).
+ */
+export async function fetchGrokModels(session, fetchFn = fetch) {
+    const response = await fetchFn(GROK_MODELS_URL, {
+        headers: {
+            'authorization': `Bearer ${session.accessToken}`,
+            'accept': 'application/json',
+            ...attributionHeaders(),
+        },
+    });
+    if (!response.ok)
+        throw await oauthEndpointError(response, 'grok models');
+    const payload = await response.json();
+    if (!Array.isArray(payload.data))
+        throw new Error('grok models endpoint returned no data array');
+    const seen = new Set();
+    const discovered = [];
+    for (const entry of payload.data) {
+        if (typeof entry.id !== 'string' || entry.id.length === 0 || seen.has(entry.id))
+            continue;
+        if (!isChatModel(entry.id))
+            continue;
+        seen.add(entry.id);
+        discovered.push({ id: entry.id, name: entry.id });
+    }
+    // An empty catalog from a 200 response is treated as a discovery failure so
+    // the adapter falls back to the static catalog instead of vanishing from
+    // the picker.
+    if (discovered.length === 0)
+        throw new Error('grok models endpoint returned an empty catalog');
+    return discovered;
+}
+/** Grok wire adapter: one instance serves the `grok` provider route. */
+export class GrokAdapter extends LlmAdapter {
+    options;
+    catalog = new ModelCatalogCache();
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    providerInfo(provider) {
+        return { id: provider, name: 'Grok (Subscription)' };
+    }
+    staticModels(provider) {
+        return this.options.models.map(model => ({
+            provider,
+            id: model.id,
+            name: model.name ?? model.id,
+            inputModalities: model.inputModalities ?? grokModalities(model.id),
+        }));
+    }
+    async listModels(provider) {
+        // Not logged in → empty catalog, so the web picker drops the provider.
+        const session = await this.options.tokens.peek();
+        if (session === undefined)
+            return [];
+        if (!this.options.discovery)
+            return this.staticModels(provider);
+        try {
+            const discovered = await this.catalog.get(() => fetchGrokModels(session, this.options.fetchFn));
+            return discovered.map(model => ({
+                provider,
+                id: model.id,
+                name: model.name,
+                inputModalities: grokModalities(model.id),
+            }));
+        }
+        catch (error) {
+            if (error instanceof OAuthEndpointError && error.status === 401)
+                this.catalog.invalidate();
+            this.options.onWarn?.(`grok model discovery failed; using the built-in catalog (${errorChain(error)})`);
+            return this.staticModels(provider);
+        }
+    }
+    resolveModel(provider, model) {
+        const discovered = this.options.discovery
+            ? this.catalog.cached()?.find(entry => entry.id === model)
+            : undefined;
+        const configured = this.options.models.find(entry => entry.id === model);
+        return Promise.resolve({
+            provider,
+            id: model,
+            name: discovered?.name ?? configured?.name ?? model,
+            inputModalities: configured?.inputModalities ?? grokModalities(model),
+            context: { contextWindow: configured?.contextWindow ?? GROK_CONTEXT_WINDOW },
+            defaultMaxTokens: configured?.maxTokens ?? GROK_DEFAULT_MAX_TOKENS,
+            // No reasoning metadata: effort selection is not exposed for grok.
+        });
+    }
+    async *stream(options) {
+        const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);
+        try {
+            let session = await this.options.tokens.session();
+            let response = await this.request(options, session, watchdog.signal);
+            if (response.status === 401) {
+                // One forced refresh + retry on an unexpired-but-rejected token.
+                session = await this.options.tokens.session(true);
+                response = await this.request(options, session, watchdog.signal);
+            }
+            if (!response.ok)
+                throw await httpLlmError(response, 'grok API');
+            if (response.body === null) {
+                throw new LlmError('grok API returned no response body', EMPTY_RESPONSE_CODE);
+            }
+            yield* streamResponses(response.body, () => { watchdog.pulse(); });
+        }
+        catch (error) {
+            throw mapFetchFailure('grok API', error, watchdog, options.signal);
+        }
+        finally {
+            watchdog.stop();
+        }
+    }
+    async request(options, session, signal) {
+        const messages = await resolveImages(options.messages, this.options.resolveAttachments?.(), signal);
+        const { instructions, input } = toResponsesInput(messages, options.system);
+        const body = {
+            model: options.model,
+            ...instructions === undefined ? {} : { instructions },
+            input,
+            ...options.tools !== undefined && options.tools.length > 0
+                ? { tools: toResponsesTools(options.tools) }
+                : {},
+            tool_choice: 'auto',
+            parallel_tool_calls: true,
+            ...options.maxTokens !== undefined ? { max_output_tokens: options.maxTokens } : {},
+            store: false,
+            stream: true,
+        };
+        return fetch(GROK_API_URL, {
+            method: 'POST',
+            headers: {
+                'authorization': `Bearer ${session.accessToken}`,
+                'accept': 'text/event-stream',
+                'content-type': 'application/json',
+                ...attributionHeaders(),
+            },
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+}

package/lib/tools/image-generate.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `image_generate` tool: generate images through the ChatGPT/Codex
+ * subscription's image endpoint and save them as PNG files under the harness
+ * home. Mirrors codex-rs `codex-api/src/images.rs`: POST
+ * `/backend-api/codex/images/generations` with the responses call's auth
+ * headers; the response carries base64 PNG data.
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { CodexSession } from '../auth/store.js';
+import { TokenManager } from '../providers/common.js';
+import type { FetchFn } from '../providers/common.js';
+/** Endpoint the generation request is posted to. */
+export declare const IMAGE_GENERATE_URL = "https://chatgpt.com/backend-api/codex/images/generations";
+/** The image model the codex subscription endpoint serves. */
+export declare const IMAGE_GENERATE_MODEL = "gpt-image-2";
+/** Dependencies of the `image_generate` tool. */
+export interface ImageGenerateToolOptions {
+    /** Codex session source; a missing session throws the log-in hint. */
+    tokens: TokenManager<CodexSession>;
+    /** Fetch implementation (injectable for tests). */
+    fetchFn?: FetchFn;
+    /** Directory override for saved images (defaults under the harness home). */
+    imagesDir?: string;
+}
+/** The wire request body for one generation call. */
+export interface ImageGenerateRequestBody {
+    prompt: string;
+    model: string;
+    size?: string;
+    quality?: string;
+}
+/**
+ * Assemble the request body from tool arguments (hand-checks the non-empty
+ * prompt the schema DSL cannot express).
+ */
+export declare function buildImageGenerateBody(args: {
+    prompt: string;
+    size?: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
+    quality?: 'low' | 'medium' | 'high' | 'auto';
+}): ImageGenerateRequestBody;
+/** One generated image decoded from the response. */
+export interface GeneratedImage {
+    /** PNG bytes. */
+    data: Buffer;
+    /** Provider-revised prompt, when the response carries one. */
+    revisedPrompt?: string;
+}
+/**
+ * Parse the generations response into decodable images. Throws when the
+ * payload carries no usable `b64_json` entries.
+ */
+export declare function parseImageGenerateResponse(payload: unknown): GeneratedImage[];
+/** Directory the generated PNG files are written to. */
+export declare function imagesDirectory(): string;
+/**
+ * Build the `image_generate` tool definition.
+ * @param options - codex session source, fetch implementation, and image directory.
+ * @returns the tool to register on `ctx.tools`.
+ */
+export declare function createImageGenerateTool(options: ImageGenerateToolOptions): ToolDefinition;

package/lib/tools/image-generate.js

@@ -0,0 +1,142 @@
+/**
+ * `image_generate` tool: generate images through the ChatGPT/Codex
+ * subscription's image endpoint and save them as PNG files under the harness
+ * home. Mirrors codex-rs `codex-api/src/images.rs`: POST
+ * `/backend-api/codex/images/generations` with the responses call's auth
+ * headers; the response carries base64 PNG data.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { httpLlmError, TokenManager } from '../providers/common.js';
+/** Endpoint the generation request is posted to. */
+export const IMAGE_GENERATE_URL = 'https://chatgpt.com/backend-api/codex/images/generations';
+/** The image model the codex subscription endpoint serves. */
+export const IMAGE_GENERATE_MODEL = 'gpt-image-2';
+/**
+ * Assemble the request body from tool arguments (hand-checks the non-empty
+ * prompt the schema DSL cannot express).
+ */
+export function buildImageGenerateBody(args) {
+    const prompt = args.prompt.trim();
+    if (prompt.length === 0)
+        throw new Error('image_generate: prompt must be a non-empty string');
+    return {
+        prompt,
+        model: IMAGE_GENERATE_MODEL,
+        ...args.size === undefined ? {} : { size: args.size },
+        ...args.quality === undefined ? {} : { quality: args.quality },
+    };
+}
+/**
+ * Parse the generations response into decodable images. Throws when the
+ * payload carries no usable `b64_json` entries.
+ */
+export function parseImageGenerateResponse(payload) {
+    const body = typeof payload === 'object' && payload !== null ? payload : {};
+    const entries = Array.isArray(body.data) ? body.data : [];
+    const images = [];
+    for (const entry of entries) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        if (typeof record.b64_json !== 'string' || record.b64_json.length === 0)
+            continue;
+        images.push({
+            data: Buffer.from(record.b64_json, 'base64'),
+            ...typeof record.revised_prompt === 'string' && record.revised_prompt.length > 0
+                ? { revisedPrompt: record.revised_prompt }
+                : {},
+        });
+    }
+    if (images.length === 0)
+        throw new Error('image_generate: the response carried no image data');
+    return images;
+}
+/** Directory the generated PNG files are written to. */
+export function imagesDirectory() {
+    return dshHomePath('plugins', 'subscriptions', 'images');
+}
+/** Timestamped, collision-safe file name for one generated image. */
+function imageFileName(index) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `image-${stamp}-${Math.random().toString(36).slice(2, 8)}-${index}.png`;
+}
+/** Bound a call-card title's prompt. */
+function truncate(text, max = 60) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/**
+ * Build the `image_generate` tool definition.
+ * @param options - codex session source, fetch implementation, and image directory.
+ * @returns the tool to register on `ctx.tools`.
+ */
+export function createImageGenerateTool(options) {
+    return defineTool({
+        name: 'image_generate',
+        description: 'Generate an image with the ChatGPT subscription (gpt-image-2) and save it as a PNG file. '
+            + 'Returns the saved file paths.',
+        parameters: {
+            prompt: { type: 'string', required: true, description: 'What the image should show.' },
+            size: {
+                type: 'string',
+                enum: ['1024x1024', '1024x1536', '1536x1024', 'auto'],
+                description: 'Image dimensions; omit for the provider default.',
+            },
+            quality: {
+                type: 'string',
+                enum: ['low', 'medium', 'high', 'auto'],
+                description: 'Rendering quality; omit for the provider default.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    paths: { type: 'array', items: { type: 'string' }, required: true },
+                    revisedPrompt: { type: 'string' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Saved ${value.paths.length} image(s):\n${value.paths.map(path => `- ${path}`).join('\n')}`
+                        + (value.revisedPrompt === undefined ? '' : `\n\nRevised prompt: ${value.revisedPrompt}`),
+                }],
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `image_generate: ${truncate(args.prompt)}`,
+        }),
+        async execute(args, exec) {
+            const body = buildImageGenerateBody(args);
+            const session = await options.tokens.session();
+            const response = await (options.fetchFn ?? fetch)(IMAGE_GENERATE_URL, {
+                method: 'POST',
+                headers: {
+                    'authorization': `Bearer ${session.accessToken}`,
+                    'chatgpt-account-id': session.accountId,
+                    'originator': 'codex_cli_rs',
+                    'content-type': 'application/json',
+                    'accept': 'application/json',
+                },
+                body: JSON.stringify(body),
+                signal: exec.signal,
+            });
+            if (!response.ok)
+                throw await httpLlmError(response, 'image_generate');
+            const images = parseImageGenerateResponse(await response.json());
+            const directory = options.imagesDir ?? imagesDirectory();
+            await mkdir(directory, { recursive: true });
+            const paths = [];
+            for (const [index, image] of images.entries()) {
+                const path = join(directory, imageFileName(index));
+                await writeFile(path, image.data);
+                paths.push(path);
+            }
+            const revisedPrompt = images.find(image => image.revisedPrompt !== undefined)?.revisedPrompt;
+            return { paths, ...revisedPrompt === undefined ? {} : { revisedPrompt } };
+        },
+    });
+}

package/lib/tools/x-search.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `x_search` tool: run xAI's hosted X (Twitter) search through the grok
+ * subscription's OAuth session. The wire call is a non-streaming Responses
+ * request carrying the built-in `x_search` tool definition; the canonical
+ * output is `{ answer, citations }`.
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { GrokSession } from '../auth/store.js';
+import { TokenManager } from '../providers/common.js';
+import type { FetchFn } from '../providers/common.js';
+/** Endpoint the search request is posted to. */
+export declare const X_SEARCH_URL = "https://api.x.ai/v1/responses";
+/** Grok model the search runs on (a catalog model of the grok provider). */
+export declare const X_SEARCH_MODEL = "grok-4";
+/** Dependencies of the `x_search` tool. */
+export interface XSearchToolOptions {
+    /** Grok session source; a missing session throws the log-in hint. */
+    tokens: TokenManager<GrokSession>;
+    /** Fetch implementation (injectable for tests). */
+    fetchFn?: FetchFn;
+}
+/** Normalized, validated arguments of one search call. */
+interface XSearchRequest {
+    query: string;
+    tool: Record<string, unknown>;
+}
+/**
+ * Validate and assemble the request facts from tool arguments. Throws plain
+ * Errors for argument problems the schema DSL cannot express (non-empty
+ * query, handle caps, mutually exclusive filters).
+ */
+export declare function buildXSearchRequest(args: {
+    query: string;
+    allowed_x_handles?: string[];
+    excluded_x_handles?: string[];
+    from_date?: string;
+    to_date?: string;
+    enable_image_understanding?: boolean;
+    enable_video_understanding?: boolean;
+}): XSearchRequest;
+/** The canonical output of one successful search. */
+interface XSearchOutput {
+    answer: string;
+    citations: string[];
+}
+/**
+ * Extract the answer text and citation URLs from a Responses payload: the
+ * `output_text` shortcut or message output parts for the answer, and both
+ * top-level `citations` and inline `url_citation` annotations for sources.
+ */
+export declare function parseXSearchResponse(payload: unknown): XSearchOutput;
+/**
+ * Build the `x_search` tool definition.
+ * @param options - grok session source and fetch implementation.
+ * @returns the tool to register on `ctx.tools`.
+ */
+export declare function createXSearchTool(options: XSearchToolOptions): ToolDefinition;
+export {};