dsh-plugin-subscriptions 0.3.1 → 0.4.0

package/lib/index.js

@@ -2,9 +2,9 @@ import z from "@deepseek-ai/schemastery";
 import { CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, ReasoningEffortId, attributionHeaders, createUserMessage, errorChain, isContextWindowExceededError, isQuotaExceededError } from "@deepseek-ai/dsh-llm";
 import { createServer } from "node:http";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { AttachmentId } from "@deepseek-ai/dsh-attachment";
 import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
+import { AttachmentId } from "@deepseek-ai/dsh-attachment";
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 
@@ -371,6 +371,8 @@ const IMAGE_MEDIA_TYPES = [
 	"image/webp",
 	"image/gif"
 ];
+/** Bare MP4 file names the `video` endpoint accepts (no path separators). */
+const VIDEO_NAME_PATTERN = /^[\w.-]+\.mp4$/;
 /** Payload carried no usable provider id — an RPC client bug, not a server failure. */
 var BadRequest = class extends Error {};
 function ok(value) {
@@ -436,6 +438,17 @@ function readImageRef(payload) {
 		...name$1 === void 0 ? {} : { name: name$1 }
 	};
 }
+/**
+* Validate the `video` endpoint's payload into a bare file name. Rejecting
+* anything with a path separator (the pattern allows none) pins every read
+* inside the plugin's videos directory.
+*/
+function readVideoName(payload) {
+	if (typeof payload !== "object" || payload === null) throw new BadRequest("payload must be an object");
+	const name$1 = payload.name;
+	if (typeof name$1 !== "string" || !VIDEO_NAME_PATTERN.test(name$1)) throw new BadRequest("payload.name must be a bare .mp4 file name");
+	return name$1;
+}
 async function dispatch(controller, endpoint, payload, signal) {
 	switch (endpoint) {
 		case "status": {
@@ -456,6 +469,7 @@ async function dispatch(controller, endpoint, payload, signal) {
 			return ok({ ok: true });
 		case "usage": return ok(await controller.usage(readProvider(payload), signal));
 		case "image": return ok(await controller.readImage(readImageRef(payload), signal));
+		case "video": return ok(await controller.readVideo(readVideoName(payload), signal));
 		default: throw new BadRequest(`unknown /subscriptions-auth endpoint "${endpoint}"`);
 	}
 }
@@ -1510,8 +1524,28 @@ function isCodexPermanentRefreshError(error) {
 	return error instanceof OAuthEndpointError && error.oauthCode !== void 0 && PERMANENT_REFRESH_CODES.has(error.oauthCode);
 }
 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 = 300 * 60;
+const WEEKLY_WINDOW_SECONDS = 10080 * 60;
+/** Whether a reported duration approximately matches the expected window length. */
+function matchesWindow(seconds, expected) {
+	return seconds >= expected * .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 void 0;
 	const window = value;
 	if (typeof window.used_percent !== "number" || !Number.isFinite(window.used_percent)) return void 0;
@@ -1519,7 +1553,7 @@ function codexUsageWindow(value, kind) {
 	if (typeof window.reset_at === "number" && window.reset_at > 0) resetsAt = window.reset_at * 1e3;
 	else if (typeof window.reset_after_seconds === "number" && window.reset_after_seconds > 0) resetsAt = Date.now() + window.reset_after_seconds * 1e3;
 	return {
-		kind,
+		kind: codexWindowKind(window, fallbackKind),
 		usedPercent: window.used_percent,
 		...resetsAt === void 0 ? {} : { resetsAt }
 	};
@@ -1527,8 +1561,11 @@ function codexUsageWindow(value, kind) {
 /**
 * 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.
@@ -2893,7 +2930,7 @@ function normalizeHandles(value, field) {
 	if (handles.length > MAX_HANDLES) throw new Error(`x_search: ${field} supports at most ${MAX_HANDLES} handles`);
 	return handles;
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
@@ -2902,7 +2939,7 @@ function isRecord(value) {
 * top-level `citations` and inline `url_citation` annotations for sources.
 */
 function parseXSearchResponse(payload) {
-	const body = isRecord(payload) ? payload : {};
+	const body = isRecord$1(payload) ? payload : {};
 	let answer = typeof body.output_text === "string" ? body.output_text.trim() : "";
 	const citations = [];
 	const push = (url) => {
@@ -2911,12 +2948,12 @@ function parseXSearchResponse(payload) {
 	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;
+		if (!isRecord$1(item) || item.type !== "message" || !Array.isArray(item.content)) continue;
 		for (const part of item.content) {
-			if (!isRecord(part)) continue;
+			if (!isRecord$1(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);
+				for (const annotation of part.annotations) if (isRecord$1(annotation) && annotation.type === "url_citation") push(annotation.url);
 			}
 		}
 	}
@@ -2927,7 +2964,7 @@ function parseXSearchResponse(payload) {
 	};
 }
 /** Bound a call-card title's query. */
-function truncate$1(text, max = 60) {
+function truncate$2(text, max = 60) {
 	return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
 }
 /**
@@ -2999,11 +3036,11 @@ function createXSearchTool(options) {
 		},
 		presentCall: (args) => ({
 			card: "generic",
-			title: `x_search: ${truncate$1(args.query)}`,
+			title: `x_search: ${truncate$2(args.query)}`,
 			kind: "search"
 		}),
 		presentResult: (_args, result) => {
-			if (result.isError || !isRecord(result.meta)) return void 0;
+			if (result.isError || !isRecord$1(result.meta)) return void 0;
 			return {
 				card: "web",
 				kind: "search",
@@ -3088,7 +3125,7 @@ function imageFileName(index) {
 	return `image-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${Math.random().toString(36).slice(2, 8)}-${index}.png`;
 }
 /** Bound a call-card title's prompt. */
-function truncate(text, max = 60) {
+function truncate$1(text, max = 60) {
 	return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
 }
 /**
@@ -3224,7 +3261,7 @@ function createImageGenerateTool(options) {
 		},
 		presentCall: (args) => ({
 			card: "generic",
-			title: `image_generate: ${truncate(args.prompt)}`
+			title: `image_generate: ${truncate$1(args.prompt)}`
 		}),
 		presentResult: (_args, result) => ({
 			card: "generic",
@@ -3291,6 +3328,249 @@ function createImageGenerateTool(options) {
 	});
 }
 
+//#endregion
+//#region src/tools/video-generate.ts
+/** Endpoint the generation request is posted to. */
+const VIDEO_GENERATE_URL = "https://api.x.ai/v1/videos/generations";
+/** The video model the grok subscription endpoint serves. */
+const VIDEO_GENERATE_MODEL = "grok-imagine-video-1.5";
+/** Polling endpoint for one generation request. */
+function videoStatusUrl(requestId) {
+	return `https://api.x.ai/v1/videos/${encodeURIComponent(requestId)}`;
+}
+/** Default delay between two status polls. */
+const DEFAULT_POLL_INTERVAL_MS = 3e3;
+/** Default overall deadline for one generation (submit → done). */
+const DEFAULT_MAX_WAIT_MS = 10 * 6e4;
+/** 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).
+*/
+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 !== void 0 && (!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 === void 0 ? {} : { duration: args.duration },
+		...args.aspect_ratio === void 0 ? {} : { aspect_ratio: args.aspect_ratio },
+		...args.resolution === void 0 ? {} : { resolution: args.resolution },
+		...imageUrl === void 0 || 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.
+*/
+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).
+*/
+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 : void 0;
+			return {
+				status: body.status,
+				...detail === void 0 ? {} : { detail }
+			};
+		}
+		default: throw new Error(`video_generate: unexpected status ${JSON.stringify(body.status)}`);
+	}
+}
+/** Directory the downloaded MP4 files are written to. */
+function videosDirectory() {
+	return dshHomePath("plugins", "subscriptions", "videos");
+}
+/** Timestamped, collision-safe file name for one generated video. */
+function videoFileName() {
+	return `video-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${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 : /* @__PURE__ */ 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`.
+*/
+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 === void 0 ? "" : ` (${String(value.duration)}s)`) + `\nTemporary provider URL (expires soon): ${value.url}`
+			}],
+			presentationMeta: (_args, value) => ({
+				fileName: basename(value.path),
+				...value.duration === void 0 ? {} : { 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 === void 0 ? "" : `: ${status.detail}`));
+				if (Date.now() >= deadline) throw new Error(`video_generate: timed out after ${String(maxWaitMs)}ms waiting for request ${requestId}`);
+			}
+			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);
+			return {
+				path,
+				url: done.url,
+				...done.duration === void 0 ? {} : { duration: done.duration }
+			};
+		}
+	});
+}
+
 //#endregion
 //#region src/index.ts
 const name = "dsh-plugin-subscriptions";
