@hypit/hypit 0.2.3 → 0.2.4

package/packages/provider-pollo/src/routes.ts

@@ -0,0 +1,120 @@
+import {
+  compileWireRequest,
+  selectWireModelForRequest,
+  generationTypes,
+  sealGeneratedImageSet,
+  sealGeneratedVideoSet,
+} from "@hypit/generation";
+import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } from "@hypit/generation";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CapabilityRef, CanonicalValue, StoredValue, TypeRef } from "@hypit/protocol";
+import type { EndpointRequest, EndpointSupport } from "@hypit/endpoint-kit";
+import { polloMappings } from "./mapping.js";
+
+export type PolloPreparedRequest = {
+  /** Request path under the Pollo platform base URL. */
+  readonly path: string;
+  readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;
+};
+
+export type PolloRoute = GenerationWireMapping & {
+  readonly key: string;
+  readonly returns: TypeRef;
+  readonly supports: (request: EndpointRequest) => EndpointSupport;
+  readonly prepare: (constraints: CanonicalValue) => PolloPreparedRequest;
+  readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
+};
+
+function scalar(request: GenerationRequest, port: string): string | number | boolean | undefined {
+  const value = request.ports[port]?.[0];
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : undefined;
+}
+function count(request: GenerationRequest, port: string): number {
+  return request.ports[port]?.length ?? 0;
+}
+function strings(value: unknown): readonly string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];
+}
+
+const GPT_IMAGE_RATIOS = ["1:1", "3:2", "2:3", "16:9", "9:16", "4:3", "3:4", "21:9", "auto"];
+
+/** Pollo's documented input ranges for each mapped model, checked before any reference is resolved. */
+function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {
+  const { name } = mapping.capability;
+  const ratio = scalar(request, "aspectRatio");
+  if (name === "grok-imagine-video-1.5-preview") {
+    if (count(request, "images") !== 1) return "Pollo Grok Imagine 1.5 animates exactly one image";
+    if (ratio !== "auto") return `Pollo Grok Imagine 1.5 takes no aspect ratio; use auto, not ${String(ratio)}`;
+  }
+  if (name === "gpt-image-2" && !GPT_IMAGE_RATIOS.includes(String(ratio))) {
+    return `Pollo GPT Image 2 does not render ${String(ratio)}`;
+  }
+  if (mapping.capability.module.name === "@hypit/nano-banana" && ratio === "auto") {
+    return `Pollo ${name} takes an explicit aspect ratio, not auto`;
+  }
+  return undefined;
+}
+
+function ref(type: "image" | "video" | "audio") {
+  return (url: string) => ({ url, type });
+}
+
+/** Fields the model package requires that Pollo names differently or does not take. */
+function normalize(mapping: GenerationWireMapping, input: Record<string, unknown>): Record<string, unknown> {
+  const { name } = mapping.capability;
+  if (name === "minimax-h3") {
+    const refs = [
+      ...strings(input.refs_image).map(ref("image")),
+      ...strings(input.refs_video).map(ref("video")),
+      ...strings(input.refs_audio).map(ref("audio")),
+    ];
+    delete input.refs_image;
+    delete input.refs_video;
+    delete input.refs_audio;
+    if (refs.length > 0) input.refs = refs;
+  }
+  if (name === "grok-imagine-video-1.5-preview") {
+    input.image = strings(input.images)[0];
+    delete input.images;
+    delete input.aspect_ratio;
+  }
+  if (mapping.capability.module.name === "@hypit/nano-banana") delete input.output_format;
+  return input;
+}
+
+function capabilityKey(capability: CapabilityRef): string {
+  return `${capability.module.name}@${capability.module.version}#${capability.name}`;
+}
+
+export const polloRoutes: readonly PolloRoute[] = polloMappings.map((mapping) => ({
+  ...mapping,
+  key: capabilityKey(mapping.capability),
+  returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+  supports: (request) => {
+    const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
+    return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
+  },
+  prepare: (constraints) => {
+    const request = constraints as unknown as GenerationRequest;
+    const reason = rejection(mapping, request);
+    if (reason !== undefined) throw new Error(reason);
+    return {
+      path: selectWireModelForRequest(mapping, request),
+      compile: async (resolve) => ({
+        input: normalize(mapping, (await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),
+      }),
+    };
+  },
+  packageResult: (artifacts) => ({
+    kind: "inline",
+    value: canonicalize(mapping.result === "image"
+      ? sealGeneratedImageSet({ images: artifacts })
+      : sealGeneratedVideoSet({ videos: artifacts })),
+  }),
+}));
+
+const byCapability = new Map(polloRoutes.map((route) => [route.key, route]));
+
+export function polloRouteForCapability(capability: CapabilityRef): PolloRoute | undefined {
+  return byCapability.get(capabilityKey(capability));
+}

package/packages/provider-tokendance/README.md

@@ -0,0 +1,67 @@
+# `@hypit/provider-tokendance`
+
+Hypit Runtime Provider for a [TokenDance](https://tokendance.space) account. It submits generation
+requests with a TokenDance API key through the gateway protocols TokenDance documents for each model
+and stores the returned files in the current Build.
+
+| Capability | TokenDance model | Protocol |
+| --- | --- | --- |
+| `@hypit/seedance@1#seedance-2` | `seedance-2.0` | Ark `POST /ark/v3/generations/tasks`, polled at `GET /ark/v3/generations/tasks/{id}` |
+| `@hypit/seedance@1#seedance-2-fast` | `seedance-2.0-fast` | same |
+| `@hypit/seedance@1#seedance-2-mini` | `seedance-2.0-mini` | same |
+| `@hypit/seedance@1#seedance-2.5` | `seedance-2.5` | same |
+| `@hypit/seedream@1#seedream-5-lite` | `seedream-5.0-lite` | Ark `POST /ark/v3/images/generations`, synchronous |
+| `@hypit/minimax-h3@1#minimax-h3` | `minimax-h3` | MiniMax `POST /minimax/v2/video_generation`, polled at `GET /minimax/v2/query/video_generation/{id}` |
+
+The TokenDance catalogue at `GET /gateway/v1/models` lists further models; this Provider maps only
+the models the Distribution already describes.
+
+Video requests write the prompt and each media input as one item of the protocol's `content`
+array with its `role` (`first_frame`, `last_frame`, `reference_image`, `reference_video`,
+`reference_audio`), then `resolution`, `ratio`, `duration` and, for Seedance, `generate_audio`;
+`web-search="true"` adds `tools: [{ "type": "web_search" }]`. Seedance visual references may carry
+`person-reference`; the Provider accepts the declaration and transmits nothing for it, since the Ark
+protocol has no such field. Seedance 2.0 and 2.5 reject reference images and videos that contain a
+real human face; TokenDance offers no way to register authorized portrait material, so such a request
+fails with the service's moderation error.
+
+Seedream requests send the Ark `size` in pixels: the authored `quality` selects the 2K, 3K or 4K
+tier and `aspect-ratio` the entry from the Ark reference table for Seedream 5.0 lite. Output uses
+`response_format: "url"` and `watermark: false`. `nsfw-check` has no Ark field and is not sent.
+
+Service limits this Provider reports as unsupported before submitting:
+
+- Seedance 2.5 frame mode (`first-frame` present) requires `aspect-ratio="adaptive"`.
+- MiniMax H3 text-to-video requires an explicit `aspect-ratio`; frame and reference modes may omit it.
+
+Reference media reach each protocol the way its documentation provides. Ark takes images under
+30 MB and audio up to 15 MB inline as `data:` URLs within a 64 MB request body; the Provider checks
+both before submitting. An Ark reference video takes a URL only; configure `publicAssetUrl` when
+embedding the Provider, otherwise such a request fails before submission. MiniMax inputs are
+uploaded through the gateway's `POST /minimax/v1/files/upload` with `purpose:
+video_generation_input` (images up to 30 MB, videos up to 50 MB, audio up to 15 MB) and referenced
+as `mm_file://{file_id}`; MiniMax keeps such files for seven days.
+
+Runtime Profile example:
+
+```json
+{
+  "endpoints": {
+    "tokendance.default": {
+      "use": "@hypit/provider-tokendance",
+      "pool": "tokendance.default",
+      "config": {
+        "apiKey": { "store": "platform", "key": "tokendance.api-key" },
+        "defaultConcurrency": 3,
+        "pollIntervalMs": 10000
+      }
+    }
+  }
+}
+```
+
+`baseUrl` defaults to `https://tokendance.space/gateway`. Store the API key with
+`hypit auth login tokendance.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,
+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote task and action
+concurrency. Task and HTTP failures keep TokenDance's `error.code` and message, with any signed URL
+in the message redacted.

package/packages/provider-tokendance/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/provider-tokendance",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": { ".": "./src/index.ts" },
+  "hypit": { "activation": "./src/activation.ts" },
+  "dependencies": {
+    "@hypit/endpoint-kit": "workspace:*",
+    "@hypit/generation": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/minimax-h3": "workspace:*",
+    "@hypit/seedance": "workspace:*",
+    "@hypit/seedream": "workspace:*"
+  }
+}

package/packages/provider-tokendance/src/activation.ts

@@ -0,0 +1,62 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigCredentialRef,
+  runtimeConfigActionLimits,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createTokenDanceProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-tokendance",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("TokenDance Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "TokenDance");
+    runtimeConfigExact(config, [
+      "baseUrl",
+      "apiKey",
+      "defaultConcurrency",
+      "actionLimits",
+      "pollIntervalMs",
+      "requestTimeoutMs",
+      "operationTimeoutMs",
+    ], "TokenDance");
+    const baseUrl = runtimeConfigString(config.baseUrl, "TokenDance baseUrl");
+    if (baseUrl !== undefined) {
+      const url = new URL(baseUrl);
+      if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+        throw new Error("TokenDance baseUrl must use HTTPS or loopback");
+      }
+    }
+    const apiKey = runtimeConfigCredentialRef(config.apiKey, "TokenDance apiKey");
+    if (apiKey === undefined) throw new Error("TokenDance apiKey CredentialRef is required");
+    const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "TokenDance defaultConcurrency");
+    const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "TokenDance pollIntervalMs");
+    const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "TokenDance requestTimeoutMs");
+    const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "TokenDance operationTimeoutMs");
+    return {
+      endpoint: createTokenDanceProvider({
+        instance: context.instance,
+        pool: context.pool,
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        apiKey,
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(actionLimits === undefined ? {} : { actionLimits }),
+        ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+        ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+        ...(operationTimeoutMs === undefined ? {} : { operationTimeoutMs }),
+      }),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [adapter],
+};
+
+export default hypitPackage;

package/packages/provider-tokendance/src/errors.ts

@@ -0,0 +1,47 @@
+/** TokenDance relays each protocol's own error body; keep the code, the message and the HTTP facts. */
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// Responses may mention a signed asset URL. Keep the reason, not its access capability.
+export function safeTokenDanceReason(value: string): string {
+  return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class TokenDanceServiceError extends Error {
+  constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class TokenDanceHttpError extends TokenDanceServiceError {
+  constructor(readonly status: number, response: { readonly headers: Headers }, bodyText: string,
+    request: { readonly method: string; readonly path: string; readonly model?: string }) {
+    let body: Record<string, unknown> | undefined;
+    try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }
+    const error = record(body?.error);
+    const code = text(error?.code) ?? text(error?.type) ?? text(body?.code) ?? "TOKENDANCE_HTTP_ERROR";
+    const reason = text(error?.message) ?? text(body?.message)
+      ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+    const requestId = text(response.headers.get("x-request-id"));
+    const facts = [
+      `TokenDance HTTP ${status}`, code, `${request.method} ${request.path}`,
+      ...(request.model === undefined ? [] : [`model=${request.model}`]),
+      ...(requestId === undefined ? [] : [`request=${requestId}`]),
+    ];
+    super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safeTokenDanceReason(reason)}`}`);
+  }
+}
+
+/** A terminal task body from either protocol; `undefined` when the task did not fail. */
+export function tokenDanceTaskFailure(task: Record<string, unknown>, id: string): TokenDanceServiceError | undefined {
+  const status = String(task.status);
+  if (!["failed", "cancelled", "canceled", "expired"].includes(status)) return undefined;
+  const error = record(task.error);
+  const code = text(error?.code) ?? "TOKENDANCE_TASK_FAILED";
+  const reason = text(error?.message) ?? text(task.error);
+  return new TokenDanceServiceError(code,
+    `TokenDance task ${id} ${status}; ${code}${reason === undefined ? "" : `: ${safeTokenDanceReason(reason)}`}`);
+}

package/packages/provider-tokendance/src/index.ts

@@ -0,0 +1,2 @@
+export { createTokenDanceProvider, tokenDanceProviderModuleRef } from "./provider.js";
+export type { CreateTokenDanceProviderOptions } from "./provider.js";

package/packages/provider-tokendance/src/mapping.ts

@@ -0,0 +1,60 @@
+import type { ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
+const SEEDREAM: ModuleRef = { name: "@hypit/seedream", version: "1" };
+const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+
+/**
+ * TokenDance model IDs and the request fields they accept. Media fields name the `role` of an Ark
+ * or MiniMax `content` item; routes.ts folds them into that array. `personReference` is accepted
+ * on visual references and not transmitted: neither protocol has a field for it.
+ */
+const seedance = (name: string, model: string): GenerationWireMapping => ({
+  capability: { module: SEEDANCE, name }, result: "video", routes: [{ model }],
+  fields: {
+    prompt: { as: "value", field: "text" },
+    referenceImage: { as: "urlArray", field: "reference_image", resourceFields: ["personReference"] },
+    referenceVideo: { as: "urlArray", field: "reference_video", resourceFields: ["personReference"] },
+    referenceAudio: { as: "urlArray", field: "reference_audio" },
+    firstFrame: { as: "url", field: "first_frame", resourceFields: ["personReference"] },
+    lastFrame: { as: "url", field: "last_frame", resourceFields: ["personReference"] },
+    resolution: { as: "value", field: "resolution" },
+    aspectRatio: { as: "value", field: "ratio" },
+    duration: { as: "value", field: "duration" },
+    generateAudio: { as: "value", field: "generate_audio" },
+    webSearch: { as: "value", field: "web_search" },
+  },
+});
+
+export const tokenDanceMappings: readonly GenerationWireMapping[] = [
+  seedance("seedance-2", "seedance-2.0"),
+  seedance("seedance-2-fast", "seedance-2.0-fast"),
+  seedance("seedance-2-mini", "seedance-2.0-mini"),
+  seedance("seedance-2.5", "seedance-2.5"),
+  {
+    capability: { module: SEEDREAM, name: "seedream-5-lite" }, result: "image", routes: [{ model: "seedream-5.0-lite" }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      quality: { as: "value", field: "quality" },
+      outputFormat: { as: "value", field: "output_format" },
+      nsfwCheck: { as: "value", field: "nsfw_check" },
+      images: { as: "urlArray", field: "image" },
+    },
+  },
+  {
+    capability: { module: MINIMAX, name: "minimax-h3" }, result: "video", routes: [{ model: "minimax-h3" }],
+    fields: {
+      prompt: { as: "value", field: "text" },
+      duration: { as: "value", field: "duration" },
+      resolution: { as: "value", field: "resolution", whenAbsent: "2K" },
+      aspectRatio: { as: "value", field: "ratio" },
+      referenceImage: { as: "urlArray", field: "reference_image" },
+      referenceVideo: { as: "urlArray", field: "reference_video" },
+      referenceAudio: { as: "urlArray", field: "reference_audio" },
+      firstFrame: { as: "url", field: "first_frame" },
+      lastFrame: { as: "url", field: "last_frame" },
+    },
+  },
+];

package/packages/provider-tokendance/src/provider.ts

@@ -0,0 +1,268 @@
+import { requestDeadline } from "@hypit/runtime-kit";
+import type { AsyncEndpoint, EndpointCredential, EndpointInvocationContext, EndpointOutcome, ImmediateEndpointHandler } from "@hypit/endpoint-kit";
+import { defineEndpointPackage, wakeAfter } from "@hypit/endpoint-kit";
+import type { GenerationArtifactUrlResolver } from "@hypit/generation";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CapabilityRef } from "@hypit/protocol";
+import { credentialRef } from "@hypit/runtime";
+import type { CredentialRef, ResourceStore } from "@hypit/runtime";
+import { tokenDanceRouteForCapability, tokenDanceRoutes } from "./routes.js";
+import type { TokenDanceRoute } from "./routes.js";
+import { TokenDanceHttpError, TokenDanceServiceError, tokenDanceTaskFailure } from "./errors.js";
+
+export const tokenDanceProviderModuleRef = { name: "@hypit/provider-tokendance", version: "1" } as const;
+
+export type CreateTokenDanceProviderOptions = {
+  readonly instance?: string;
+  readonly pool?: string;
+  readonly baseUrl?: string;
+  readonly apiKey?: CredentialRef;
+  readonly defaultConcurrency?: number;
+  readonly actionLimits?: import("@hypit/endpoint-kit").EndpointActionLimits;
+  readonly pollIntervalMs?: number;
+  readonly requestTimeoutMs?: number;
+  readonly operationTimeoutMs?: number;
+  readonly fetch?: typeof globalThis.fetch;
+  /** Publish a referenced Resource at a URL the service can fetch; replaces inline data URLs. */
+  readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;
+};
+
+type Handle = {
+  readonly contract: "hypit.tokendance-operation@1";
+  readonly taskId: string;
+  readonly route: string;
+  readonly startedAt: number;
+  readonly url?: string;
+};
+
+function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
+function object(value: unknown, subject: string): Record<string, unknown> {
+  assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+  return value as Record<string, unknown>;
+}
+function capabilityKey(capability: CapabilityRef): string { return `${capability.module.name}@${capability.module.version}#${capability.name}`; }
+function apiBaseUrl(value: string): string {
+  let trimmed = value.trim();
+  while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+  assert(trimmed.length > 0, "TokenDance base URL is empty");
+  return trimmed;
+}
+function apiKey(credentials: Readonly<Record<string, EndpointCredential>>): string {
+  const value = credentials.apiKey?.secret;
+  assert(typeof value === "string" && value.length > 0, "TokenDance apiKey credential is unavailable; store a TokenDance API key for this Endpoint");
+  return value;
+}
+function failureMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+function failure(error: unknown): EndpointOutcome {
+  return { status: "failed", failure: { code: error instanceof TokenDanceServiceError ? error.code : "TOKENDANCE_ERROR", message: failureMessage(error) } };
+}
+function httpsUrl(value: unknown, subject: string): string {
+  assert(typeof value === "string" && /^https?:\/\//u.test(value), `${subject} has no download URL`);
+  return value;
+}
+
+class TokenDanceClient {
+  constructor(readonly baseUrl: string, readonly timeout: number, readonly fetcher: typeof globalThis.fetch) {}
+  async json(path: string, key: string, init: RequestInit = {}): Promise<Record<string, unknown>> {
+    const deadline = requestDeadline(this.timeout);
+    try {
+      const response = await deadline.wait(this.fetcher(`${this.baseUrl}${path}`, {
+        ...init, signal: deadline.signal, headers: { authorization: `Bearer ${key}`, ...(init.headers ?? {}) },
+      }));
+      const text = await deadline.wait(response.text());
+      if (!response.ok) {
+        const input = typeof init.body === "string" ? JSON.parse(init.body) as Record<string, unknown> : undefined;
+        throw new TokenDanceHttpError(response.status, response, text, {
+          method: init.method ?? "GET", path, ...(typeof input?.model === "string" ? { model: input.model } : {}),
+        });
+      }
+      let body: unknown;
+      try { body = text.length === 0 ? {} : JSON.parse(text); } catch { throw new Error(`TokenDance returned invalid JSON (${response.status})`); }
+      return object(body, "TokenDance response");
+    } finally { deadline.finish(); }
+  }
+  /** MiniMax's file API through the gateway; the returned id is referenced as `mm_file://{file_id}`. */
+  async uploadMiniMaxInput(bytes: Uint8Array, artifact: BlobRef, key: string): Promise<string> {
+    const form = new FormData();
+    form.set("purpose", "video_generation_input");
+    form.set("file", new Blob([new Uint8Array(bytes)], { type: artifact.mediaType }), `${artifact.resource}.${artifact.mediaType.split("/")[1] ?? "bin"}`);
+    const response = await this.json("/minimax/v1/files/upload", key, { method: "POST", body: form });
+    const status = object(response.base_resp ?? {}, "TokenDance upload base_resp").status_code;
+    assert(status === undefined || status === 0, `TokenDance MiniMax upload rejected: ${String(object(response.base_resp, "TokenDance upload base_resp").status_msg ?? status)}`);
+    const id = object(response.file, "TokenDance upload file").file_id;
+    assert((typeof id === "string" && id.length > 0) || typeof id === "number", "TokenDance MiniMax upload returned no file_id");
+    return `mm_file://${String(id)}`;
+  }
+  async download(url: string): Promise<{ readonly bytes: Uint8Array; readonly mediaType: string }> {
+    const deadline = requestDeadline(this.timeout);
+    try {
+      const response = await deadline.wait(this.fetcher(url, { signal: deadline.signal }));
+      if (!response.ok) throw new Error(`TokenDance asset returned HTTP ${response.status}`);
+      return { bytes: new Uint8Array(await deadline.wait(response.arrayBuffer())), mediaType: response.headers.get("content-type")?.split(";", 1)[0] ?? "application/octet-stream" };
+    } finally { deadline.finish(); }
+  }
+}
+
+function mediaKind(mediaType: string): "image" | "video" | "audio" | undefined {
+  const kind = mediaType.split("/", 1)[0];
+  return kind === "image" || kind === "video" || kind === "audio" ? kind : undefined;
+}
+
+function resolverFor(client: TokenDanceClient, route: TokenDanceRoute, context: EndpointInvocationContext, publicAssetUrl: CreateTokenDanceProviderOptions["publicAssetUrl"]): GenerationArtifactUrlResolver {
+  const resolved = new Map<string, Promise<string>>();
+  return (artifact, fields) => {
+    const existing = resolved.get(artifact.resource);
+    if (existing !== undefined) return existing;
+    const promise = (async () => {
+      if (publicAssetUrl !== undefined) return await publicAssetUrl(artifact, context.resources, fields);
+      const kind = mediaKind(artifact.mediaType);
+      const limit = kind === undefined ? undefined : route.mediaLimits[kind];
+      assert(limit !== undefined,
+        `TokenDance ${route.protocol} accepts ${artifact.mediaType} references only by public URL; configure publicAssetUrl for this Endpoint`);
+      assert(artifact.size <= limit,
+        `TokenDance ${route.protocol} accepts ${kind} references up to ${limit / 1_000_000} MB; ${artifact.resource} is ${artifact.size} bytes`);
+      const bytes = await context.resources.get(artifact.resource);
+      assert(bytes !== undefined && bytes.byteLength === artifact.size, `Reference Resource ${artifact.resource} is unavailable or has changed`);
+      if (route.protocol === "minimax-video") return await client.uploadMiniMaxInput(bytes, artifact, apiKey(context.credentials));
+      return `data:${artifact.mediaType};base64,${Buffer.from(bytes).toString("base64")}`;
+    })();
+    resolved.set(artifact.resource, promise);
+    return promise;
+  };
+}
+
+async function prepare(client: TokenDanceClient, context: EndpointInvocationContext, publicAssetUrl: CreateTokenDanceProviderOptions["publicAssetUrl"]) {
+  const route = tokenDanceRouteForCapability(context.need.capability);
+  assert(route !== undefined, "TokenDance does not implement this exact capability");
+  const request = route.prepare(context.need.constraints);
+  await context.reportProgress?.({ phase: `Preparing TokenDance request: ${request.model}` });
+  let body: string;
+  try {
+    body = JSON.stringify(await request.compile(resolverFor(client, route, context, publicAssetUrl)));
+    const cap = route.mediaLimits.body;
+    assert(cap === undefined || Buffer.byteLength(body) <= cap,
+      `TokenDance ${route.protocol} accepts request bodies up to ${(cap ?? 0) / 1_000_000} MB; inline references make this one ${Buffer.byteLength(body)} bytes`);
+  } catch (error) {
+    throw new TokenDanceServiceError(error instanceof TokenDanceServiceError ? error.code : "TOKENDANCE_ERROR",
+      `TokenDance request preparation failed; model=${request.model}; generation not submitted: ${failureMessage(error)}`);
+  }
+  return { route, model: request.model, body };
+}
+
+async function store(client: TokenDanceClient, urls: readonly string[], resources: ResourceStore): Promise<BlobRef[]> {
+  const blobs: BlobRef[] = [];
+  for (const url of urls) {
+    const downloaded = await client.download(url);
+    blobs.push(await resources.put(downloaded.bytes, downloaded.mediaType));
+  }
+  return blobs;
+}
+
+const paths = {
+  "ark-video": { submit: "/ark/v3/generations/tasks", task: (id: string) => `/ark/v3/generations/tasks/${encodeURIComponent(id)}` },
+  "minimax-video": { submit: "/minimax/v2/video_generation", task: (id: string) => `/minimax/v2/query/video_generation/${encodeURIComponent(id)}` },
+} as const;
+
+function taskId(protocol: keyof typeof paths, response: Record<string, unknown>): string {
+  const id = protocol === "ark-video" ? response.id : response.task_id;
+  assert(typeof id === "string" && id.length > 0, "TokenDance response has no task id");
+  return id;
+}
+
+/** Ark answers the task itself; MiniMax wraps it in `task`. */
+function taskBody(protocol: keyof typeof paths, response: Record<string, unknown>): Record<string, unknown> {
+  return protocol === "ark-video" ? response : object(response.task, "TokenDance task");
+}
+
+function taskVideoUrl(protocol: keyof typeof paths, task: Record<string, unknown>): string {
+  const content = object(task.content, "TokenDance task content");
+  return httpsUrl(protocol === "ark-video" ? content.video_url : content.url, "TokenDance task");
+}
+
+function endpoint(client: TokenDanceClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreateTokenDanceProviderOptions["publicAssetUrl"]): AsyncEndpoint {
+  return {
+    async start(context) {
+      try {
+        const { route, model, body } = await prepare(client, context, publicAssetUrl);
+        assert(route.protocol !== "ark-image", "TokenDance image capabilities use an immediate endpoint");
+        await context.reportProgress?.({ phase: `Submitting TokenDance request: ${model}` });
+        const response = await client.json(paths[route.protocol].submit, apiKey(context.credentials), {
+          method: "POST", headers: { "content-type": "application/json" }, body,
+        });
+        const handle: Handle = { contract: "hypit.tokendance-operation@1", taskId: taskId(route.protocol, response), route: route.key, startedAt: Date.now() };
+        const receipt = { id: handle.taskId };
+        await context.checkpoint?.({ handle: canonicalize(handle), receipt });
+        return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: "submitted" }), receipt };
+      } catch (error) {
+        return failure(error);
+      }
+    },
+    async poll(context) {
+      try {
+        const handle = object(context.handle, "TokenDance handle") as unknown as Handle;
+        const route = tokenDanceRouteForCapability(context.need.capability);
+        assert(route !== undefined && handle.contract === "hypit.tokendance-operation@1" && handle.route === route.key && route.protocol !== "ark-image", "TokenDance handle is invalid");
+        const receipt = { id: handle.taskId };
+        if (Date.now() - handle.startedAt > maxOperationMs) {
+          return { status: "failed", receipt, failure: { code: "TOKENDANCE_OPERATION_TIMEOUT", message: `TokenDance task ${handle.taskId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };
+        }
+        const task = taskBody(route.protocol, await client.json(paths[route.protocol].task(handle.taskId), apiKey(context.credentials)));
+        const status = String(task.status);
+        if (status === "queued" || status === "running") return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };
+        const rejected = tokenDanceTaskFailure(task, handle.taskId);
+        if (rejected !== undefined) return { ...failure(rejected), receipt };
+        assert(status === "succeeded", `TokenDance returned unknown task status ${status}`);
+        return { status: "ready", handle: canonicalize({ ...handle, url: taskVideoUrl(route.protocol, task) }), receipt };
+      } catch (error) {
+        return failure(error);
+      }
+    },
+    async collect(context) {
+      try {
+        const handle = object(context.handle, "TokenDance handle") as unknown as Handle;
+        const route = tokenDanceRouteForCapability(context.need.capability);
+        assert(route !== undefined && handle.route === route.key, "TokenDance collection route differs");
+        await context.reportProgress?.({ phase: "Receiving generated video" });
+        const blobs = await store(client, [httpsUrl(handle.url, "TokenDance handle")], context.resources);
+        return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.taskId } };
+      } catch (error) {
+        return failure(error);
+      }
+    },
+  };
+}
+
+export function createTokenDanceProvider(options: CreateTokenDanceProviderOptions = {}) {
+  const requestTimeoutMs = options.requestTimeoutMs ?? 300_000;
+  const operationTimeoutMs = options.operationTimeoutMs ?? 30 * 60_000;
+  for (const [name, value] of Object.entries({ requestTimeoutMs, operationTimeoutMs })) {
+    assert(Number.isSafeInteger(value) && value > 0, `TokenDance ${name} must be a positive integer`);
+  }
+  const client = new TokenDanceClient(apiBaseUrl(options.baseUrl ?? "https://tokendance.space/gateway"), requestTimeoutMs, options.fetch ?? globalThis.fetch);
+  const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, operationTimeoutMs, options.publicAssetUrl);
+  const imageEndpoint: ImmediateEndpointHandler = async (context) => {
+    const { route, model, body } = await prepare(client, context, options.publicAssetUrl);
+    assert(route.protocol === "ark-image", "TokenDance video capabilities use an asynchronous endpoint");
+    await context.reportProgress?.({ phase: `Submitting TokenDance request: ${model}` });
+    const response = await client.json("/ark/v3/images/generations", apiKey(context.credentials), {
+      method: "POST", headers: { "content-type": "application/json" }, body,
+    });
+    assert(Array.isArray(response.data) && response.data.length > 0, "TokenDance image response has no data");
+    const urls = response.data.map((item, index) => httpsUrl(object(item, `TokenDance image ${index + 1}`).url, `TokenDance image ${index + 1}`));
+    await context.reportProgress?.({ phase: "Receiving generated images" });
+    return { value: route.packageResult(await store(client, urls, context.resources)) };
+  };
+  return defineEndpointPackage({
+    module: tokenDanceProviderModuleRef, facet: "gateway", instance: options.instance ?? "tokendance.default", pool: options.pool ?? options.instance ?? "tokendance.default",
+    pricing: { kind: "page", url: "https://tokendance.space/models" },
+    credentials: { apiKey: options.apiKey ?? credentialRef("os", "tokendance.api-key") },
+    credentialInputs: { apiKey: { label: "TokenDance API key" } },
+    defaultConcurrency: options.defaultConcurrency ?? 4,
+    ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),
+    capabilities: tokenDanceRoutes.map((route) => route.protocol === "ark-image"
+      ? { capability: route.capability, returns: route.returns, lifecycle: "immediate" as const, handler: imageEndpoint, capacity: route.capability.name, supports: route.supports }
+      : { capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports }),
+  });
+}