dsh-plugin-subscriptions 0.3.1 → 0.4.1

package/lib/providers/codex.js

@@ -189,8 +189,31 @@ export function isCodexPermanentRefreshError(error) {
         && PERMANENT_REFRESH_CODES.has(error.oauthCode);
 }
 export const CODEX_USAGE_URL = 'https://chatgpt.com/backend-api/wham/usage';
+/** Seconds of the canonical 5-hour session and 7-day weekly windows. */
+const SESSION_WINDOW_SECONDS = 5 * 60 * 60;
+const WEEKLY_WINDOW_SECONDS = 7 * 24 * 60 * 60;
+/** Whether a reported duration approximately matches the expected window length. */
+function matchesWindow(seconds, expected) {
+    return seconds >= expected * 0.95 && seconds <= expected * 1.05;
+}
+/**
+ * Classify a wham/usage window by its reported duration. The backend has been
+ * observed to place the weekly lane in `primary_window` with no secondary
+ * window, so slot position alone is unreliable; the caller's positional
+ * fallback applies only when the duration is absent.
+ */
+function codexWindowKind(window, fallback) {
+    const seconds = window.limit_window_seconds;
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0)
+        return fallback;
+    if (matchesWindow(seconds, SESSION_WINDOW_SECONDS))
+        return 'session';
+    if (matchesWindow(seconds, WEEKLY_WINDOW_SECONDS))
+        return 'weekly';
+    return 'other';
+}
 /** Map one wham/usage window into a {@link UsageWindow}; undefined when unusable. */
