@eddyskywalker/dsh-chatgpt-subscription 0.29.0 → 0.31.0

package/lib/types/host/minimax-code/video-tool.d.ts

@@ -0,0 +1,757 @@
+/**
+ * The MiniMax Code video tools: understanding and generation.
+ *
+ * Both ride the Matrix media gateway (./matrix-client.ts), which sits beside the
+ * Messages route on the same agent host. Neither of them sends video to the
+ * model as a content block: the Anthropic Messages wire this line speaks has no
+ * video part (./modalities.ts records the same conclusion for the prompt path),
+ * so understanding is a SERVER-SIDE call that answers with text, and generation
+ * is a two-step async task that produces a file.
+ *
+ * THE ROUTE GATE. Both tools refuse unless the session is routed to
+ * `minimax-code`. The reason is not a modality declaration - generation needs
+ * none - but the credential: the bearer both tools present is this line's
+ * subscription token read from this line's pool. A session served by another
+ * provider has no such credential, so the call would 401 in a way the user
+ * cannot act on. Refusing here, with the model to switch to, is the same
+ * contract `kimi_attach_video` states for its own route.
+ *
+ * @module dsh-chatgpt-subscription/minimax-code/video-tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const MINIMAX_UNDERSTAND_VIDEO_TOOL_NAME = "minimax_understand_video";
+export declare const MINIMAX_GENERATE_VIDEO_TOOL_NAME = "minimax_generate_video";
+/** Default prompt used when the caller asks no specific question. */
+export declare const DEFAULT_UNDERSTAND_PROMPT = "\u63CF\u8FF0\u8FD9\u4E2A\u89C6\u9891\u7684\u5185\u5BB9";
+/**
+ * Largest local file the INLINE (base64) understanding path will send.
+ *
+ * A MEASURED CONSTRAINT, not a taste. `videos_understand` reads a local clip
+ * only through `video_info[].data`, which is base64 (docs/
+ * minimax-video-generation-probe.md §3.2, U3: the only one of the three source
+ * forms that answered `results[0].success: true`). Base64 grows the bytes by
+ * 4/3 on the wire, and this line's request body is capped at
+ * {@link maxMessageBodyBytes} (./types.ts, 64 MB by default), so a 40 MB clip
+ * encodes to ~53 MB and still fits. A larger file would leave the caller with
+ * an opaque "body too large" from the transport instead of an answer, which is
+ * why it is refused here, before the bytes become a request.
+ */
+export declare const MAX_INLINE_VIDEO_BYTES: number;
+/**
+ * The effective inline ceiling for one deployment.
+ *
+ * Two limits apply at once: the fixed {@link MAX_INLINE_VIDEO_BYTES}, and the
+ * body budget `maxMessageBodyBytes()` — which a deployment can pin lower with
+ * `DSH_MINIMAX_CODE_MAX_BODY_BYTES`. The base64 form costs 4 bytes per 3 bytes
+ * of video, so the body budget converts to 3/4 of itself; a further 1/8 is
+ * reserved for the JSON envelope around the payload.
+ *
+ * @param bodyLimit - the request-body ceiling; defaults to this line's own.
+ * @returns the largest raw video size that can be sent inline.
+ */
+export declare function inlineVideoByteBudget(bodyLimit?: number): number;
+/**
+ * Largest local file the UPLOAD (presigned PUT) understanding path will send.
+ *
+ * 200 MiB, which is deliberately the SAME number as
+ * {@link MAX_GENERATED_VIDEO_BYTES} — the ceiling the download side puts on a
+ * generated clip. The two directions are held to one value on purpose: a file
+ * this route can push into the bucket is also a file it can pull back out, so
+ * neither limit can leave the other holding a video that moves one way and not
+ * the other.
+ *
+ * Upstream's own ceiling is `MATRIX_MAX_UPLOAD_BYTES` = 500 MiB
+ * (packages/agent-tools/src/desktop/matrix-media-client.ts:14), so the service
+ * is not what binds here — this process' memory is.
+ *
+ * WHY AN UPLOAD CAP AT ALL, given that these bytes never enter the request
+ * body: they still pass THROUGH this process. {@link uploadLocalVideo} is
+ * handed a `Uint8Array` of the entire file and `get_upload_url` is asked for
+ * a target sized from it, so with no cap a 2 GB clip would be read into RAM and
+ * PUT as one object. That is why the check lives in {@link readLocalVideo},
+ * against `stats.size`, before a single byte is read — see the note there.
+ */
+export declare const MAX_UPLOAD_VIDEO_BYTES: number;
+/**
+ * How a local file reaches the service.
+ *
+ * `inline` is the default because it needs no upload step at all. `upload`
+ * exists because base64 stops scaling at {@link MAX_INLINE_VIDEO_BYTES}; both
+ * its field names (§5) and its end-to-end read-back are measured — see
+ * {@link uploadLocalVideo} for what that does and does not cover.
+ */
+export declare const MINIMAX_VIDEO_TRANSPORTS: readonly ["inline", "upload"];
+export type MinimaxVideoTransport = (typeof MINIMAX_VIDEO_TRANSPORTS)[number];
+/**
+ * Models the generation tool accepts, in the order the picker shows them.
+ *
+ * THREE, AND ALL THREE ARE MEASURED. `MiniMax-H3-Max` was missing from this
+ * list; it is not an inference, because the service named it in its own duration
+ * rule (docs/minimax-video-free-checks.md section 2.1, verbatim):
+ *
+ * > use 4-15 seconds for MiniMax-H3, 5-15 seconds for MiniMax-H3-Max, or 6/10
+ * > seconds for Hailuo 2.3
+ *
+ * That sentence is also what proves `MiniMax-Hailuo-2.3` is recognised: asked
+ * for a bad duration, the service answered with a rule about THAT model, so its
+ * id had already passed the model check (section 3).
+ */
+export declare const MINIMAX_VIDEO_MODELS: readonly ["MiniMax-H3", "MiniMax-H3-Max", "MiniMax-Hailuo-2.3"];
+export type MinimaxVideoModel = (typeof MINIMAX_VIDEO_MODELS)[number];
+/** Model used when the caller names none. */
+export declare const DEFAULT_MINIMAX_VIDEO_MODEL: MinimaxVideoModel;
+/**
+ * Every resolution spelling ANY model accepts: a UNION, never a legal set.
+ *
+ * THIS LIST IS NOT ANY MODEL'S LEGAL RESOLUTION SET, AND MUST NOT BE USED AS
+ * ONE. MEASURED, and the measurement contradicts the intuitive reading
+ * (docs/minimax-video-model-rules.md section 5): the three models' sets are
+ * pairwise different and none of them is the union.
+ *
+ * | model                | accepts                     | only this model has |
+ * | -------------------- | --------------------------- | ------------------- |
+ * | `MiniMax-H3`         | `768P`, `2K`               | `2K`                |
+ * | `MiniMax-H3-Max`     | `480P`, `768P`             | `480P`              |
+ * | `MiniMax-Hailuo-2.3` | `768P`, `1080P`            | `1080P`             |
+ *
+ * So every member of this list is illegal for at least one model: `2K` is
+ * refused by H3-Max and by Hailuo, `1080P` by H3 and by H3-Max, `480P` by H3
+ * and by Hailuo. The one place this list is legitimately used is the tool
+ * parameter schema, which can advertise only ONE `enum` for a field whose real
+ * rule is per model; the per-model enforcement that has to follow it lives in
+ * {@link assertVideoResolution}, driven by {@link MINIMAX_VIDEO_MODEL_RULES}.
+ */
+export declare const MINIMAX_VIDEO_RESOLUTION_UNION: readonly ["480P", "768P", "1080P", "2K"];
+export type MinimaxVideoResolution = (typeof MINIMAX_VIDEO_RESOLUTION_UNION)[number];
+/**
+ * Shortest clip ANY model accepts, in seconds.
+ *
+ * The union of the per-model windows, for a caller that needs the widest answer.
+ * It is NOT what enforcement uses: a Hailuo clip of 7 s sits inside 4-15 and must
+ * still be refused, because that model accepts only 6 or 10.
+ */
+export declare const MINIMAX_VIDEO_MIN_DURATION_SECONDS = 4;
+/** Longest clip ANY model accepts, in seconds. See {@link MINIMAX_VIDEO_MIN_DURATION_SECONDS}. */
+export declare const MINIMAX_VIDEO_MAX_DURATION_SECONDS = 15;
+/** How one model bounds `duration`: an inclusive interval, or a closed set. */
+export type MinimaxVideoDurationRule = {
+    readonly kind: 'range';
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'values';
+    readonly values: readonly number[];
+};
+/** One model's accepted `duration` and `resolution`, with where each came from. */
+export interface MinimaxVideoModelRule {
+    readonly model: MinimaxVideoModel;
+    /** The `duration` window. MEASURED for all three (sections 2.1, 2.2 and 3). */
+    readonly duration: MinimaxVideoDurationRule;
+    /** The spellings this model accepts, exactly as they must be sent (case-sensitive). */
+    readonly resolutions: readonly MinimaxVideoResolution[];
+    /**
+     * Where {@link resolutions} came from.
+     *
+     * `measured` - the service's own refusal sentence named the values.
+     * `documented` - upstream documentation states them; no probe confirmed them.
+     * `inferred` - no evidence at all for THIS model; copied from the model the
+     * comment names, and it may be wrong.
+     */
+    readonly resolutionSource: 'measured' | 'documented' | 'inferred';
+}
+/**
+ * The per-model table, and the ONE place the service's real rules live.
+ *
+ * The old shape - one 4-15 window and one resolution list shared by every model
+ * - is wrong in three measured ways: H3-Max starts at 5, Hailuo accepts only 6
+ * or 10, and H3 refuses `1080P` outright.
+ */
+export declare const MINIMAX_VIDEO_MODEL_RULES: readonly MinimaxVideoModelRule[];
+/** The rule for one model id, or undefined when this build has none. */
+export declare function videoModelRule(model: string): MinimaxVideoModelRule | undefined;
+/**
+ * Narrow a caller-supplied model id to one this build knows.
+ *
+ * The parameter schema already lists exactly these three, so a value outside the
+ * set is a caller bypassing its own schema rather than a new upstream model. It
+ * is refused with the legal ids instead of being forwarded, because a model this
+ * build has no rule for cannot have its duration and resolution checked - and the
+ * service bills a submit before it refuses those.
+ *
+ * @param value - the caller's `model` argument, already trimmed.
+ * @returns the matching model id.
+ * @throws HarnessError `MINIMAX_VIDEO_MODEL_INVALID` listing the accepted ids.
+ */
+export declare function assertVideoModel(value: string): MinimaxVideoModel;
+/**
+ * The meta shape the client reads, field for field.
+ *
+ * docs/minimax-video-design-spec.md section 5 fixes these names: the client
+ * narrows `ToolResultNode.meta` to this interface, and a rename here is a
+ * silently blank card there. The `value` a tool returns is deliberately NOT
+ * persisted by the harness, so this is the only channel.
+ */
+export interface MinimaxVideoPresentationMeta {
+    /** Workspace-relative path; the client resolves it against `cwd`. */
+    readonly videoPath: string;
+    readonly mediaType: string;
+    readonly bytes: number;
+    readonly model: string;
+    readonly durationSeconds?: number;
+    /** Upstream task id, for diagnosis and follow-up. */
+    readonly taskId: string;
+}
+/** Base backoff for a transient Matrix failure, matching the adapter's policy. */
+export declare const DEFAULT_RETRY_BACKOFF_MS = 1500;
+/** How often the generation task is polled. */
+export declare const VIDEO_POLL_INTERVAL_MS = 4000;
+/**
+ * Total wall-clock budget for one generation.
+ *
+ * Matches the upstream submit timeout (600 s). Past it the task is very likely
+ * stuck rather than slow, and the user is better served by an answer than by a
+ * request that outlives every other thing in the turn.
+ */
+export declare const VIDEO_GENERATION_BUDGET_MS = 600000;
+/** The slice of the account pool these tools use. */
+export interface MinimaxVideoCredentialSource {
+    getFreshCredential(accountId?: string, fetchFn?: typeof fetch): Promise<{
+        accessToken: string;
+        region: 'cn' | 'global';
+    }>;
+}
+/** A partial Matrix credential, as the tools need it. */
+export interface MinimaxVideoCredential {
+    readonly accessToken: string;
+    readonly region: 'cn' | 'global';
+}
+/** Options for both video tools. */
+export interface MinimaxVideoToolOptions {
+    /** Injected fetch; tests supply a mock so no request ever leaves the process. */
+    readonly fetchFn?: typeof fetch;
+    /** Credential source (the line's account pool). */
+    readonly pool: MinimaxVideoCredentialSource;
+    /** Poll interval, injected so a test does not sleep for real. */
+    readonly pollIntervalMs?: number;
+    /** Generation budget, injected for the same reason. */
+    readonly generationBudgetMs?: number;
+    /**
+     * Base backoff between retries of a transient Matrix failure.
+     *
+     * Injected so a test does not spend the real 1.5 s the adapter's policy uses;
+     * production leaves it at {@link DEFAULT_RETRY_BACKOFF_MS}.
+     */
+    readonly retryBackoffMs?: number;
+    /** Clock, injected so a test can pin the generated file name. */
+    readonly now?: () => number;
+}
+type FetchLike = typeof fetch;
+/**
+ * The provider this session is routed to, and the model on it.
+ *
+ * Read through the same two seams `kimi_attach_video` uses: the live session's
+ * request header first, the agent's own options second. Both are read
+ * defensively because a tool is also executed by tooling that composes no
+ * agent.
+ */
+export declare function routedProvider(exec: {
+    readonly agent?: unknown;
+}): {
+    provider?: string;
+    model?: string;
+};
+/**
+ * Refuse unless this session is served by the MiniMax Code line.
+ *
+ * @param exec - the tool execution.
+ * @param what - the operation being refused, for the message.
+ * @throws HarnessError naming the model to switch to.
+ */
+export declare function assertMinimaxRoute(exec: {
+    readonly agent?: unknown;
+}, what: string): void;
+/**
+ * Prove the `durationSeconds` argument is legal FOR THE MODEL the caller picked.
+ *
+ * The window is not a property of the endpoint, it is a property of the model,
+ * and the service said so itself (docs/minimax-video-free-checks.md section 2.1,
+ * verbatim):
+ *
+ * > use 4-15 seconds for MiniMax-H3, 5-15 seconds for MiniMax-H3-Max, or 6/10
+ * > seconds for Hailuo 2.3
+ *
+ * So a single 4-15 check is wrong in both directions: it lets 7 s through to
+ * Hailuo (which accepts only 6 or 10) and it refuses 4 s on H3-Max (which
+ * accepts 5-15). Both are refusals the service makes AFTER billing the submit,
+ * which is why they are caught here for free instead.
+ *
+ * `0` IS NOT AN OUT-OF-RANGE VALUE. The service treats it as ABSENT - asked for
+ * `duration: 0` it answers "duration is required for MiniMax-H3" (section 2.2) -
+ * so it is reported as a missing argument rather than as a number outside the
+ * window, and the caller is told the model's legal values rather than a range
+ * that would not have applied anyway.
+ *
+ * @param value - the caller's argument, in seconds.
+ * @param model - the model id the submit names, which selects the rule.
+ * @returns the same value, proven legal for that model.
+ * @throws HarnessError naming THAT model's accepted values.
+ */
+export declare function assertVideoDuration(value: unknown, model: MinimaxVideoModel): number;
+/**
+ * Prove the `resolution` argument is one THIS MODEL accepts, spelled exactly.
+ *
+ * The service validates the value against the model, and its sentence names the
+ * model AND its own pair. All three are MEASURED, verbatim
+ * (docs/minimax-video-model-rules.md sections 1 and 2.1, plus
+ * docs/minimax-video-free-checks.md section 2.3 for H3):
+ *
+ * > model resolution for `MiniMax-H3` must be `768P` or `2K`
+ * > model resolution for `MiniMax-H3-Max` must be `480P` or `768P`
+ * > model resolution for `MiniMax-Hailuo-2.3` must be `768P` or `1080P`
+ *
+ * Three measured consequences:
+ *
+ * 1. `1080P` is a real resolution in general and ILLEGAL for H3, so the check
+ *    cannot be "is it in the union" - it has to be "is it in THIS model's set".
+ * 2. The sets are PAIRWISE DIFFERENT and none of them is the union: `2K` is
+ *    H3's alone, `480P` is H3-Max's alone, `1080P` is Hailuo's alone. Nothing
+ *    in this function may fall back to {@link MINIMAX_VIDEO_RESOLUTION_UNION}
+ *    for a model that has a row.
+ * 3. The match is CASE-SENSITIVE. `720p` and `4K` came back with the identical
+ *    sentence, so a lowercase spelling is refused exactly like an invented one.
+ *    The value is trimmed but NOT case-folded, and `'768p'` must stay refused.
+ *
+ * @param value - the caller's argument.
+ * @param model - the model id the submit names, which selects the set.
+ * @returns the matched member, exactly as it will be sent.
+ * @throws HarnessError listing THAT model's accepted spellings.
+ */
+export declare function assertVideoResolution(value: unknown, model: MinimaxVideoModel): MinimaxVideoResolution;
+/**
+ * Every `ratio` spelling the service accepts, in upstream's own order.
+ *
+ * COPIED FROM UPSTREAM'S SCHEMA (docs/minimax-video-extended-spec.md section 1),
+ * including `adaptive`. `adaptive` is listed even though a caller should rarely
+ * type it, because the LINKAGE below produces it: on the H3 family a keyframe
+ * submit OVERWRITES whatever ratio was given with `adaptive`, and a reference
+ * submit defaults to it.
+ */
+export declare const MINIMAX_VIDEO_RATIOS: readonly ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16", "adaptive"];
+export type MinimaxVideoRatio = (typeof MINIMAX_VIDEO_RATIOS)[number];
+/** The ratio the H3 linkage sends for a text-only submit (upstream: `ratio ?? '16:9'`). */
+export declare const MINIMAX_H3_TEXT_DEFAULT_RATIO: MinimaxVideoRatio;
+/** The ratio the H3 linkage FORCES when a first and/or last frame is present. */
+export declare const MINIMAX_KEYFRAME_RATIO: MinimaxVideoRatio;
+/** The ratio the H3 linkage falls back to when reference media is present. */
+export declare const MINIMAX_REFERENCE_DEFAULT_RATIO: MinimaxVideoRatio;
+/**
+ * The resolution the H3 linkage sends when the caller names none.
+ *
+ * UPSTREAM'S DEFAULT (`input.resolution ?? '2K'`), applied only where it is a
+ * LEGAL value for that model - see {@link resolveVideoSubmissionResolution} for
+ * the one row where the literal rule and the measured table disagree.
+ */
+export declare const MINIMAX_H3_DEFAULT_RESOLUTION: MinimaxVideoResolution;
+/**
+ * Whether this model belongs to the H3 family, which is what the ratio and
+ * resolution linkage is written for.
+ *
+ * THE SAME PREDICATE UPSTREAM USES (`isH3VideoModel`), and the same one that
+ * decides reference-media support: H3 and H3-Max take the reference collections
+ * and the linkage defaults, Hailuo-2.3 takes neither.
+ *
+ * @param model - a model id.
+ * @returns true for `MiniMax-H3` and `MiniMax-H3-Max`.
+ */
+export declare function isH3VideoModel(model: string): boolean;
+/**
+ * Prove the `ratio` argument is one of the spellings the service knows.
+ *
+ * ONLY THE SPELLING IS CHECKED HERE. Which ratio is finally sent is decided by
+ * {@link resolveVideoSubmissionRatio}, because on the H3 family the caller's
+ * choice is often replaced (a keyframe submit is forced to `adaptive`) and on
+ * Hailuo it is passed through untouched. Refusing an invented spelling here means
+ * the linkage never has to reason about a value the service would reject anyway,
+ * and it costs no request.
+ *
+ * @param value - the caller's argument.
+ * @returns the matched spelling, exactly as the schema lists it.
+ * @throws HarnessError `MINIMAX_VIDEO_RATIO_INVALID` listing every spelling.
+ */
+export declare function assertVideoRatio(value: unknown): MinimaxVideoRatio;
+/** Everything the ratio rule branches on. */
+export interface MinimaxVideoRatioDecision {
+    /** The model the submit names; only the H3 family gets a default. */
+    readonly model: MinimaxVideoModel;
+    /** The caller's ratio, already proven to be a known spelling. */
+    readonly ratio?: MinimaxVideoRatio;
+    /** True when `inputImagePath` and/or `lastFrameImagePath` is present. */
+    readonly hasKeyframes: boolean;
+    /** True when at least one reference image, video or audio is present. */
+    readonly hasReferences: boolean;
+}
+/**
+ * Decide the ratio that is actually SENT, or undefined when none is.
+ *
+ * COPIED FROM UPSTREAM (`submit-video-generation.ts:77-86`), branch for branch:
+ *
+ * ```ts
+ * const effectiveRatio = isH3VideoModel(model)
+ *   ? hasKeyframes ? 'adaptive'
+ *     : hasReferences ? (ratio ?? 'adaptive')
+ *     : (ratio ?? '16:9')
+ *   : ratio
+ * ```
+ *
+ * ONE REFUSAL IS ADDED ON TOP, and it comes from upstream's own description
+ * ("cannot use adaptive"): `adaptive` means "adapt to the input frame", so a
+ * TEXT-ONLY submit has nothing to adapt to. Sending it anyway would spend a
+ * billed request learning what upstream already states, so it is refused here,
+ * for every model - a text-only adaptive request is meaningless whichever model
+ * reads it. On the H3 family the refusal is also unavoidable rather than
+ * pedantic: the text-only branch would otherwise have replaced it with `16:9`
+ * silently, and a caller who asked for `adaptive` and got `16:9` was never told.
+ *
+ * @param input - the model, the caller's ratio, and what the call carries.
+ * @returns the ratio to send, or undefined to send no `ratio` field at all.
+ * @throws HarnessError `MINIMAX_VIDEO_RATIO_ADAPTIVE_UNSUPPORTED` for a
+ *   text-only adaptive call.
+ */
+export declare function resolveVideoSubmissionRatio(input: MinimaxVideoRatioDecision): MinimaxVideoRatio | undefined;
+/**
+ * Decide the resolution that is actually SENT, or undefined when none is.
+ *
+ * TWO VALUES, AND THEY ARE NOT THE SAME VALUE - which is the whole point of the
+ * split with {@link assertVideoResolution}:
+ *
+ * - The CALLER's resolution is proven by `assertVideoResolution`, against the
+ * measured set for the model in {@link MINIMAX_VIDEO_MODEL_RULES}. That check runs
+ * first, outside this function, and is untouched by it.
+ * - The value SENT is what this function returns. For the H3 family it is
+ * `resolution ?? '2K'` (upstream's "defaults to 2K when omitted"); for Hailuo it
+ * is whatever the caller gave, with NO default, because upstream sets none for
+ * that model. THIS IS THE BEHAVIOUR CHANGE: an H3 submit that names no resolution
+ * used to send no `resolution` field at all, and now sends `2K`.
+ *
+ * THE ONE PLACE THIS DELIBERATELY DIVERGES FROM A LITERAL COPY, and the reason is
+ * MEASURED rather than stylistic: `MiniMax-H3-Max` is part of the H3 family, so
+ * the literal rule would make 2K its default - and 2K is exactly the spelling its
+ * measured set does NOT contain ("model resolution for MiniMax-H3-Max must be
+ * 480P or 768P", docs/minimax-video-model-rules.md section 2.1). Defaulting it to
+ * 2K would turn every H3-Max call that omits `resolution` into a billed submit
+ * the service always refuses. So the default is applied only where it is a legal
+ * member of THAT model's set; where it is not, no resolution is sent and the
+ * service keeps its own default - H3-Max's behaviour is unchanged on purpose.
+ *
+ * @param model - the model the submit names.
+ * @param resolution - the caller's value, already proven legal for that model.
+ * @returns the resolution to send, or undefined to send no `resolution` field.
+ */
+export declare function resolveVideoSubmissionResolution(model: MinimaxVideoModel, resolution: MinimaxVideoResolution | undefined): MinimaxVideoResolution | undefined;
+/**
+ * Prove one URL is a public destination before anything connects to it.
+ *
+ * The generation response's own video_url is upstream data, not a caller
+ * argument, and that is exactly why the gate matters: a service - or anything
+ * that has compromised its response - that answered with http://127.0.0.1/...
+ * would otherwise turn this tool into a reader of the user's own machine.
+ */
+export declare function assertPublicUrl(url: URL, what: string): Promise<void>;
+/** The one CDN host measured to work through the `url` key (upload probe section 4). */
+export declare const MINIMAX_CDN_HOST = "cdn.hailuoai.com";
+/**
+ * The agent hosts whose own addresses the service also accepts.
+ *
+ * MEASURED for the CDN host only (docs/minimax-video-upload-probe.md section 4:
+ * `get_upload_url` answered `cdn_url` on `cdn.hailuoai.com` and citing that
+ * address answered `success: true`). The `agent.minimax.` forms are accepted
+ * because they are MiniMax's own origin hosts - the same family this line already
+ * talks to - and refusing them would break a source the service would take. This
+ * half is NOT probe-confirmed; it is the service's own-family host, accepted on
+ * that basis alone.
+ */
+export declare const MINIMAX_CDN_HOST_SUFFIXES: readonly string[];
+/**
+ * Refuse a `url` source that is not a MiniMax-hosted address.
+ *
+ * THE MEASURED REASON. Two of three third-party URLs were confirmed fetchable
+ * from this machine - HTTP 206, `video/mp4`, `ftypmp42` - and the service still
+ * answered `results[0].success: false` with `video_info.url could not be used as
+ * a media source` for all three (docs/minimax-video-free-checks.md sections 5.2
+ * and 5.3). The key is syntactically legal; the service simply will not go and
+ * fetch a third party's address. Only its own CDN is measured to work.
+ *
+ * So a third-party address is refused locally, before the request, with the
+ * remedy (send the local file) instead of a remote refusal that reads like a
+ * transient problem.
+ *
+ * The exempt hosts are exactly the ones this route's own upload path produces,
+ * so `transport: "upload"` never trips this check.
+ *
+ * `what` NAMES THE ARGUMENT, and that is not decoration: the generation submit
+ * carries a whole set of media arguments (a first frame, a last frame, up to
+ * nine reference images, three reference videos, three reference audios), so a
+ * refusal that said only "the URL" would leave the caller hunting for which of
+ * thirteen arguments it was.
+ *
+ * @param url - the parsed caller URL.
+ * @param what - the argument being refused, named in the message.
+ * @throws HarnessError `MINIMAX_VIDEO_URL_NOT_MINIMAX_CDN` for anything else.
+ */
+export declare function assertMinimaxCdnUrl(url: URL, what?: string): void;
+/** How many leading bytes the container sniff reads. Enough for every magic below. */
+export declare const VIDEO_CONTAINER_SNIFF_BYTES = 32;
+/** The video container one file's first bytes declare. */
+export type VideoContainerKind = 'iso-bmff' | 'matroska' | 'avi' | 'mpeg-ps';
+/**
+ * Identify the video container from the first bytes of a file.
+ *
+ * WHY THIS EXISTS AT ALL. The service answers `results[0].success: true` for
+ * bytes no decoder could ever read: 1 MiB of `0x11` filler came back with a
+ * confident, invented description of a tabby cat, and a 5 MiB sample with a
+ * "purple onion rotating on white" (docs/minimax-video-free-checks.md section
+ * 4.4). So a file that is NOT a video does not fail loudly upstream - it comes
+ * back as a fabricated answer the user will believe was about their clip. The
+ * cheapest place to stop that is here, on this machine, before the bytes leave.
+ *
+ * The four magic numbers are the ones the extensions this route accepts map to:
+ *
+ * | container            | leading bytes                                      |
+ * | -------------------- | -------------------------------------------------- |
+ * | ISO BMFF (mp4/mov)   | offset 4 is ASCII `ftyp`                            |
+ * | Matroska / WebM      | `1A 45 DF A3`                                       |
+ * | AVI (RIFF)           | `RIFF` at 0 and `AVI ` at 8                        |
+ * | MPEG program stream  | `00 00 01 BA` (pack) or `00 00 01 B3` (video seq)   |
+ *
+ * @param head - the first {@link VIDEO_CONTAINER_SNIFF_BYTES} bytes (or fewer).
+ * @returns the container, or undefined when the bytes are none of them.
+ */
+export declare function sniffVideoContainer(head: Uint8Array): VideoContainerKind | undefined;
+/**
+ * The `category` every upload body must carry, measured upstream.
+ *
+ * WHY IT IS A CONSTANT RATHER THAN A LITERAL AT THE CALL SITE. The value is
+ * part of upstream's own measured request body
+ * (`{ filename, mime_type, size_bytes, category: 'user_file_upload_tmp' }`,
+ * docs/minimax-video-extended-spec.md section 2.1). It names the TEMPORARY
+ * bucket the object lands in, and it is the same bucket for a video being
+ * understood and for a reference image being sent to the generation service -
+ * so both paths share the one spelling instead of each carrying its own copy
+ * that can drift.
+ */
+export declare const MINIMAX_UPLOAD_CATEGORY = "user_file_upload_tmp";
+/**
+ * The tool parameter each service field name belongs to, and where they differ.
+ *
+ * THIS TABLE IS THE POINT OF THIS SECTION, so it is stated once, here, in the
+ * service's own spelling:
+ *
+ * | tool parameter             | sent as            |
+ * | -------------------------- | ------------------ |
+ * | inputImagePath             | input_image        |
+ * | lastFrameImagePath         | last_frame_image   |
+ * | referenceImagePaths        | reference_images   |
+ * | referenceVideoPaths        | reference_videos   |
+ * | referenceAudioPaths        | reference_audios   |
+ *
+ * Four of the five differ from their parameter names, which is exactly the kind
+ * of mapping that survives right up until someone builds the body by
+ * destructuring the arguments. Nothing outside this section spells either
+ * column: prepareGenerationMedia returns an object whose keys ARE the right-hand
+ * column, so the submit merges it instead of re-deriving a name.
+ * (docs/minimax-video-extended-spec.md section 0.)
+ */
+/** One prepared media argument: the shape the service reads. */
+export interface MinimaxMediaPayload {
+    /** A cdn.hailuoai.com address - measured to be the only url shape read. */
+    readonly url: string;
+    readonly mime_type: string;
+}
+/** A prepared reference video: a media payload plus the length the service needs. */
+export interface MinimaxVideoMediaPayload extends MinimaxMediaPayload {
+    /** Seconds, from the container or from the caller. */
+    readonly duration_seconds: number;
+}
+/**
+ * Largest total number of reference media items (images + videos + audios).
+ *
+ * COPIED FROM UPSTREAM'S MEASURED LIMITS (spec section 6): 1-9 images, 1-3
+ * videos, 1-3 audios, and never more than 12 in total. The per-set ceilings are
+ * enforced as well as the total, because the two refuse different mistakes -
+ * 9 images plus 3 videos is 12 items and passes both, while 13 images passes
+ * neither.
+ */
+export declare const MAX_REFERENCE_MEDIA_TOTAL = 12;
+/** Most reference images one submit may carry. */
+export declare const MAX_REFERENCE_IMAGES = 9;
+/** Most reference videos one submit may carry. */
+export declare const MAX_REFERENCE_VIDEOS = 3;
+/** Most reference audios one submit may carry. */
+export declare const MAX_REFERENCE_AUDIOS = 3;
+/**
+ * How far a caller's stated reference-video length may sit from the length this
+ * route reads out of the container before the two are treated as a contradiction.
+ *
+ * A SECOND of slack, because the container reports an exact rational and a
+ * caller writing 10 for a 10.033 s clip is not wrong. Beyond that the two
+ * describe different clips, and accepting either one silently would mean
+ * sending a length the user never saw.
+ */
+export declare const MINIMAX_REFERENCE_DURATION_TOLERANCE_SECONDS = 1;
+/**
+ * Everything one media preparation needs.
+ *
+ * sleepFn and backoffMs are here because the upload channel retries, and a test
+ * must not spend the real 1.5 s doing it - the same injection the understanding
+ * path already uses.
+ */
+export interface MinimaxMediaPrepareContext {
+    readonly credential: MinimaxVideoCredential;
+    readonly fetchFn: FetchLike;
+    readonly sleepFn: (ms: number) => Promise<void>;
+    readonly backoffMs: number;
+    readonly signal?: AbortSignal;
+    /** The model the submit names, which can narrow the legal extension set. */
+    readonly model?: MinimaxVideoModel;
+}
+/** The media arguments one generation call may carry, as the caller typed them. */
+export interface MinimaxGenerationMediaInput {
+    readonly inputImagePath?: string;
+    readonly lastFrameImagePath?: string;
+    readonly referenceImagePaths?: readonly string[];
+    readonly referenceVideoPaths?: readonly string[];
+    readonly referenceVideoDurationSeconds?: readonly number[];
+    readonly referenceAudioPaths?: readonly string[];
+}
+/**
+ * The prepared media, keyed by the SERVICE's field names.
+ *
+ * The two booleans beside them are what the submit's ratio rule branches on;
+ * they are reported rather than acted on here, because this layer decides what
+ * is sent as media, not what ratio defaults to.
+ */
+export interface MinimaxGenerationMedia {
+    readonly input_image?: MinimaxMediaPayload;
+    readonly last_frame_image?: MinimaxMediaPayload;
+    readonly reference_images?: readonly MinimaxMediaPayload[];
+    readonly reference_videos?: readonly MinimaxVideoMediaPayload[];
+    readonly reference_audios?: readonly MinimaxMediaPayload[];
+    /** True when a first and/or last frame image was prepared. */
+    readonly hasKeyframes: boolean;
+    /** True when at least one reference image, video or audio was prepared. */
+    readonly hasReferences: boolean;
+}
+/**
+ * Whether this model accepts the reference collections at all.
+ *
+ * Hailuo-2.3 does not (spec section 7): upstream's own description limits it to
+ * first_frame and the legacy subject reference type, with no image/video/audio
+ * reference sets and no last frame. Both H3 models do.
+ *
+ * @param model - the model id the submit names.
+ * @returns true for the two H3 models.
+ */
+export declare function minimaxModelSupportsReferenceMedia(model: string): boolean;
+/** A length rounded the way seconds are reported, without float noise. */
+export declare function normalizeDurationSeconds(seconds: number): number;
+/**
+ * Prepare an image argument (a first frame, a last frame, or a reference).
+ *
+ * @param pathOrUrl - absolute local path, or a MiniMax CDN URL.
+ * @param fieldName - the tool argument, for every message this can raise.
+ * @param context - credential, fetch, retry policy and the model.
+ * @returns an object with url and mime_type.
+ */
+export declare function prepareImageInput(pathOrUrl: string, fieldName: string, context: MinimaxMediaPrepareContext): Promise<MinimaxMediaPayload>;
+/**
+ * Prepare an audio argument.
+ *
+ * @param pathOrUrl - absolute local path, or a MiniMax CDN URL.
+ * @param fieldName - the tool argument, for every message this can raise.
+ * @param context - credential, fetch, retry policy and the model.
+ * @returns an object with url and mime_type.
+ */
+export declare function prepareAudioInput(pathOrUrl: string, fieldName: string, context: MinimaxMediaPrepareContext): Promise<MinimaxMediaPayload>;
+/**
+ * Reconcile the caller's stated reference-video length with the one this route
+ * read out of the file.
+ *
+ * THE CALLER WINS, BUT NOT SILENTLY (spec section 4.4): a caller may deliberately
+ * trim a clip and state the trimmed length, so their number is the one sent -
+ * but if the container disagrees by more than
+ * MINIMAX_REFERENCE_DURATION_TOLERANCE_SECONDS the two are describing different
+ * things, and sending either one quietly would mean the user believes a 5 s
+ * reference was used while 12 s went out.
+ *
+ * @param fieldName - the tool argument, for the message.
+ * @param measured - seconds read from the container.
+ * @param given - the caller's value, when they supplied one.
+ * @returns the length to send.
+ * @throws HarnessError naming BOTH values when they contradict each other.
+ */
+export declare function reconcileReferenceVideoDurationSeconds(fieldName: string, measured: number, given: number | undefined): number;
+/**
+ * Prepare a reference video: the media payload PLUS the length it must carry.
+ *
+ * THE LENGTH COMES FROM TWO PLACES AND THEY ARE NOT INTERCHANGEABLE:
+ *
+ * - a LOCAL file is read here, out of the container's own moov/mvhd
+ *   (readIsoBmffDurationSeconds), so the caller owes nothing;
+ * - a REMOTE URL cannot be read - this route does not download a reference to
+ *   measure it, and the service does not either - so the caller MUST state it,
+ *   and a missing value is refused rather than guessed (spec section 4.2).
+ *
+ * @param pathOrUrl - absolute local path, or a MiniMax CDN URL.
+ * @param fieldName - the tool argument, for every message this can raise.
+ * @param durationSeconds - the caller's stated length, when they gave one.
+ * @param context - credential, fetch, retry policy and the model.
+ * @returns an object with url, mime_type and duration_seconds.
+ */
+export declare function prepareVideoInput(pathOrUrl: string, fieldName: string, durationSeconds: number | undefined, context: MinimaxMediaPrepareContext): Promise<MinimaxVideoMediaPayload>;
+/**
+ * Prepare every media argument of one generation submit.
+ *
+ * The ORDER of the refusals is deliberate: the free ones come first. A model
+ * that does not accept reference media at all is refused before a single file is
+ * read, and the counts are checked before any upload, so an over-limit call
+ * costs no request instead of nine uploads and then a refusal.
+ *
+ * @param input - the media arguments as the caller typed them.
+ * @param model - the model the submit names, which constrains what is legal.
+ * @param context - credential, fetch, retry policy.
+ * @returns the media keyed by the SERVICE's field names, plus the two booleans
+ *   the ratio rule branches on.
+ * @throws HarnessError for any refusal; nothing is uploaded before the last free
+ *   check has passed.
+ */
+export declare function prepareGenerationMedia(input: MinimaxGenerationMediaInput, model: MinimaxVideoModel, context: MinimaxMediaPrepareContext): Promise<MinimaxGenerationMedia>;
+/**
+ * Extract the byte count from an `inline:<N>B` source, or undefined.
+ *
+ * Only the inline spelling carries a count; a URL source echoes the URL, and a
+ * body with no `source` at all carries nothing. Both are "no count", and the
+ * caller SKIPS the cross-check rather than failing it.
+ *
+ * @param source - the measured `results[0].source`.
+ * @returns the byte count, or undefined when the source is not `inline:<N>B`.
+ */
+export declare function inlineSourceBytes(source: string): number | undefined;
+/**
+ * Whether this text says the video was never seen.
+ *
+ * @param text - the description, the error, or both joined.
+ * @returns true when the text declares no video was received.
+ */
+export declare function declaresNoVideoViewed(text: string): boolean;
+/**
+ * Build the video-understanding tool.
+ *
+ * @param ctx - host context (the route gate needs no service, but the context
+ *   is kept for symmetry with the generation tool and for later extensions).
+ * @param options - credential source, fetch and the injectable clocks.
+ * @returns a registry-ready tool definition.
+ */
+export declare function createMinimaxUnderstandVideoTool(ctx: Context, options: MinimaxVideoToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export declare function createMinimaxGenerateVideoTool(ctx: Context, options: MinimaxVideoToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export {};
+//# sourceMappingURL=video-tool.d.ts.map