dsh-plugin-subscriptions 0.3.0 → 0.4.0

package/lib/providers/grok.js

@@ -405,10 +405,15 @@ export async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
 /** Grok wire adapter: one instance serves the `grok` provider route. */
 export class GrokAdapter extends LlmAdapter {
     options;
-    catalog = new ModelCatalogCache();
+    catalog;
     constructor(options) {
         super();
         this.options = options;
+        this.catalog = new ModelCatalogCache(options.catalogStore);
+    }
+    /** Discovery fetcher: resolves the session through the refresh-aware path. */
+    async fetchCatalog() {
+        return fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn);
     }
     providerInfo(provider) {
         return { id: provider, name: 'Grok (Subscription)' };
@@ -432,7 +437,7 @@ export class GrokAdapter extends LlmAdapter {
             // The fetcher runs only on a cache miss, and resolves the session
             // through the refresh-aware path so an expired access token renews here
             // instead of failing discovery into the static fallback.
-            const discovered = await this.catalog.get(async () => fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn));
+            const discovered = await this.catalog.get(() => this.fetchCatalog());
             return discovered.map(model => ({
                 provider,
                 id: model.id,
@@ -453,12 +458,24 @@ export class GrokAdapter extends LlmAdapter {
             return this.staticModels(provider);
         }
     }
-    resolveModel(provider, model) {
-        const discovered = this.options.discovery
-            ? this.catalog.cached()?.find(entry => entry.id === model)
-            : undefined;
+    /**
+     * The discovered entry for one model. Resolved through the cache's
+     * stale-while-revalidate path: capability metadata must stay stable across
+     * a long conversation — a session that selected a reasoning effort calls
+     * this on EVERY step, and forgetting the efforts just because the TTL
+     * lapsed mid-turn would fail the call with UNSUPPORTED_REASONING_EFFORT
+     * before provider I/O.
+     */
+    async discovered(model) {
+        if (!this.options.discovery)
+            return undefined;
+        const models = await this.catalog.resolve(() => this.fetchCatalog());
+        return models?.find(entry => entry.id === model);
+    }
+    async resolveModel(provider, model) {
+        const discovered = await this.discovered(model);
         const configured = this.options.models.find(entry => entry.id === model);
-        return Promise.resolve({
+        return {
             provider,
             id: model,
             name: discovered?.name ?? configured?.name ?? model,
@@ -470,7 +487,7 @@ export class GrokAdapter extends LlmAdapter {
             // cover expose none, so the harness rejects explicit efforts before
             // provider I/O instead of the API 400ing.
             ...discovered?.reasoning === undefined ? {} : { reasoning: discovered.reasoning },
-        });
+        };
     }
     async *stream(options) {
         const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);

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;

package/lib/tools/video-generate.js

@@ -0,0 +1,255 @@
+/**
+ * `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 { mkdir, writeFile } from 'node:fs/promises';
+import { basename, 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 VIDEO_GENERATE_URL = 'https://api.x.ai/v1/videos/generations';
+/** The video model the grok subscription endpoint serves. */
+export const VIDEO_GENERATE_MODEL = 'grok-imagine-video-1.5';
+/** Polling endpoint for one generation request. */
+export function videoStatusUrl(requestId) {
+    return `https://api.x.ai/v1/videos/${encodeURIComponent(requestId)}`;
+}
+/** Default delay between two status polls. */
+export const DEFAULT_POLL_INTERVAL_MS = 3_000;
+/** Default overall deadline for one generation (submit → done). */
+export const DEFAULT_MAX_WAIT_MS = 10 * 60_000;
+/** xAI's supported clip length range in seconds. */
+const DURATION_RANGE = { min: 1, max: 15 };
+/**
+ * Assemble the request body from tool arguments (hand-checks the non-empty
+ * prompt and the duration range the schema DSL cannot express).
+ */
+export function buildVideoGenerateBody(args) {
+    const prompt = args.prompt.trim();
+    if (prompt.length === 0)
+        throw new Error('video_generate: prompt must be a non-empty string');
+    if (args.duration !== undefined
+        && (!Number.isInteger(args.duration)
+            || args.duration < DURATION_RANGE.min
+            || args.duration > DURATION_RANGE.max)) {
+        throw new Error(`video_generate: duration must be an integer between ${String(DURATION_RANGE.min)} and ${String(DURATION_RANGE.max)} seconds`);
+    }
+    const imageUrl = args.image_url?.trim();
+    return {
+        prompt,
+        model: VIDEO_GENERATE_MODEL,
+        ...args.duration === undefined ? {} : { duration: args.duration },
+        ...args.aspect_ratio === undefined ? {} : { aspect_ratio: args.aspect_ratio },
+        ...args.resolution === undefined ? {} : { resolution: args.resolution },
+        ...imageUrl === undefined || imageUrl.length === 0 ? {} : { image: { url: imageUrl } },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Extract the request id from the submit response. Throws when the payload
+ * carries none.
+ */
+export function parseVideoStartResponse(payload) {
+    const body = isRecord(payload) ? payload : {};
+    if (typeof body.request_id !== 'string' || body.request_id.length === 0) {
+        throw new Error('video_generate: the response carried no request_id');
+    }
+    return body.request_id;
+}
+/**
+ * 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 function parseVideoStatusResponse(payload) {
+    const body = isRecord(payload) ? payload : {};
+    switch (body.status) {
+        case 'pending':
+            return { status: 'pending' };
+        case 'done': {
+            const video = isRecord(body.video) ? body.video : {};
+            if (typeof video.url !== 'string' || video.url.length === 0) {
+                throw new Error('video_generate: the completed response carried no video URL');
+            }
+            return {
+                status: 'done',
+                url: video.url,
+                ...typeof video.duration === 'number' ? { duration: video.duration } : {},
+            };
+        }
+        case 'failed':
+        case 'expired': {
+            const error = isRecord(body.error) ? body.error : {};
+            const detail = typeof error.message === 'string' && error.message.length > 0
+                ? error.message
+                : typeof body.error === 'string' && body.error.length > 0 ? body.error : undefined;
+            return { status: body.status, ...detail === undefined ? {} : { detail } };
+        }
+        default:
+            throw new Error(`video_generate: unexpected status ${JSON.stringify(body.status)}`);
+    }
+}
+/** Directory the downloaded MP4 files are written to. */
+export function videosDirectory() {
+    return dshHomePath('plugins', 'subscriptions', 'videos');
+}
+/** Timestamped, collision-safe file name for one generated video. */
+function videoFileName() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `video-${stamp}-${Math.random().toString(36).slice(2, 8)}.mp4`;
+}
+/** Bound a call-card title's prompt. */
+function truncate(text, max = 60) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/** Abort-aware sleep between two polls. */
+function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason instanceof Error ? signal.reason : new Error('video_generate: aborted'));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * 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 function createVideoGenerateTool(options) {
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    return defineTool({
+        name: 'video_generate',
+        description: `Generate a short video (1-15 seconds) with the grok subscription (${VIDEO_GENERATE_MODEL}) `
+            + 'and save it as an MP4 file. Generation is asynchronous and may take a minute or more; '
+            + 'the tool waits for completion and returns the saved file path. '
+            + 'Optionally animate a still image by passing image_url (image-to-video).',
+        parameters: {
+            prompt: { type: 'string', required: true, description: 'What the video should show.' },
+            duration: {
+                type: 'integer',
+                description: 'Clip length in seconds (1-15); omit for the provider default.',
+            },
+            aspect_ratio: {
+                type: 'string',
+                enum: ['16:9', '9:16', '1:1', '4:3', '3:4', '3:2', '2:3'],
+                description: 'Output aspect ratio; omit for the provider default (16:9).',
+            },
+            resolution: {
+                type: 'string',
+                enum: ['480p', '720p', '1080p'],
+                description: 'Output resolution; omit for the provider default (480p). Higher is slower.',
+            },
+            image_url: {
+                type: 'string',
+                description: 'Optional public URL or base64 data URL of a JPEG/PNG/WebP image to animate '
+                    + '(image-to-video); the image becomes the starting frame.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', required: true },
+                    url: { type: 'string', required: true },
+                    duration: { type: 'number' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Saved video to ${value.path}`
+                        + (value.duration === undefined ? '' : ` (${String(value.duration)}s)`)
+                        + `\nTemporary provider URL (expires soon): ${value.url}`,
+                }],
+            // The client toolview fetches the bytes by bare file name through the
+            // `/subscriptions-auth` `video` endpoint; meta hands it that name.
+            presentationMeta: (_args, value) => ({
+                fileName: basename(value.path),
+                ...value.duration === undefined ? {} : { duration: value.duration },
+            }),
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `video_generate: ${truncate(args.prompt)}`,
+        }),
+        async execute(args, exec) {
+            const body = buildVideoGenerateBody(args);
+            const session = await options.tokens.session();
+            const fetchFn = options.fetchFn ?? fetch;
+            const headers = {
+                'authorization': `Bearer ${session.accessToken}`,
+                'accept': 'application/json',
+            };
+            const submit = await fetchFn(VIDEO_GENERATE_URL, {
+                method: 'POST',
+                headers: { ...headers, 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: exec.signal,
+            });
+            if (!submit.ok)
+                throw await httpLlmError(submit, 'video_generate');
+            const requestId = parseVideoStartResponse(await submit.json());
+            const deadline = Date.now() + maxWaitMs;
+            let done;
+            for (;;) {
+                await sleep(pollIntervalMs, exec.signal);
+                const poll = await fetchFn(videoStatusUrl(requestId), {
+                    method: 'GET',
+                    headers,
+                    signal: exec.signal,
+                });
+                if (!poll.ok)
+                    throw await httpLlmError(poll, 'video_generate');
+                const status = parseVideoStatusResponse(await poll.json());
+                if (status.status === 'done') {
+                    done = status;
+                    break;
+                }
+                if (status.status === 'failed' || status.status === 'expired') {
+                    throw new Error(`video_generate: generation ${status.status} (request ${requestId})`
+                        + (status.detail === undefined ? '' : `: ${status.detail}`));
+                }
+                if (Date.now() >= deadline) {
+                    throw new Error(`video_generate: timed out after ${String(maxWaitMs)}ms waiting for request ${requestId}`);
+                }
+            }
+            // The MP4 lives on a separate signed host: no auth header on purpose.
+            const download = await fetchFn(done.url, { method: 'GET', signal: exec.signal });
+            if (!download.ok)
+                throw await httpLlmError(download, 'video_generate download');
+            const data = Buffer.from(await download.arrayBuffer());
+            const directory = options.videosDir ?? videosDirectory();
+            await mkdir(directory, { recursive: true });
+            const path = join(directory, videoFileName());
+            await writeFile(path, data);
+            const value = {
+                path,
+                url: done.url,
+                ...done.duration === undefined ? {} : { duration: done.duration },
+            };
+            return value;
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-subscriptions",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Use ChatGPT (Codex), Claude, and Grok (X Premium) subscriptions as DeepSeek Harness LLM providers, with OAuth login from the web Settings page",
   "license": "MIT",
   "repository": {
@@ -48,6 +48,12 @@
       ]
     }
   },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "test": "tsc -p tsconfig.test.json && node --test lib-test/test/",
+    "prepare": "tsdown -c tsdown.prepare.config.ts",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-attachment": "^0.1.0-rc.5",
@@ -75,9 +81,5 @@
     "react": "^18.2.0",
     "tsdown": "^0.15.0",
     "typescript": "^5.8.0"
-  },
-  "scripts": {
-    "build": "tsc && tsdown",
-    "test": "tsc -p tsconfig.test.json && node --test lib-test/test/"
   }
-}
+}