-function codexUsageWindow(value, kind) {
+function codexUsageWindow(value, fallbackKind) {
     if (typeof value !== 'object' || value === null)
         return undefined;
     const window = value;
@@ -203,13 +226,20 @@ function codexUsageWindow(value, kind) {
     else if (typeof window.reset_after_seconds === 'number' && window.reset_after_seconds > 0) {
         resetsAt = Date.now() + window.reset_after_seconds * 1000;
     }
-    return { kind, usedPercent: window.used_percent, ...resetsAt === undefined ? {} : { resetsAt } };
+    return {
+        kind: codexWindowKind(window, fallbackKind),
+        usedPercent: window.used_percent,
+        ...resetsAt === undefined ? {} : { resetsAt },
+    };
 }
 /**
  * Fetch the codex subscription usage from the ChatGPT backend wham/usage
  * endpoint (the source of the codex CLI `/status` rate-limit lines). The
- * primary window is the rolling session (5-hour) lane, the secondary window
- * the weekly lane; the lookup itself consumes no rate-limit budget.
+ * windows are classified by their reported duration (`limit_window_seconds`)
+ * rather than by slot, since the backend has been observed to report the
+ * weekly lane as `primary_window` without a secondary window; slot order is
+ * kept only as a fallback when the duration is absent. The lookup itself
+ * consumes no rate-limit budget.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param signal - caller cancellation from the RPC transport.

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

@@ -1,27 +1,37 @@
 /**
- * `image_generate` tool: generate images through the ChatGPT/Codex
- * subscription's image endpoint, save them as PNG files under the harness
- * home, and — when the deployment mounts an attachment store and the calling
- * route declares image input — also commit the bytes as durable attachments
- * so the images render inline and enter model context (the same path
- * `read_image` uses). 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.
+ * `image_generate` tool: generate images through a subscription image
+ * endpoint, save them under the harness home, and — when the deployment
+ * mounts an attachment store and the calling route declares image input —
+ * also commit the bytes as durable attachments so the images render inline
+ * and enter model context (the same path `read_image` uses).
+ *
+ * Provider selection: the `provider` argument names the preferred provider
+ * (default `gpt`, i.e. the ChatGPT/Codex subscription serving gpt-image-2 —
+ * mirrors codex-rs `codex-api/src/images.rs`); when the preferred one is
+ * logged out the other serves as fallback (`grok` is grok-imagine-image-2.0
+ * via `api.x.ai/v1/images/generations` with `response_format: 'b64_json'`).
+ * Both answer the OpenAI images shape (`data[].b64_json`).
  */
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
 import type { LlmRuntime } from '@deepseek-ai/dsh-llm';
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
-import type { CodexSession } from '../auth/store.js';
+import type { CodexSession, GrokSession } from '../auth/store.js';
 import { TokenManager } from '../providers/common.js';
 import type { FetchFn } from '../providers/common.js';
-/** Endpoint the generation request is posted to. */
+/** Endpoint the codex 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";
+/** Endpoint the grok generation request is posted to. */
+export declare const GROK_IMAGE_GENERATE_URL = "https://api.x.ai/v1/images/generations";
+/** The image model the grok subscription endpoint serves. */
+export declare const GROK_IMAGE_GENERATE_MODEL = "grok-imagine-image-2.0";
 /** Dependencies of the `image_generate` tool. */
 export interface ImageGenerateToolOptions {
-    /** Codex session source; a missing session throws the log-in hint. */
-    tokens: TokenManager<CodexSession>;
+    /** Codex session source; the default preferred provider (`provider: 'gpt'`). */
+    codexTokens?: TokenManager<CodexSession>;
+    /** Grok session source; preferred when the call passes `provider: 'grok'`. */
+    grokTokens?: TokenManager<GrokSession>;
     /** Fetch implementation (injectable for tests). */
     fetchFn?: FetchFn;
     /** Directory override for saved images (defaults under the harness home). */
@@ -38,15 +48,33 @@ export interface ImageGenerateRequestBody {
     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: {
+/** The tool's own argument shape, shared by both provider body builders. */
+export interface ImageGenerateArgs {
     prompt: string;
     size?: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
     quality?: 'low' | 'medium' | 'high' | 'auto';
-}): ImageGenerateRequestBody;
+    /** Preferred provider; the other one serves when the preferred is logged out. */
+    provider?: 'gpt' | 'grok';
+}
+/**
+ * Assemble the codex request body from tool arguments (hand-checks the
+ * non-empty prompt the schema DSL cannot express).
+ */
+export declare function buildImageGenerateBody(args: ImageGenerateArgs): ImageGenerateRequestBody;
+/** The wire request body for one grok generation call. */
+export interface GrokImageGenerateRequestBody {
+    prompt: string;
+    model: string;
+    response_format: 'b64_json';
+    aspect_ratio?: string;
+    quality?: 'low' | 'medium';
+}
+/**
+ * Assemble the grok request body from the same tool arguments: `size` maps
+ * onto the nearest `aspect_ratio`, and `quality` folds into grok's low/medium
+ * pair (`high` → `medium`, `auto` → provider default).
+ */
+export declare function buildGrokImageGenerateBody(args: ImageGenerateArgs): GrokImageGenerateRequestBody;
 /** One generated image decoded from the response. */
 export interface GeneratedImage {
     /** PNG bytes. */
@@ -59,8 +87,16 @@ export interface GeneratedImage {
  * payload carries no usable `b64_json` entries.
  */
 export declare function parseImageGenerateResponse(payload: unknown): GeneratedImage[];
-/** Directory the generated PNG files are written to. */
+/** Directory the generated image files are written to. */
 export declare function imagesDirectory(): string;
+/** Media types the attachment store accepts and this tool can produce. */
+export type GeneratedImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp';
+/**
+ * Sniff a generated image's media type from its magic bytes (codex serves
+ * PNG; grok's format is undocumented, so trust the bytes). Unrecognized data
+ * defaults to PNG, matching the historical behavior.
+ */
+export declare function sniffImageMediaType(data: Buffer): GeneratedImageMediaType;
 /**
  * Build the `image_generate` tool definition.
  * @param options - codex session source, fetch implementation, and image directory.

package/lib/tools/image-generate.js

@@ -1,12 +1,16 @@
 /**
- * `image_generate` tool: generate images through the ChatGPT/Codex
- * subscription's image endpoint, save them as PNG files under the harness
- * home, and — when the deployment mounts an attachment store and the calling
- * route declares image input — also commit the bytes as durable attachments
- * so the images render inline and enter model context (the same path
- * `read_image` uses). 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.
+ * `image_generate` tool: generate images through a subscription image
+ * endpoint, save them under the harness home, and — when the deployment
+ * mounts an attachment store and the calling route declares image input —
+ * also commit the bytes as durable attachments so the images render inline
+ * and enter model context (the same path `read_image` uses).
+ *
+ * Provider selection: the `provider` argument names the preferred provider
+ * (default `gpt`, i.e. the ChatGPT/Codex subscription serving gpt-image-2 —
+ * mirrors codex-rs `codex-api/src/images.rs`); when the preferred one is
+ * logged out the other serves as fallback (`grok` is grok-imagine-image-2.0
+ * via `api.x.ai/v1/images/generations` with `response_format: 'b64_json'`).
+ * Both answer the OpenAI images shape (`data[].b64_json`).
  */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
@@ -15,13 +19,17 @@ import { AttachmentId } from '@deepseek-ai/dsh-attachment';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { httpLlmError, TokenManager } from '../providers/common.js';
-/** Endpoint the generation request is posted to. */
+/** Endpoint the codex 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';
+/** Endpoint the grok generation request is posted to. */
+export const GROK_IMAGE_GENERATE_URL = 'https://api.x.ai/v1/images/generations';
+/** The image model the grok subscription endpoint serves. */
+export const GROK_IMAGE_GENERATE_MODEL = 'grok-imagine-image-2.0';
 /**
- * Assemble the request body from tool arguments (hand-checks the non-empty
- * prompt the schema DSL cannot express).
+ * Assemble the codex 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();
@@ -34,6 +42,33 @@ export function buildImageGenerateBody(args) {
         ...args.quality === undefined ? {} : { quality: args.quality },
     };
 }
+/** The codex `size` values mapped onto grok aspect ratios. */
+const GROK_ASPECT_RATIOS = {
+    '1024x1024': '1:1',
+    '1024x1536': '2:3',
+    '1536x1024': '3:2',
+    'auto': 'auto',
+};
+/**
+ * Assemble the grok request body from the same tool arguments: `size` maps
+ * onto the nearest `aspect_ratio`, and `quality` folds into grok's low/medium
+ * pair (`high` → `medium`, `auto` → provider default).
+ */
+export function buildGrokImageGenerateBody(args) {
+    const prompt = args.prompt.trim();
+    if (prompt.length === 0)
+        throw new Error('image_generate: prompt must be a non-empty string');
+    const quality = args.quality === 'low' ? 'low'
+        : args.quality === 'medium' || args.quality === 'high' ? 'medium'
+            : undefined;
+    return {
+        prompt,
+        model: GROK_IMAGE_GENERATE_MODEL,
+        response_format: 'b64_json',
+        ...args.size === undefined ? {} : { aspect_ratio: GROK_ASPECT_RATIOS[args.size] },
+        ...quality === undefined ? {} : { quality },
+    };
+}
 /**
  * Parse the generations response into decodable images. Throws when the
  * payload carries no usable `b64_json` entries.
@@ -59,14 +94,33 @@ export function parseImageGenerateResponse(payload) {
         throw new Error('image_generate: the response carried no image data');
     return images;
 }
-/** Directory the generated PNG files are written to. */
+/** Directory the generated image files are written to. */
 export function imagesDirectory() {
     return dshHomePath('plugins', 'subscriptions', 'images');
 }
+/**
+ * Sniff a generated image's media type from its magic bytes (codex serves
+ * PNG; grok's format is undocumented, so trust the bytes). Unrecognized data
+ * defaults to PNG, matching the historical behavior.
+ */
+export function sniffImageMediaType(data) {
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff)
+        return 'image/jpeg';
+    if (data.length >= 12 && data.toString('latin1', 0, 4) === 'RIFF' && data.toString('latin1', 8, 12) === 'WEBP') {
+        return 'image/webp';
+    }
+    return 'image/png';
+}
+/** File extension for one sniffed media type. */
+const MEDIA_TYPE_EXTENSIONS = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+};
 /** Timestamped, collision-safe file name for one generated image. */
-function imageFileName(index) {
+function imageFileName(index, mediaType) {
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    return `image-${stamp}-${Math.random().toString(36).slice(2, 8)}-${index}.png`;
+    return `image-${stamp}-${Math.random().toString(36).slice(2, 8)}-${index}.${MEDIA_TYPE_EXTENSIONS[mediaType]}`;
 }
 /** Bound a call-card title's prompt. */
 function truncate(text, max = 60) {
@@ -127,7 +181,10 @@ function imageGenerateText(value) {
 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. '
+        description: 'Generate an image with the ChatGPT subscription (gpt-image-2) or the Grok '
+            + 'subscription (grok-imagine-image-2.0) and save it as an image file. The `provider` '
+            + 'parameter picks the preferred provider (default gpt); when the preferred one is logged '
+            + 'out the other serves as fallback. '
             + 'Returns the saved file paths; on image-capable models the image itself is attached.',
         parameters: {
             prompt: { type: 'string', required: true, description: 'What the image should show.' },
@@ -141,6 +198,11 @@ export function createImageGenerateTool(options) {
                 enum: ['low', 'medium', 'high', 'auto'],
                 description: 'Rendering quality; omit for the provider default.',
             },
+            provider: {
+                type: 'string',
+                enum: ['gpt', 'grok'],
+                description: 'Preferred provider (default gpt); the other one serves as fallback when the preferred is logged out.',
+            },
         },
         output: {
             schema: {
@@ -180,30 +242,67 @@ export function createImageGenerateTool(options) {
             content: result.content.filter(block => block.type === 'text'),
         }),
         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,
-            });
+            const fetchFn = options.fetchFn ?? fetch;
+            // Provider selection: the preferred provider (default gpt) when logged
+            // in, the other one as the fallback. A configured-but-logged-out manager
+            // still resolves through `session()` below so the standard log-in hint
+            // surfaces.
+            const preferGrok = args.provider === 'grok';
+            const codexReady = options.codexTokens !== undefined && await options.codexTokens.hasSession();
+            const grokReady = options.grokTokens !== undefined && await options.grokTokens.hasSession();
+            const useGrok = preferGrok ? grokReady : grokReady && !codexReady;
+            const useCodex = !useGrok && codexReady;
+            let response;
+            if (useCodex && options.codexTokens !== undefined) {
+                const session = await options.codexTokens.session();
+                response = await fetchFn(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(buildImageGenerateBody(args)),
+                    signal: exec.signal,
+                });
+            }
+            else if (useGrok && options.grokTokens !== undefined) {
+                const session = await options.grokTokens.session();
+                response = await fetchFn(GROK_IMAGE_GENERATE_URL, {
+                    method: 'POST',
+                    headers: {
+                        'authorization': `Bearer ${session.accessToken}`,
+                        'content-type': 'application/json',
+                        'accept': 'application/json',
+                    },
+                    body: JSON.stringify(buildGrokImageGenerateBody(args)),
+                    signal: exec.signal,
+                });
+            }
+            else {
+                const manager = preferGrok
+                    ? options.grokTokens ?? options.codexTokens
+                    : options.codexTokens ?? options.grokTokens;
+                if (manager === undefined)
+                    throw new Error('image_generate: no image provider is configured');
+                await manager.session(); // logged out: throws the provider's log-in hint
+                throw new Error('image_generate: no image provider is logged in');
+            }
             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 = [];
+            const mediaTypes = [];
             for (const [index, image] of images.entries()) {
-                const path = join(directory, imageFileName(index));
+                const mediaType = sniffImageMediaType(image.data);
+                const path = join(directory, imageFileName(index, mediaType));
                 await writeFile(path, image.data);
                 paths.push(path);
+                mediaTypes.push(mediaType);
             }
             // Inline display requires durable attachment references, and those may
             // only enter session history on a route that declares image input.
@@ -216,7 +315,7 @@ export function createImageGenerateTool(options) {
                 for (const [index, image] of images.entries()) {
                     const ref = await attachments.saveImage({
                         data: image.data,
-                        mediaType: 'image/png',
+                        mediaType: mediaTypes[index],
                         name: basename(paths[index]),
                     });
                     refs.push({

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

@@ -0,0 +1,89 @@
+/**
+ * `video_generate` tool: generate videos through the grok subscription's
+ * Imagine video endpoint and save them as MP4 files under the harness home.
+ * The xAI API is asynchronous: POST `/v1/videos/generations` returns a
+ * `request_id`, GET `/v1/videos/{request_id}` is polled until the status
+ * leaves `pending`, and the completed response carries a temporary MP4 URL
+ * that is downloaded promptly (the URL expires). The canonical result is the
+ * saved file path; videos have no attachment surface, so the result stays
+ * text-only (unlike image_generate).
+ */
+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 generation request is posted to. */
+export declare const VIDEO_GENERATE_URL = "https://api.x.ai/v1/videos/generations";
+/** The video model the grok subscription endpoint serves. */
+export declare const VIDEO_GENERATE_MODEL = "grok-imagine-video-1.5";
+/** Polling endpoint for one generation request. */
+export declare function videoStatusUrl(requestId: string): string;
+/** Default delay between two status polls. */
+export declare const DEFAULT_POLL_INTERVAL_MS = 3000;
+/** Default overall deadline for one generation (submit → done). */
+export declare const DEFAULT_MAX_WAIT_MS: number;
+/** Dependencies of the `video_generate` tool. */
+export interface VideoGenerateToolOptions {
+    /** Grok session source; a missing session throws the log-in hint. */
+    tokens: TokenManager<GrokSession>;
+    /** Fetch implementation (injectable for tests). */
+    fetchFn?: FetchFn;
+    /** Directory override for saved videos (defaults under the harness home). */
+    videosDir?: string;
+    /** Delay between status polls (injectable for tests). */
+    pollIntervalMs?: number;
+    /** Overall deadline from submit to completion. */
+    maxWaitMs?: number;
+}
+/** The wire request body for one generation call. */
+export interface VideoGenerateRequestBody {
+    prompt: string;
+    model: string;
+    duration?: number;
+    aspect_ratio?: string;
+    resolution?: string;
+    image?: {
+        url: string;
+    };
+}
+/**
+ * Assemble the request body from tool arguments (hand-checks the non-empty
+ * prompt and the duration range the schema DSL cannot express).
+ */
+export declare function buildVideoGenerateBody(args: {
+    prompt: string;
+    duration?: number;
+    aspect_ratio?: '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '3:2' | '2:3';
+    resolution?: '480p' | '720p' | '1080p';
+    image_url?: string;
+}): VideoGenerateRequestBody;
+/**
+ * Extract the request id from the submit response. Throws when the payload
+ * carries none.
+ */
+export declare function parseVideoStartResponse(payload: unknown): string;
+/** One decoded poll response. */
+export type VideoStatus = {
+    status: 'pending';
+} | {
+    status: 'done';
+    url: string;
+    duration?: number;
+} | {
+    status: 'failed' | 'expired';
+    detail?: string;
+};
+/**
+ * Decode one poll response. A `done` payload without a video URL and an
+ * unrecognized status both throw (the poll loop cannot make progress on
+ * either).
+ */
+export declare function parseVideoStatusResponse(payload: unknown): VideoStatus;
+/** Directory the downloaded MP4 files are written to. */
+export declare function videosDirectory(): string;
+/**
+ * Build the `video_generate` tool definition.
+ * @param options - grok session source, fetch implementation, and video directory.
+ * @returns the tool to register on `ctx.tools`.
+ */
+export declare function createVideoGenerateTool(options: VideoGenerateToolOptions): ToolDefinition;