@@ -3420,6 +3700,12 @@ var SubscriptionsAuthController = class {
 			dataBase64: Buffer.from(stored.data).toString("base64")
 		};
 	}
+	async readVideo(name$1, signal) {
+		return {
+			mediaType: "video/mp4",
+			dataBase64: (await readFile(join(videosDirectory(), name$1), { signal })).toString("base64")
+		};
+	}
 	async status(provider) {
 		const session = await getSession(provider);
 		const account = accountOf(provider, session);
@@ -3577,7 +3863,10 @@ function apply(ctx, config) {
 	}
 	registerAuthRpc(ctx, new SubscriptionsAuthController(flows, authChanged, resolveAttachments, usageFetchers));
 	ctx.inject(["tools"], (toolsCtx) => {
-		if (grokTokens !== void 0) toolsCtx.tools.register(createXSearchTool({ tokens: grokTokens }));
+		if (grokTokens !== void 0) {
+			toolsCtx.tools.register(createXSearchTool({ tokens: grokTokens }));
+			toolsCtx.tools.register(createVideoGenerateTool({ tokens: grokTokens }));
+		}
 		if (codexTokens !== void 0) toolsCtx.tools.register(createImageGenerateTool({
 			tokens: codexTokens,
 			resolveAttachments,

package/lib/providers/codex.d.ts

@@ -57,8 +57,11 @@ export declare const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usa
 /**
  * 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/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/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;