dsh-plugin-subscription-usage 0.0.0-stage → 0.1.0

package/lib/tools/video-generate.js

@@ -0,0 +1,257 @@
+/**
+ * `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 } from '../providers/common.js';
+import { AccountTokenManager } from '../providers/accounts.js';
+import { proxiedFetch } from '../http.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 ?? proxiedFetch;
+            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/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 { AccountTokenManager } from '../providers/accounts.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: AccountTokenManager<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 {};

package/lib/tools/x-search.js

@@ -0,0 +1,197 @@
+/**
+ * `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 { defineTool } from '@deepseek-ai/dsh-tools';
+import { httpLlmError } from '../providers/common.js';
+import { AccountTokenManager } from '../providers/accounts.js';
+import { proxiedFetch } from '../http.js';
+/** Endpoint the search request is posted to. */
+export const X_SEARCH_URL = 'https://api.x.ai/v1/responses';
+/** Grok model the search runs on (a catalog model of the grok provider). */
+export const X_SEARCH_MODEL = 'grok-4';
+/** xAI caps each handle filter list at ten entries. */
+const MAX_HANDLES = 10;
+/**
+ * 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 function buildXSearchRequest(args) {
+    const query = args.query.trim();
+    if (query.length === 0)
+        throw new Error('x_search: query must be a non-empty string');
+    const allowed = normalizeHandles(args.allowed_x_handles, 'allowed_x_handles');
+    const excluded = normalizeHandles(args.excluded_x_handles, 'excluded_x_handles');
+    if (allowed.length > 0 && excluded.length > 0) {
+        throw new Error('x_search: allowed_x_handles and excluded_x_handles cannot be used together');
+    }
+    const tool = { type: 'x_search' };
+    if (allowed.length > 0)
+        tool.allowed_x_handles = allowed;
+    if (excluded.length > 0)
+        tool.excluded_x_handles = excluded;
+    if (args.from_date !== undefined && args.from_date.trim().length > 0)
+        tool.from_date = args.from_date.trim();
+    if (args.to_date !== undefined && args.to_date.trim().length > 0)
+        tool.to_date = args.to_date.trim();
+    if (args.enable_image_understanding === true)
+        tool.enable_image_understanding = true;
+    if (args.enable_video_understanding === true)
+        tool.enable_video_understanding = true;
+    return { query, tool };
+}
+/** Strip `@` prefixes, drop blanks, and enforce the provider's handle cap. */
+function normalizeHandles(value, field) {
+    if (value === undefined)
+        return [];
+    const handles = value.map(handle => handle.trim().replace(/^@+/, '')).filter(handle => handle.length > 0);
+    if (handles.length > MAX_HANDLES)
+        throw new Error(`x_search: ${field} supports at most ${MAX_HANDLES} handles`);
+    return handles;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 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 function parseXSearchResponse(payload) {
+    const body = isRecord(payload) ? payload : {};
+    let answer = typeof body.output_text === 'string' ? body.output_text.trim() : '';
+    const citations = [];
+    const push = (url) => {
+        if (typeof url === 'string' && url.length > 0 && !citations.includes(url))
+            citations.push(url);
+    };
+    if (Array.isArray(body.citations)) {
+        for (const citation of body.citations)
+            push(citation);
+    }
+    const parts = [];
+    if (Array.isArray(body.output)) {
+        for (const item of body.output) {
+            if (!isRecord(item) || item.type !== 'message' || !Array.isArray(item.content))
+                continue;
+            for (const part of item.content) {
+                if (!isRecord(part))
+                    continue;
+                if ((part.type === 'output_text' || part.type === 'text')
+                    && typeof part.text === 'string' && part.text.trim().length > 0) {
+                    parts.push(part.text.trim());
+                }
+                if (Array.isArray(part.annotations)) {
+                    for (const annotation of part.annotations) {
+                        if (isRecord(annotation) && annotation.type === 'url_citation')
+                            push(annotation.url);
+                    }
+                }
+            }
+        }
+    }
+    if (answer.length === 0)
+        answer = parts.join('\n\n');
+    return { answer, citations };
+}
+/** Bound a call-card title's query. */
+function truncate(text, max = 60) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/**
+ * Build the `x_search` tool definition.
+ * @param options - grok session source and fetch implementation.
+ * @returns the tool to register on `ctx.tools`.
+ */
+export function createXSearchTool(options) {
+    return defineTool({
+        name: 'x_search',
+        description: "Search X (Twitter) posts, profiles, and threads using the grok subscription's hosted xAI x_search. "
+            + 'Use this for current discussion, reactions, or claims on X rather than general web pages.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'What to look up on X.' },
+            allowed_x_handles: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'X handles to include exclusively (max 10).',
+            },
+            excluded_x_handles: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'X handles to exclude (max 10).',
+            },
+            from_date: { type: 'string', description: 'Optional start date in YYYY-MM-DD format.' },
+            to_date: { type: 'string', description: 'Optional end date in YYYY-MM-DD format.' },
+            enable_image_understanding: {
+                type: 'boolean',
+                description: 'Whether xAI should analyze images attached to matching posts.',
+            },
+            enable_video_understanding: {
+                type: 'boolean',
+                description: 'Whether xAI should analyze videos attached to matching posts.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    answer: { type: 'string', required: true },
+                    citations: { type: 'array', items: { type: 'string' }, required: true },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: value.citations.length > 0
+                        ? `${value.answer}\n\nSources:\n${value.citations.map(citation => `- ${citation}`).join('\n')}`
+                        : value.answer,
+                }],
+            presentationMeta: (_args, value) => ({ answer: value.answer, citations: value.citations }),
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: `x_search: ${truncate(args.query)}`,
+            kind: 'search',
+        }),
+        presentResult: (_args, result) => {
+            if (result.isError || !isRecord(result.meta))
+                return undefined;
+            const citations = Array.isArray(result.meta.citations) ? result.meta.citations : [];
+            return {
+                card: 'web',
+                kind: 'search',
+                sources: citations.filter((citation) => typeof citation === 'string')
+                    .map(url => ({ url })),
+                ...typeof result.meta.answer === 'string' && result.meta.answer.length > 0
+                    ? { answer: result.meta.answer }
+                    : {},
+                truncated: false,
+            };
+        },
+        async execute(args, exec) {
+            const request = buildXSearchRequest(args);
+            const session = await options.tokens.session();
+            const response = await (options.fetchFn ?? proxiedFetch)(X_SEARCH_URL, {
+                method: 'POST',
+                headers: {
+                    'authorization': `Bearer ${session.accessToken}`,
+                    'content-type': 'application/json',
+                    'accept': 'application/json',
+                },
+                body: JSON.stringify({
+                    model: X_SEARCH_MODEL,
+                    input: [{ role: 'user', content: request.query }],
+                    tools: [request.tool],
+                    store: false,
+                }),
+                signal: exec.signal,
+            });
+            if (!response.ok)
+                throw await httpLlmError(response, 'x_search');
+            return parseXSearchResponse(await response.json());
+        },
+    });
+}