Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat(providers): add TokenDance, HiAPI, Pollo and Monid gateway Providers (#282)
Sharky Wang6386639f2e85
diff --git a/docs/guide/providers.md b/docs/guide/providers.mdindex 7495c357..80a48770 100644--- a/docs/guide/providers.md+++ b/docs/guide/providers.md@@ -8,7 +8,8 @@ A **Provider** knows how to fulfill that request through a particular service. Aconfigured instance of that Provider, with its service address, credential reference and capacity.The Runtime Profile binds the requested capability to an Endpoint.-Hypit's official Distribution includes local Providers and the HypiHub Provider. Other services+Hypit's official Distribution includes local Providers, the HypiHub Provider, and API-key Providers+for TokenDance, HiAPI, Pollo and Monid that serve the installed models each service offers. Other servicesconnect through packages owned by the production or their authors. The Agent can implement a newservice through the public SDK, just as it can create a visual component for a video.[Model and deployment services](./service-partners.md) introduces independent partners through thatdiff --git a/docs/guide/service-partners.md b/docs/guide/service-partners.mdindex 72407b5e..6e157dcf 100644--- a/docs/guide/service-partners.md+++ b/docs/guide/service-partners.md@@ -11,22 +11,48 @@ work. Its Provider is maintained with Hypit. Local execution remains available tProviders, and users can connect their own services through project Providers.The services introduced below are independent partners. They have their own accounts, terms,-prices, model availability and APIs. A partnership is an introduction, not a shared HypiHub account-or an automatically installed integration. Choose a service for the work and connect its supported-capabilities through the ordinary [Model and Provider](./providers.md) extension path.+prices, model availability and APIs. A partnership is an introduction, not a shared HypiHub account.+The Distribution bundles an API-key Provider for each service named below; each Provider maps the+installed models that service offers and reports that service's input limits, and its README lists+both. A model the service offers beyond that set connects through the ordinary+[Model and Provider](./providers.md) extension path.## Model and tool API partners+### TokenDance++[TokenDance](https://tokendance.space) is a multi-model gateway.+[`@hypit/provider-tokendance`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-tokendance/README.md)+serves the Seedance 2.0 and 2.5 models, Seedream 5.0 lite and MiniMax H3 through the Ark and+MiniMax protocols TokenDance documents. Its+[documentation index](https://tokendance.space/llms.txt) and live model catalogue supply the+details of other models.++### HiAPI++[HiAPI](https://www.hiapi.ai) offers image, video and audio models through one asynchronous task+API. [`@hypit/provider-hiapi`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-hiapi/README.md)+serves the Seedance, Seedream 5.0 lite, MiniMax H3, GPT Image 2, Nano Banana and Grok Imagine+models the Distribution describes. Its [model index](https://www.hiapi.ai/docs/models.json) lists+the rest.++### Pollo++[Pollo AI](https://docs.pollo.ai) offers video and image models through per-model generation+paths. [`@hypit/provider-pollo`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-pollo/README.md)+serves MiniMax H3, Grok Imagine 1.5, GPT Image 2 and Nano Banana. Pollo takes reference media by+public URL only, so a request with reference media needs a URL the embedding caller supplies.+### Monid[Monid](https://monid.ai) is a Hypit service partner.-[Its documentation](https://docs.monid.ai/) describes discovering tools, inspecting their inputs and-prices, and calling them through its interfaces. For a video production, identify the concrete-image, video, audio or other tool that meets the material requirement. Its-[HTTP API documentation](https://docs.monid.ai/api/overview.html) supplies the connection details.-An installed compatible Provider can be reused; otherwise the Agent can implement the required-request and result mapping in a project package. Availability of a tool does not itself install-a Hypit Provider for it.+[Its documentation](https://monid.ai/docs) describes discovering tools, inspecting their inputs and+prices, and calling them through its interfaces.+[`@hypit/provider-monid`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-monid/README.md)+serves the Seedance 2.0 and 2.5 endpoints and uploads reference media through Monid's workspace+file system. For another Monid tool, its+[HTTP API documentation](https://monid.ai/docs/api/overview) supplies the connection details, and+the Agent can implement the required request and result mapping in a project package.## Your own model deploymentdiff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.mdindex 7e77517e..f91a2a72 100644--- a/docs/quickstart/generation.md+++ b/docs/quickstart/generation.md@@ -152,7 +152,8 @@ On an image or video reference, `person-reference="true"` declares a person/avatmaterial, including a generated human likeness. Use false for a reference without that content;omission leaves the classification unspecified. Audio references do not use this visual flag.Frame mode provides `first-frame-person-reference` and `last-frame-person-reference`. The selected-Provider carries this fact through the service's media preparation.+Provider carries this fact through the service's media preparation; a service without such a field+accepts the declaration without transmitting it.A video reference can guide dance, physical action or camera movement while images guide the newappearance. Choose an excerpt that carries the intended motion within the selected model anddiff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.mdindex cbdf75c7..18a7c165 100644--- a/docs/zh/guide/providers.md+++ b/docs/zh/guide/providers.md@@ -5,7 +5,7 @@ description: 选择账户、连接服务或添加模型,沿用同一套视频**Model** 定义要生成什么:输入、支持的参数和输出类型。**Provider** 知道如何通过某个服务完成这个请求。**Endpoint** 是配置好的 Provider 实例,包含服务地址、凭据引用和容量。Runtime Profile 将所需能力绑定到 Endpoint。-官方发行包含本地 Provider 和 HypiHub Provider。其他服务通过项目或作者自己的包接入;Agent 可以使用公开 SDK 编写所需接入,就像为视频创建视觉组件。[模型与部署服务](./service-partners.md) 集中介绍独立合作服务,它们沿用同一套扩展方式。选择执行服务,与[选择 Agent 工作环境](./agents.md)是两件事。+官方发行包含本地 Provider、HypiHub Provider,以及 TokenDance、HiAPI、Pollo、Monid 四个使用 API Key 的 Provider,各自覆盖该服务提供的已安装模型。其他服务通过项目或作者自己的包接入;Agent 可以使用公开 SDK 编写所需接入,就像为视频创建视觉组件。[模型与部署服务](./service-partners.md) 集中介绍独立合作服务,它们沿用同一套扩展方式。选择执行服务,与[选择 Agent 工作环境](./agents.md)是两件事。HypiHub 是我们推荐的集成托管服务。**BYOK** 指使用自己账户的 API Key:Key 通过兼容的 Provider 连接到签发它的服务。告诉 Agent 你已有哪个服务及其 API 文档,具体接线和项目包可以由 Agent 完成。Key 负责授权请求,本身不会实现 API 接口。一个项目可以为不同能力使用不同服务,分别使用各自的账户并按各自规则计费。diff --git a/docs/zh/guide/service-partners.md b/docs/zh/guide/service-partners.mdindex 84301d46..1e435069 100644--- a/docs/zh/guide/service-partners.md+++ b/docs/zh/guide/service-partners.md@@ -9,19 +9,42 @@ HypiHub 是 Hypit 推荐的集成托管服务,提供已支持的生成与 Whis维护。本地能力仍可通过本地 Provider 使用,用户自己的服务通过项目 Provider 接入。下面介绍的合作方是独立服务,各有自己的账户、条款、价格、模型可用性和 API。-合作关系提供一个了解服务的入口,不共用 HypiHub 账户,也不意味着已经自动安装了适配。-根据当前作品选择服务,通过普通的 [Model 与 Provider](./providers.md) 扩展方式连接所需能力。+合作关系提供一个了解服务的入口,不共用 HypiHub 账户。+发行包为下面每个服务内置了一个使用 API Key 的 Provider,覆盖该服务提供的已安装模型,+并按该服务的输入限制报告不支持的请求;具体清单见各 Provider 的 README。+服务提供、但不在这个范围内的模型,通过普通的 [Model 与 Provider](./providers.md) 扩展方式连接。## 模型与工具 API 合作方+### TokenDance++[TokenDance](https://tokendance.space) 是多模型网关。+[`@hypit/provider-tokendance`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-tokendance/README.md)+按 TokenDance 文档中的方舟与 MiniMax 协议提供 Seedance 2.0、2.5 系列、Seedream 5.0 lite 和 MiniMax H3。+其他模型见它的[文档索引](https://tokendance.space/llms.txt)和实时模型目录。++### HiAPI++[HiAPI](https://www.hiapi.ai) 通过一个异步任务接口提供图片、视频和音频模型。+[`@hypit/provider-hiapi`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-hiapi/README.md)+提供发行包已描述的 Seedance、Seedream 5.0 lite、MiniMax H3、GPT Image 2、Nano Banana 和 Grok Imagine 模型。+其余模型见它的[模型索引](https://www.hiapi.ai/docs/models.json)。++### Pollo++[Pollo AI](https://docs.pollo.ai) 按模型路径提供视频和图片生成。+[`@hypit/provider-pollo`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-pollo/README.md)+提供 MiniMax H3、Grok Imagine 1.5、GPT Image 2 和 Nano Banana。+Pollo 只接受公网 URL 形式的参考素材,带参考素材的请求需要由嵌入方提供 URL。+### Monid[Monid](https://monid.ai) 是 Hypit 的服务合作方。-[它的文档](https://docs.monid.ai/)介绍了工具发现、输入与价格查询,以及调用方式。-制作视频时,根据具体素材需要找到合适的图片、视频、音频或其他工具,-[HTTP API 文档](https://docs.monid.ai/api/overview.html)提供接入依据。-已有兼容 Provider 可以复用;缺少时,Agent 可以在项目包中实现这次所需的请求与结果映射。-服务里存在某个工具,并不意味着项目已经安装了对应的 Hypit Provider。+[它的文档](https://monid.ai/docs)介绍了工具发现、输入与价格查询,以及调用方式。+[`@hypit/provider-monid`](https://github.com/hypit-ai/hypit/blob/main/packages/provider-monid/README.md)+提供 Seedance 2.0、2.5 系列端点,并通过 Monid 的工作区文件系统上传参考素材。+使用 Monid 的其他工具时,[HTTP API 文档](https://monid.ai/docs/api/overview)提供接入依据,+Agent 可以在项目包中实现这次所需的请求与结果映射。## 自己部署模型diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.mdindex 0adde651..6bd141be 100644--- a/docs/zh/quickstart/generation.md+++ b/docs/zh/quickstart/generation.md@@ -136,7 +136,7 @@ Seedance 2.5 复用同样的 Surface,而不是由 Runtime 把别的模型偷图片或视频参考上的 `person-reference="true"` 声明素材中含有人物/数字人形象,AI 生成的人像也适用。没有这类内容时可写 false;省略表示没有提供分类。音频参考不使用这个视觉标记。首尾帧模式提供 `first-frame-person-reference` 和 `last-frame-person-reference`。-选定的 Provider 负责把这项事实交给服务的素材准备流程。+选定的 Provider 负责把这项事实交给服务的素材准备流程;服务 API 没有对应字段时,Provider 接受这项声明但不传输。舞蹈、身体动作或运镜可以由参考视频提供运动依据,再用参考图指定新的形象与场景。围绕需要保留的动作选取片段,并核对模型与服务的参考视频时长上限;它和要生成的视频时长是两回事。diff --git a/package.json b/package.jsonindex 3e406c72..53a58d4e 100644--- a/package.json+++ b/package.json@@ -236,9 +236,13 @@"@hypit/project-context-node": "workspace:*","@hypit/protocol": "workspace:*","@hypit/provider-hyperframes-local": "workspace:*",+ "@hypit/provider-hiapi": "workspace:*","@hypit/provider-hypihub": "workspace:*","@hypit/provider-image-opencv-local": "workspace:*","@hypit/provider-media-local": "workspace:*",+ "@hypit/provider-monid": "workspace:*",+ "@hypit/provider-pollo": "workspace:*",+ "@hypit/provider-tokendance": "workspace:*","@hypit/provider-whisperx-local": "workspace:*","@hypit/ranking": "workspace:*","@hypit/ranking-studio": "workspace:*",diff --git a/packages/provider-hiapi/README.md b/packages/provider-hiapi/README.mdnew file mode 100644index 00000000..75420acc--- /dev/null+++ b/packages/provider-hiapi/README.md@@ -0,0 +1,75 @@+# `@hypit/provider-hiapi`++Hypit Runtime Provider for a [HiAPI](https://www.hiapi.ai) account. Every capability submits one+task to `POST /v1/tasks` with the model's documented `input` fields, polls+`GET /v1/tasks/{taskId}` until the task is terminal, downloads `data.output[].url` and stores the+files in the current Build. Submission carries an `Idempotency-Key`, so a retried submission returns+the original task.++| Capability | HiAPI model |+| --- | --- |+| `@hypit/seedance@1#seedance-2` | `seedance-2.0` |+| `@hypit/seedance@1#seedance-2-fast` | `seedance-2.0-fast` |+| `@hypit/seedance@1#seedance-2-mini` | `seedance-2.0-mini` |+| `@hypit/seedance@1#seedance-2.5` | `seedance-2.5/reference-to-video` with a reference video, `seedance-2.5/image-to-video` with frames, reference images or reference audio, otherwise `seedance-2.5/text-to-video` |+| `@hypit/seedream@1#seedream-5-lite` | `seedream-5.0-lite/image-to-image` with references, otherwise `seedream-5.0-lite/text-to-image` |+| `@hypit/minimax-h3@1#minimax-h3` | `minimax-h3` |+| `@hypit/gpt-image@1#gpt-image-2` | `gpt-image-2/image-to-image` with references, otherwise `gpt-image-2/text-to-image` |+| `@hypit/nano-banana@1#nano-banana-2` | `Nano-Banana-2` |+| `@hypit/nano-banana@1#nano-banana-pro` | `Nano-Banana-Pro` |+| `@hypit/grok-imagine@1#grok-imagine-video` | `grok-imagine/image-to-video` with images, otherwise `grok-imagine/text-to-video` |+| `@hypit/grok-imagine@1#grok-imagine-video-1.5-preview` | `grok-imagine-1.5/image-to-video` |++HiAPI's model index at `https://www.hiapi.ai/docs/models.json` lists further models and routes;+this Provider maps only the models the Distribution already describes, on each model's standard+route.++Service limits this Provider reports as unsupported before submitting:++- `seedance-2.0-mini` has no `web_search` field; `web-search="true"` is unsupported there.+- `seedance-2.5/image-to-video` takes only `aspect-ratio="adaptive"`; `text-to-video` and+ `image-to-video` render 720p or 1080p, `reference-to-video` also 480p.+- Seedream 5.0 lite renders 2K (`quality="basic"`) or 4K (`quality="ultra"`); `high` (3K) is+ unsupported. `output-format` and `nsfw-check` have no HiAPI field and are not sent.+- `minimax-h3` renders 2K only and accepts up to five reference images; requests send+ `watermark: false`.+- GPT Image 2: `background` only at 1K; `auto` ratio only at 1K; 2K excludes `5:4`, `4:5`, `3:1`,+ `1:3`, `9:21`; 4K excludes `1:1`, `3:1`, `1:3`, `9:21`; image-to-image takes up to six references.+- Grok Imagine renders 480p or 720p; `grok-imagine-1.5/image-to-video` animates exactly one image.++Seedance visual references may carry `person-reference`; the Provider accepts the declaration and+transmits nothing for it, since HiAPI has no field for it. Seedance rejects reference images and+videos that contain a real human face; HiAPI offers no way to register authorized portrait material,+so such a request fails with the service's moderation error.++Reference images and audio travel inline as `data:` URLs, which HiAPI documents for its Seedance+inputs, within the per-file sizes each model page states: 30 MB images and 15 MB audio for+`seedance-2.0-mini` and the Seedance 2.5 models (2.5 also caps combined images at 120 MB), 10 MB+images for `seedream-5.0-lite/image-to-image` and `grok-imagine/image-to-video`, 20 MB for+`grok-imagine-1.5/image-to-video`, 30 MB for `Nano-Banana-Pro`. The Provider checks these before+submitting. A reference video must be a public HTTPS URL; configure `publicAssetUrl` when embedding+the Provider, otherwise such a request fails before submission.++Runtime Profile example:++```json+{+ "endpoints": {+ "hiapi.default": {+ "use": "@hypit/provider-hiapi",+ "pool": "hiapi.default",+ "config": {+ "apiKey": { "store": "platform", "key": "hiapi.api-key" },+ "defaultConcurrency": 3,+ "pollIntervalMs": 10000+ }+ }+ }+}+```++`baseUrl` defaults to `https://api.hiapi.ai`. Store the API key with+`hypit auth login hiapi.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote task and action+concurrency. HTTP failures keep HiAPI's `error_code` and message; failed tasks keep+`data.error.code` and message, with any signed URL in the message redacted.diff --git a/packages/provider-hiapi/package.json b/packages/provider-hiapi/package.jsonnew file mode 100644index 00000000..80dbd109--- /dev/null+++ b/packages/provider-hiapi/package.json@@ -0,0 +1,24 @@+{+ "name": "@hypit/provider-hiapi",+ "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/gpt-image": "workspace:*",+ "@hypit/grok-imagine": "workspace:*",+ "@hypit/minimax-h3": "workspace:*",+ "@hypit/nano-banana": "workspace:*",+ "@hypit/seedance": "workspace:*",+ "@hypit/seedream": "workspace:*"+ }+}diff --git a/packages/provider-hiapi/src/activation.ts b/packages/provider-hiapi/src/activation.tsnew file mode 100644index 00000000..61814ddc--- /dev/null+++ b/packages/provider-hiapi/src/activation.ts@@ -0,0 +1,62 @@+import {+ createRuntimeEndpointAdapterFacet,+ runtimeConfigCredentialRef,+ runtimeConfigActionLimits,+ runtimeConfigExact,+ runtimeConfigObject,+ runtimeConfigPositiveInteger,+ runtimeConfigString,+} from "@hypit/runtime-kit";++import { createHiApiProvider } from "./provider.js";++const adapter = createRuntimeEndpointAdapterFacet({+ use: "@hypit/provider-hiapi",+ activate(context) {+ if (context.pool === undefined) throw new Error("HiAPI Provider Pool is required");+ const config = runtimeConfigObject(context.config, "HiAPI");+ runtimeConfigExact(config, [+ "baseUrl",+ "apiKey",+ "defaultConcurrency",+ "actionLimits",+ "pollIntervalMs",+ "requestTimeoutMs",+ "operationTimeoutMs",+ ], "HiAPI");+ const baseUrl = runtimeConfigString(config.baseUrl, "HiAPI 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("HiAPI baseUrl must use HTTPS or loopback");+ }+ }+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "HiAPI apiKey");+ if (apiKey === undefined) throw new Error("HiAPI apiKey CredentialRef is required");+ const actionLimits = runtimeConfigActionLimits(config.actionLimits);+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HiAPI defaultConcurrency");+ const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "HiAPI pollIntervalMs");+ const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "HiAPI requestTimeoutMs");+ const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "HiAPI operationTimeoutMs");+ return {+ endpoint: createHiApiProvider({+ 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;diff --git a/packages/provider-hiapi/src/errors.ts b/packages/provider-hiapi/src/errors.tsnew file mode 100644index 00000000..0e32e849--- /dev/null+++ b/packages/provider-hiapi/src/errors.ts@@ -0,0 +1,44 @@+/** HiAPI's `{ code, message, error_code }` envelope and task `error` object, kept at the service boundary. */+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 safeHiApiReason(value: string): string {+ return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");+}++export class HiApiServiceError extends Error {+ constructor(readonly code: string, message: string) { super(message); }+}++export class HiApiHttpError extends HiApiServiceError {+ 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 code = text(body?.error_code) ?? "HIAPI_HTTP_ERROR";+ const reason = text(body?.message) ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);+ const requestId = text(response.headers.get("x-request-id"));+ const facts = [+ `HiAPI HTTP ${status}`, code, `${request.method} ${request.path}`,+ ...(request.model === undefined ? [] : [`model=${request.model}`]),+ ...(requestId === undefined ? [] : [`request=${requestId}`]),+ ];+ super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safeHiApiReason(reason)}`}`);+ }+}++/** A terminal `fail` task; `undefined` otherwise. */+export function hiApiTaskFailure(task: Record<string, unknown>, id: string): HiApiServiceError | undefined {+ if (task.status !== "fail") return undefined;+ const error = record(task.error);+ const code = text(error?.code) ?? "HIAPI_TASK_FAILED";+ const reason = text(error?.message);+ return new HiApiServiceError(code,+ `HiAPI task ${id} failed; ${code}${reason === undefined ? "" : `: ${safeHiApiReason(reason)}`}`);+}diff --git a/packages/provider-hiapi/src/index.ts b/packages/provider-hiapi/src/index.tsnew file mode 100644index 00000000..858cd7de--- /dev/null+++ b/packages/provider-hiapi/src/index.ts@@ -0,0 +1,2 @@+export { createHiApiProvider, hiApiProviderModuleRef } from "./provider.js";+export type { CreateHiApiProviderOptions } from "./provider.js";diff --git a/packages/provider-hiapi/src/mapping.ts b/packages/provider-hiapi/src/mapping.tsnew file mode 100644index 00000000..d4393b0d--- /dev/null+++ b/packages/provider-hiapi/src/mapping.ts@@ -0,0 +1,129 @@+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" };+const GPT_IMAGE: ModuleRef = { name: "@hypit/gpt-image", version: "1" };+const NANO_BANANA: ModuleRef = { name: "@hypit/nano-banana", version: "1" };+const GROK: ModuleRef = { name: "@hypit/grok-imagine", version: "1" };++/**+ * HiAPI model IDs and the `input` fields each documents. A model whose HiAPI ID depends on the+ * request shape (text, frames or references) lists one route per shape; the first route whose+ * ports are present wins. `personReference` is accepted on Seedance visual references and not+ * transmitted: HiAPI has no field for it.+ */+const seedanceFields = {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ duration: { as: "value", field: "duration" },+ resolution: { as: "value", field: "resolution" },+ firstFrame: { as: "url", field: "first_frame_url", resourceFields: ["personReference"] },+ lastFrame: { as: "url", field: "last_frame_url", resourceFields: ["personReference"] },+ referenceImage: { as: "urlArray", field: "reference_image_urls", resourceFields: ["personReference"] },+ referenceVideo: { as: "urlArray", field: "reference_video_urls", resourceFields: ["personReference"] },+ referenceAudio: { as: "urlArray", field: "reference_audio_urls" },+ generateAudio: { as: "value", field: "generate_audio" },+ webSearch: { as: "value", field: "web_search" },+} as const satisfies GenerationWireMapping["fields"];++const seedance2 = (name: string, model: string): GenerationWireMapping => ({+ capability: { module: SEEDANCE, name }, result: "video", routes: [{ model }], fields: seedanceFields,+});++export const hiApiMappings: readonly GenerationWireMapping[] = [+ seedance2("seedance-2", "seedance-2.0"),+ seedance2("seedance-2-fast", "seedance-2.0-fast"),+ seedance2("seedance-2-mini", "seedance-2.0-mini"),+ {+ capability: { module: SEEDANCE, name: "seedance-2.5" }, result: "video",+ routes: [+ { model: "seedance-2.5/reference-to-video", whenPresent: ["referenceVideo"] },+ { model: "seedance-2.5/image-to-video", whenPresent: ["firstFrame"] },+ { model: "seedance-2.5/image-to-video", whenPresent: ["referenceImage"] },+ { model: "seedance-2.5/image-to-video", whenPresent: ["referenceAudio"] },+ { model: "seedance-2.5/text-to-video" },+ ],+ fields: seedanceFields,+ },+ {+ capability: { module: SEEDREAM, name: "seedream-5-lite" }, result: "image",+ routes: [+ { model: "seedream-5.0-lite/image-to-image", whenPresent: ["images"] },+ { model: "seedream-5.0-lite/text-to-image" },+ ],+ 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_urls" },+ },+ },+ {+ capability: { module: MINIMAX, name: "minimax-h3" }, result: "video", routes: [{ model: "minimax-h3" }],+ constants: { watermark: false },+ fields: {+ prompt: { as: "value", field: "prompt" },+ duration: { as: "value", field: "duration" },+ resolution: { as: "value", field: "resolution" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ firstFrame: { as: "url", field: "first_frame_image" },+ lastFrame: { as: "url", field: "last_frame_image" },+ referenceImage: { as: "urlArray", field: "image_urls" },+ referenceVideo: { as: "urlArray", field: "video_urls" },+ referenceAudio: { as: "urlArray", field: "audio_urls" },+ },+ },+ {+ capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image",+ routes: [+ { model: "gpt-image-2/image-to-image", whenPresent: ["images"] },+ { model: "gpt-image-2/text-to-image" },+ ],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ background: { as: "value", field: "background" },+ images: { as: "urlArray", field: "input_urls" },+ },+ },+ ...([["nano-banana-2", "Nano-Banana-2"], ["nano-banana-pro", "Nano-Banana-Pro"]] as const).map(([name, model]): GenerationWireMapping => ({+ capability: { module: NANO_BANANA, name }, result: "image", routes: [{ model }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ images: { as: "urlArray", field: "image_input" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ outputFormat: { as: "value", field: "output_format" },+ },+ })),+ {+ capability: { module: GROK, name: "grok-imagine-video" }, result: "video",+ routes: [+ { model: "grok-imagine/image-to-video", whenPresent: ["images"] },+ { model: "grok-imagine/text-to-video" },+ ],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ duration: { as: "value", field: "duration" },+ images: { as: "urlArray", field: "image_urls" },+ },+ },+ {+ capability: { module: GROK, name: "grok-imagine-video-1.5-preview" }, result: "video",+ routes: [{ model: "grok-imagine-1.5/image-to-video" }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ duration: { as: "value", field: "duration" },+ images: { as: "urlArray", field: "image_urls" },+ },+ },+];diff --git a/packages/provider-hiapi/src/provider.ts b/packages/provider-hiapi/src/provider.tsnew file mode 100644index 00000000..c9870473--- /dev/null+++ b/packages/provider-hiapi/src/provider.ts@@ -0,0 +1,215 @@+import { requestDeadline } from "@hypit/runtime-kit";+import type { AsyncEndpoint, EndpointCredential, EndpointInvocationContext, EndpointOutcome } 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 { hiApiRouteForCapability, hiApiRoutes } from "./routes.js";+import type { HiApiMediaLimits } from "./routes.js";+import { HiApiHttpError, HiApiServiceError, hiApiTaskFailure } from "./errors.js";++export const hiApiProviderModuleRef = { name: "@hypit/provider-hiapi", version: "1" } as const;++export type CreateHiApiProviderOptions = {+ 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.hiapi-operation@1";+ readonly taskId: string;+ readonly route: string;+ readonly startedAt: number;+ readonly urls?: readonly 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, "HiAPI 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, "HiAPI apiKey credential is unavailable; store a HiAPI 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 HiApiServiceError ? error.code : "HIAPI_ERROR", message: failureMessage(error) } };+}++class HiApiClient {+ 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 HiApiHttpError(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(`HiAPI returned invalid JSON (${response.status})`); }+ return object(object(body, "HiAPI response").data, "HiAPI response data");+ } finally { deadline.finish(); }+ }+ 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(`HiAPI 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 resolverFor(limits: HiApiMediaLimits, context: EndpointInvocationContext, publicAssetUrl: CreateHiApiProviderOptions["publicAssetUrl"]): GenerationArtifactUrlResolver {+ const resolved = new Map<string, Promise<string>>();+ let imageBytes = 0;+ 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);+ // HiAPI documents data URLs for image and audio inputs; reference videos must be public HTTPS URLs.+ const kind = artifact.mediaType.split("/", 1)[0];+ assert(kind === "image" || kind === "audio",+ `HiAPI accepts ${artifact.mediaType} references only by public URL; configure publicAssetUrl for this Endpoint`);+ const limit = limits[kind];+ assert(limit === undefined || artifact.size <= limit,+ `HiAPI accepts ${kind} references up to ${(limit ?? 0) / 1_000_000} MB for this model; ${artifact.resource} is ${artifact.size} bytes`);+ if (kind === "image") {+ imageBytes += artifact.size;+ assert(limits.imagesTotal === undefined || imageBytes <= limits.imagesTotal,+ `HiAPI accepts reference images up to ${(limits.imagesTotal ?? 0) / 1_000_000} MB combined for this model`);+ }+ const bytes = await context.resources.get(artifact.resource);+ assert(bytes !== undefined && bytes.byteLength === artifact.size, `Reference Resource ${artifact.resource} is unavailable or has changed`);+ return `data:${artifact.mediaType};base64,${Buffer.from(bytes).toString("base64")}`;+ })();+ resolved.set(artifact.resource, promise);+ return promise;+ };+}++function endpoint(client: HiApiClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreateHiApiProviderOptions["publicAssetUrl"]): AsyncEndpoint {+ return {+ async start(context) {+ try {+ const route = hiApiRouteForCapability(context.need.capability);+ assert(route !== undefined, "HiAPI does not implement this exact capability");+ const request = route.prepare(context.need.constraints);+ await context.reportProgress?.({ phase: `Preparing HiAPI request: ${request.model}` });+ let body: Record<string, unknown>;+ try {+ body = await request.compile(resolverFor(request.mediaLimits, context, publicAssetUrl));+ } catch (error) {+ throw new HiApiServiceError(error instanceof HiApiServiceError ? error.code : "HIAPI_ERROR",+ `HiAPI request preparation failed; model=${request.model}; generation not submitted: ${failureMessage(error)}`);+ }+ await context.reportProgress?.({ phase: `Submitting HiAPI request: ${request.model}` });+ const response = await client.json("/v1/tasks", apiKey(context.credentials), {+ method: "POST", headers: { "content-type": "application/json", "idempotency-key": context.operation }, body: JSON.stringify(body),+ });+ assert(typeof response.taskId === "string" && response.taskId.length > 0, "HiAPI response has no taskId");+ const handle: Handle = { contract: "hypit.hiapi-operation@1", taskId: response.taskId, 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, "HiAPI handle") as unknown as Handle;+ const route = hiApiRouteForCapability(context.need.capability);+ assert(route !== undefined && handle.contract === "hypit.hiapi-operation@1" && handle.route === route.key, "HiAPI handle is invalid");+ const receipt = { id: handle.taskId };+ if (Date.now() - handle.startedAt > maxOperationMs) {+ return { status: "failed", receipt, failure: { code: "HIAPI_OPERATION_TIMEOUT", message: `HiAPI task ${handle.taskId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };+ }+ const task = await client.json(`/v1/tasks/${encodeURIComponent(handle.taskId)}`, apiKey(context.credentials));+ const status = String(task.status);+ if (status === "queued" || status === "handling" || status === "archiving") {+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };+ }+ const rejected = hiApiTaskFailure(task, handle.taskId);+ if (rejected !== undefined) return { ...failure(rejected), receipt };+ assert(status === "success", `HiAPI returned unknown task status ${status}`);+ assert(Array.isArray(task.output) && task.output.length > 0, "HiAPI task succeeded without output");+ const urls = task.output.map((item, index) => {+ const url = object(item, `HiAPI output ${index + 1}`).url;+ assert(typeof url === "string" && /^https?:\/\//u.test(url), `HiAPI output ${index + 1} has no URL`);+ return url;+ });+ return { status: "ready", handle: canonicalize({ ...handle, urls }), receipt };+ } catch (error) {+ return failure(error);+ }+ },+ async collect(context) {+ try {+ const handle = object(context.handle, "HiAPI handle") as unknown as Handle;+ const route = hiApiRouteForCapability(context.need.capability);+ assert(route !== undefined && handle.route === route.key && Array.isArray(handle.urls), "HiAPI collection route differs");+ await context.reportProgress?.({ phase: "Receiving generated files" });+ const blobs: BlobRef[] = [];+ for (const url of handle.urls) {+ const downloaded = await client.download(url);+ blobs.push(await context.resources.put(downloaded.bytes, downloaded.mediaType));+ }+ return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.taskId } };+ } catch (error) {+ return failure(error);+ }+ },+ };+}++export function createHiApiProvider(options: CreateHiApiProviderOptions = {}) {+ 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, `HiAPI ${name} must be a positive integer`);+ }+ const client = new HiApiClient(apiBaseUrl(options.baseUrl ?? "https://api.hiapi.ai"), requestTimeoutMs, options.fetch ?? globalThis.fetch);+ const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, operationTimeoutMs, options.publicAssetUrl);+ return defineEndpointPackage({+ module: hiApiProviderModuleRef, facet: "gateway", instance: options.instance ?? "hiapi.default", pool: options.pool ?? options.instance ?? "hiapi.default",+ pricing: { kind: "page", url: "https://www.hiapi.ai/en/pricing" },+ credentials: { apiKey: options.apiKey ?? credentialRef("os", "hiapi.api-key") },+ credentialInputs: { apiKey: { label: "HiAPI API key" } },+ defaultConcurrency: options.defaultConcurrency ?? 4,+ ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),+ capabilities: hiApiRoutes.map((route) => ({+ capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports,+ })),+ });+}diff --git a/packages/provider-hiapi/src/routes.ts b/packages/provider-hiapi/src/routes.tsnew file mode 100644index 00000000..ae65b4e7--- /dev/null+++ b/packages/provider-hiapi/src/routes.ts@@ -0,0 +1,154 @@+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 { hiApiMappings } from "./mapping.js";++/** Documented byte limits for inline media on one HiAPI model; an absent kind carries no documented cap. */+export type HiApiMediaLimits = {+ readonly image?: number;+ readonly audio?: number;+ /** Documented cap on the combined size of all reference images. */+ readonly imagesTotal?: number;+};++const MB = 1_000_000;++/** Per-file sizes HiAPI's model pages state for images and audio; videos travel by public URL. */+const hiApiMediaLimits: Readonly<Record<string, HiApiMediaLimits>> = {+ "seedance-2.0-mini": { image: 30 * MB, audio: 15 * MB },+ "seedance-2.5/image-to-video": { image: 30 * MB, audio: 15 * MB, imagesTotal: 120 * MB },+ "seedance-2.5/reference-to-video": { image: 30 * MB, audio: 15 * MB, imagesTotal: 120 * MB },+ "seedream-5.0-lite/image-to-image": { image: 10 * MB },+ "Nano-Banana-Pro": { image: 30 * MB },+ "grok-imagine/image-to-video": { image: 10 * MB },+ "grok-imagine-1.5/image-to-video": { image: 20 * MB },+};++export type HiApiPreparedRequest = {+ readonly model: string;+ readonly mediaLimits: HiApiMediaLimits;+ readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;+};++export type HiApiRoute = GenerationWireMapping & {+ readonly key: string;+ readonly returns: TypeRef;+ readonly supports: (request: EndpointRequest) => EndpointSupport;+ readonly prepare: (constraints: CanonicalValue) => HiApiPreparedRequest;+ 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;+}++const SEEDREAM_RESOLUTION: Readonly<Record<string, string>> = { basic: "2K", ultra: "4K" };+const GPT_IMAGE_UNAVAILABLE: Readonly<Record<string, readonly string[]>> = {+ "2K": ["5:4", "4:5", "3:1", "1:3", "9:21"],+ "4K": ["1:1", "3:1", "1:3", "9:21"],+};++/** HiAPI'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");+ const resolution = scalar(request, "resolution");+ let model: string;+ try { model = selectWireModelForRequest(mapping, request); } catch (error) { return error instanceof Error ? error.message : String(error); }+ if (name === "seedance-2-mini" && scalar(request, "webSearch") === true) {+ return "HiAPI seedance-2.0-mini has no web_search field";+ }+ if (name === "seedance-2.5") {+ if (model === "seedance-2.5/image-to-video" && ratio !== "adaptive") {+ return `HiAPI ${model} takes only aspect-ratio adaptive, not ${String(ratio)}`;+ }+ if (model !== "seedance-2.5/reference-to-video" && resolution === "480p") {+ return `HiAPI ${model} renders 720p or 1080p, not 480p`;+ }+ }+ if (name === "seedream-5-lite" && SEEDREAM_RESOLUTION[String(scalar(request, "quality"))] === undefined) {+ return `HiAPI Seedream 5.0 lite renders 2K (basic) or 4K (ultra), not quality ${String(scalar(request, "quality"))}`;+ }+ if (name === "minimax-h3") {+ if (resolution !== undefined && resolution !== "2K") return `HiAPI minimax-h3 renders 2K only, not ${String(resolution)}`;+ if (count(request, "referenceImage") > 5) return "HiAPI minimax-h3 accepts up to five reference images";+ }+ if (name === "gpt-image-2") {+ if (count(request, "images") > 6) return "HiAPI gpt-image-2/image-to-image accepts up to six reference images";+ if (scalar(request, "background") !== undefined && resolution !== "1K") return `HiAPI GPT Image 2 accepts background only at 1K; omit it at ${String(resolution)}`;+ if (ratio === "auto" && resolution !== "1K") return "HiAPI GPT Image 2 renders aspect-ratio auto only at 1K";+ if (GPT_IMAGE_UNAVAILABLE[String(resolution)]?.includes(String(ratio))) return `HiAPI GPT Image 2 does not render ${String(ratio)} at ${String(resolution)}`;+ }+ if (mapping.capability.module.name === "@hypit/grok-imagine") {+ if (resolution === "1080p") return `HiAPI ${model} renders 480p or 720p, not 1080p`;+ if (name === "grok-imagine-video-1.5-preview" && count(request, "images") !== 1) {+ return "HiAPI grok-imagine-1.5/image-to-video animates exactly one image";+ }+ }+ return undefined;+}++/** Fields the model package requires that HiAPI names differently or does not take. */+function normalize(mapping: GenerationWireMapping, input: Record<string, unknown>): Record<string, unknown> {+ const { name } = mapping.capability;+ if (name === "seedance-2-mini" && input.web_search === false) delete input.web_search;+ if (name === "seedream-5-lite") {+ input.resolution = SEEDREAM_RESOLUTION[String(input.quality)];+ delete input.quality;+ delete input.output_format;+ delete input.nsfw_check;+ }+ return input;+}++function capabilityKey(capability: CapabilityRef): string {+ return `${capability.module.name}@${capability.module.version}#${capability.name}`;+}++export const hiApiRoutes: readonly HiApiRoute[] = hiApiMappings.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);+ const model = selectWireModelForRequest(mapping, request);+ return {+ model,+ mediaLimits: hiApiMediaLimits[model] ?? {},+ compile: async (resolve) => ({+ model,+ 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(hiApiRoutes.map((route) => [route.key, route]));++export function hiApiRouteForCapability(capability: CapabilityRef): HiApiRoute | undefined {+ return byCapability.get(capabilityKey(capability));+}diff --git a/packages/provider-hiapi/test/routes.test.ts b/packages/provider-hiapi/test/routes.test.tsnew file mode 100644index 00000000..e7b89c71--- /dev/null+++ b/packages/provider-hiapi/test/routes.test.ts@@ -0,0 +1,68 @@+import assert from "node:assert/strict";+import test from "node:test";+import { assertMappingCoversPorts } from "@hypit/generation";+import type { BlobRef, CanonicalValue } from "@hypit/protocol";+import { gptImage2Ports, sealGptImage2Request } from "@hypit/gpt-image";+import { grokImaginePorts } from "@hypit/grok-imagine";+import { minimaxH3Ports } from "@hypit/minimax-h3";+import { nanoBananaPorts } from "@hypit/nano-banana";+import { seedancePorts, sealSeedanceRequest } from "@hypit/seedance";+import { seedream5LitePorts, sealSeedreamRequest } from "@hypit/seedream";++import { hiApiMappings } from "../src/mapping.js";+import { hiApiRouteForCapability } from "../src/routes.js";++const image: BlobRef = { kind: "blob", resource: "res_hiapi_1", size: 3, mediaType: "image/png" };+const video: BlobRef = { kind: "blob", resource: "res_hiapi_2", size: 3, mediaType: "video/mp4" };+const resolve = async () => "https://example.test/reference";+const route = (module: string, name: string) => hiApiRouteForCapability({ module: { name: module, version: "1" }, name })!;+const constraints = (request: unknown) => request as CanonicalValue;++test("every HiAPI mapping covers its model's ports", () => {+ const tables = {+ ...seedancePorts, ...grokImaginePorts, ...nanoBananaPorts,+ "seedream-5-lite": seedream5LitePorts, "minimax-h3": minimaxH3Ports, "gpt-image-2": gptImage2Ports,+ };+ for (const mapping of hiApiMappings) {+ assertMappingCoversPorts(tables[mapping.capability.name as keyof typeof tables], mapping);+ }+});++test("Seedance 2.5 selects the HiAPI model from the request shape", async () => {+ const seedance = route("@hypit/seedance", "seedance-2.5");+ const base = { prompt: ["go"], resolution: ["720p"], duration: [5], generateAudio: [true], webSearch: [false] };+ const text = seedance.prepare(constraints(sealSeedanceRequest("seedance-2.5", { ...base, aspectRatio: ["16:9"] })));+ assert.equal(text.model, "seedance-2.5/text-to-video");+ const frames = seedance.prepare(constraints(sealSeedanceRequest("seedance-2.5", {+ ...base, aspectRatio: ["adaptive"], firstFrame: [{ role: "image", artifact: image, fields: { personReference: true } }],+ })));+ assert.equal(frames.model, "seedance-2.5/image-to-video");+ assert.deepEqual(await frames.compile(resolve), {+ model: "seedance-2.5/image-to-video",+ input: { prompt: "go", resolution: "720p", duration: 5, generate_audio: true, web_search: false, aspect_ratio: "adaptive", first_frame_url: "https://example.test/reference" },+ });+ const references = sealSeedanceRequest("seedance-2.5", {+ ...base, aspectRatio: ["16:9"], referenceVideo: [{ role: "video", artifact: video }],+ });+ assert.equal(seedance.prepare(constraints(references)).model, "seedance-2.5/reference-to-video");+ const framed = seedance.supports({ capability: seedance.capability, returns: seedance.returns,+ constraints: constraints(sealSeedanceRequest("seedance-2.5", { ...base, aspectRatio: ["16:9"], firstFrame: [{ role: "image", artifact: image }] })) });+ assert.equal(framed.status, "unsupported");+});++test("Seedream quality becomes the HiAPI resolution tier and 3K is unsupported", async () => {+ const seedream = route("@hypit/seedream", "seedream-5-lite");+ const request = sealSeedreamRequest({ prompt: ["a cup"], aspectRatio: ["9:16"], quality: ["ultra"], outputFormat: ["png"], nsfwCheck: [true], images: [{ role: "image", artifact: image }] });+ assert.deepEqual(await seedream.prepare(constraints(request)).compile(resolve), {+ model: "seedream-5.0-lite/image-to-image",+ input: { prompt: "a cup", aspect_ratio: "9:16", resolution: "4K", image_urls: ["https://example.test/reference"] },+ });+ const high = sealSeedreamRequest({ ...request.ports, quality: ["high"] });+ assert.equal(seedream.supports({ capability: seedream.capability, returns: seedream.returns, constraints: constraints(high) }).status, "unsupported");+});++test("GPT Image 2 background outside 1K is unsupported before references resolve", () => {+ const gpt = route("@hypit/gpt-image", "gpt-image-2");+ const request = sealGptImage2Request({ prompt: ["cut"], aspectRatio: ["1:1"], resolution: ["2K"], background: ["opaque"] });+ assert.equal(gpt.supports({ capability: gpt.capability, returns: gpt.returns, constraints: constraints(request) }).status, "unsupported");+});diff --git a/packages/provider-monid/README.md b/packages/provider-monid/README.mdnew file mode 100644index 00000000..e64f06b1--- /dev/null+++ b/packages/provider-monid/README.md@@ -0,0 +1,60 @@+# `@hypit/provider-monid`++Hypit Runtime Provider for a [Monid](https://monid.ai) workspace. It runs Monid's `bytedance`+Seedance endpoints through `POST /v1/run`, polls `GET /v1/runs/{runId}` until the run is terminal,+downloads the returned `video_url` and stores the video in the current Build.++| Capability | Monid endpoint |+| --- | --- |+| `@hypit/seedance@1#seedance-2` | `bytedance` `/v1/video/seedance-2.0` |+| `@hypit/seedance@1#seedance-2-fast` | `bytedance` `/v1/video/seedance-2.0-fast` |+| `@hypit/seedance@1#seedance-2-mini` | `bytedance` `/v1/video/seedance-2.0-mini` |+| `@hypit/seedance@1#seedance-2.5` | `bytedance` `/v1/video/seedance-2.5` |++Monid's catalogue also lists MiniMax H3 and other generation endpoints; their input schemas are+published only through the authenticated `inspect` operation, so this Provider maps the Seedance+endpoints whose request body Monid documents publicly.++The run `input` is the BytePlus ModelArk request the endpoint relays: one `content` array holding+the prompt and each media input as a typed item with its `role` (`first_frame`, `last_frame`,+`reference_image`, `reference_video`, `reference_audio`), then `resolution`, `ratio`, `duration` and+`generate_audio`. Monid documents no web search field for these endpoints, so `web-search="true"`+is unsupported. Seedance 2.5 frame mode (`first-frame` present) requires `aspect-ratio="adaptive"`.+Seedance visual references may carry `person-reference`; the Provider accepts the declaration and+transmits nothing for it, since the endpoint has no field for it. Seedance rejects reference images+and videos that contain a real human face; Monid offers no way to register authorized portrait+material, so such a request fails with the upstream moderation error.++Reference media are uploaded through the workspace file system Monid provides for this purpose+(`sfs`): `/put` signs an upload for `hypit/<resource>.<ext>`, the bytes are `PUT` to that URL, and+`/cat` mints a one-day download URL that the generation endpoint fetches. Uploaded files stay in the+workspace until removed with `/rm`. Embedded callers may replace this transport with+`publicAssetUrl`.++A run ends with Monid's own status (`COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT`) and,+when completed, the provider's HTTP status in `providerResponse`. A completed run whose provider+answered 4xx or 5xx fails with that status and the provider's error message; a `BLOCKED` run keeps+Monid's `reason`. Signed URLs in messages are redacted.++Runtime Profile example:++```json+{+ "endpoints": {+ "monid.default": {+ "use": "@hypit/provider-monid",+ "pool": "monid.default",+ "config": {+ "apiKey": { "store": "platform", "key": "monid.api-key" },+ "defaultConcurrency": 3,+ "pollIntervalMs": 10000+ }+ }+ }+}+```++`baseUrl` defaults to `https://api.monid.ai`. Store the API key with+`hypit auth login monid.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote run and action+concurrency; file-system runs poll at most every five seconds within `requestTimeoutMs`.diff --git a/packages/provider-monid/package.json b/packages/provider-monid/package.jsonnew file mode 100644index 00000000..ab3f15f3--- /dev/null+++ b/packages/provider-monid/package.json@@ -0,0 +1,19 @@+{+ "name": "@hypit/provider-monid",+ "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/seedance": "workspace:*"+ }+}diff --git a/packages/provider-monid/src/activation.ts b/packages/provider-monid/src/activation.tsnew file mode 100644index 00000000..185133a6--- /dev/null+++ b/packages/provider-monid/src/activation.ts@@ -0,0 +1,62 @@+import {+ createRuntimeEndpointAdapterFacet,+ runtimeConfigCredentialRef,+ runtimeConfigActionLimits,+ runtimeConfigExact,+ runtimeConfigObject,+ runtimeConfigPositiveInteger,+ runtimeConfigString,+} from "@hypit/runtime-kit";++import { createMonidProvider } from "./provider.js";++const adapter = createRuntimeEndpointAdapterFacet({+ use: "@hypit/provider-monid",+ activate(context) {+ if (context.pool === undefined) throw new Error("Monid Provider Pool is required");+ const config = runtimeConfigObject(context.config, "Monid");+ runtimeConfigExact(config, [+ "baseUrl",+ "apiKey",+ "defaultConcurrency",+ "actionLimits",+ "pollIntervalMs",+ "requestTimeoutMs",+ "operationTimeoutMs",+ ], "Monid");+ const baseUrl = runtimeConfigString(config.baseUrl, "Monid 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("Monid baseUrl must use HTTPS or loopback");+ }+ }+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "Monid apiKey");+ if (apiKey === undefined) throw new Error("Monid apiKey CredentialRef is required");+ const actionLimits = runtimeConfigActionLimits(config.actionLimits);+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "Monid defaultConcurrency");+ const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "Monid pollIntervalMs");+ const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "Monid requestTimeoutMs");+ const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "Monid operationTimeoutMs");+ return {+ endpoint: createMonidProvider({+ 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;diff --git a/packages/provider-monid/src/errors.ts b/packages/provider-monid/src/errors.tsnew file mode 100644index 00000000..c15bd039--- /dev/null+++ b/packages/provider-monid/src/errors.ts@@ -0,0 +1,55 @@+/** Monid's `{ code, message }` error envelope and run outcome fields, kept at the service boundary. */+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 safeMonidReason(value: string): string {+ return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");+}++export class MonidServiceError extends Error {+ constructor(readonly code: string, message: string) { super(message); }+}++export class MonidHttpError extends MonidServiceError {+ constructor(readonly status: number, response: { readonly headers: Headers }, bodyText: string,+ request: { readonly method: string; readonly path: string }) {+ let body: Record<string, unknown> | undefined;+ try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }+ const reason = text(body?.message) ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);+ const requestId = text(response.headers.get("x-request-id"));+ const facts = [+ `Monid HTTP ${status}`, `${request.method} ${request.path}`,+ ...(requestId === undefined ? [] : [`request=${requestId}`]),+ ];+ super("MONID_HTTP_ERROR", `${facts.join("; ")}${reason === undefined ? "" : `: ${safeMonidReason(reason)}`}`);+ }+}++export const monidTerminalStatuses = ["COMPLETED", "FAILED", "BLOCKED", "STOPPED", "TIMED_OUT"] as const;++/**+ * A run that ended without provider output: a non-COMPLETED terminal status, or COMPLETED with a+ * provider HTTP error. `undefined` while the run is pending or when the provider answered 2xx.+ */+export function monidRunFailure(run: Record<string, unknown>, id: string): MonidServiceError | undefined {+ const status = String(run.status);+ if (status !== "COMPLETED") {+ if (!monidTerminalStatuses.includes(status as typeof monidTerminalStatuses[number])) return undefined;+ const reason = text(run.reason);+ return new MonidServiceError(`MONID_RUN_${status}`,+ `Monid run ${id} ${status}${reason === undefined ? "" : `: ${safeMonidReason(reason)}`}`);+ }+ const provider = record(run.providerResponse);+ const httpStatus = typeof provider?.httpStatus === "number" ? provider.httpStatus : 200;+ if (httpStatus < 400) return undefined;+ const error = record(provider?.error);+ const detail = text(error?.message) ?? text(record(error?.error)?.message) ?? text(provider?.error);+ return new MonidServiceError("MONID_PROVIDER_ERROR",+ `Monid run ${id} completed with provider HTTP ${httpStatus}${detail === undefined ? "" : `: ${safeMonidReason(detail)}`}`);+}diff --git a/packages/provider-monid/src/index.ts b/packages/provider-monid/src/index.tsnew file mode 100644index 00000000..abcda2ca--- /dev/null+++ b/packages/provider-monid/src/index.ts@@ -0,0 +1,2 @@+export { createMonidProvider, monidProviderModuleRef } from "./provider.js";+export type { CreateMonidProviderOptions } from "./provider.js";diff --git a/packages/provider-monid/src/mapping.ts b/packages/provider-monid/src/mapping.tsnew file mode 100644index 00000000..56562b44--- /dev/null+++ b/packages/provider-monid/src/mapping.ts@@ -0,0 +1,33 @@+import type { ModuleRef } from "@hypit/protocol";+import type { GenerationWireMapping } from "@hypit/generation";++const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };++/**+ * Monid `bytedance` endpoints and the fields their ModelArk request body takes. Media fields name+ * the `role` of a `content` item; routes.ts folds them into that array. `personReference` is+ * accepted on visual references and not transmitted: the endpoint has no field for it.+ */+const seedance = (name: string, endpoint: string): GenerationWireMapping => ({+ capability: { module: SEEDANCE, name }, result: "video", routes: [{ model: endpoint }],+ 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 monidMappings: readonly GenerationWireMapping[] = [+ seedance("seedance-2", "/v1/video/seedance-2.0"),+ seedance("seedance-2-fast", "/v1/video/seedance-2.0-fast"),+ seedance("seedance-2-mini", "/v1/video/seedance-2.0-mini"),+ seedance("seedance-2.5", "/v1/video/seedance-2.5"),+];diff --git a/packages/provider-monid/src/provider.ts b/packages/provider-monid/src/provider.tsnew file mode 100644index 00000000..8cd695f5--- /dev/null+++ b/packages/provider-monid/src/provider.ts@@ -0,0 +1,242 @@+import { requestDeadline } from "@hypit/runtime-kit";+import type { AsyncEndpoint, EndpointCredential, EndpointInvocationContext, EndpointOutcome } 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 { monidRouteForCapability, monidRoutes } from "./routes.js";+import { MonidHttpError, MonidServiceError, monidRunFailure, monidTerminalStatuses } from "./errors.js";++export const monidProviderModuleRef = { name: "@hypit/provider-monid", version: "1" } as const;++export type CreateMonidProviderOptions = {+ 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 the workspace file system upload. */+ readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;+};++type Handle = {+ readonly contract: "hypit.monid-operation@1";+ readonly runId: 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, "Monid 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, "Monid apiKey credential is unavailable; store a Monid 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 MonidServiceError ? error.code : "MONID_ERROR", message: failureMessage(error) } };+}+function runId(run: Record<string, unknown>): string {+ assert(typeof run.runId === "string" && run.runId.length > 0, "Monid response has no runId");+ return run.runId;+}+function httpsUrl(value: unknown, subject: string): string {+ assert(typeof value === "string" && /^https?:\/\//u.test(value), `${subject} has no URL`);+ return value;+}+/** The relayed ModelArk result; Monid returns the task's `video_url` in the run output. */+function outputVideoUrl(run: Record<string, unknown>): string {+ const output = object(run.output, "Monid run output");+ const nested = output.content !== undefined ? object(output.content, "Monid run output content").video_url : undefined;+ return httpsUrl(output.video_url ?? nested, "Monid run output");+}+const extensions: Readonly<Record<string, string>> = {+ "image/jpeg": "jpg", "image/png": "png", "image/webp": "webp", "video/mp4": "mp4", "video/quicktime": "mov",+ "audio/wav": "wav", "audio/x-wav": "wav", "audio/mpeg": "mp3",+};++class MonidClient {+ constructor(readonly baseUrl: string, readonly timeout: number, readonly pollIntervalMs: number, readonly fetcher: typeof globalThis.fetch) {}+ async json(path: string, key: string, init: RequestInit = {}): Promise<{ readonly status: number; readonly body: 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());+ let body: unknown;+ try { body = text.length === 0 ? {} : JSON.parse(text); } catch { body = undefined; }+ // A synchronous run mirrors the provider's HTTP status while still returning the run itself.+ const run = body !== null && typeof body === "object" && !Array.isArray(body) && typeof (body as Record<string, unknown>).runId === "string";+ if (!response.ok && !run) throw new MonidHttpError(response.status, response, text, { method: init.method ?? "GET", path });+ assert(body !== undefined, `Monid returned invalid JSON (${response.status})`);+ return { status: response.status, body: object(body, "Monid response") };+ } finally { deadline.finish(); }+ }+ async run(request: { readonly provider: string; readonly endpoint: string; readonly input: Record<string, unknown> }, key: string) {+ return await this.json("/v1/run", key, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(request) });+ }+ async getRun(id: string, key: string): Promise<Record<string, unknown>> {+ return (await this.json(`/v1/runs/${encodeURIComponent(id)}`, key)).body;+ }+ /** Run a short workspace operation to completion and return its provider output. */+ async completeRun(request: { readonly provider: string; readonly endpoint: string; readonly input: Record<string, unknown> }, key: string): Promise<Record<string, unknown>> {+ let run = (await this.run(request, key)).body;+ const id = runId(run);+ const deadline = requestDeadline(this.timeout);+ try {+ while (!monidTerminalStatuses.includes(String(run.status) as typeof monidTerminalStatuses[number])) {+ await deadline.wait(new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs)));+ run = await this.getRun(id, key);+ }+ } finally { deadline.finish(); }+ const rejected = monidRunFailure(run, id);+ if (rejected !== undefined) throw rejected;+ return object(run.output, `Monid ${request.provider}${request.endpoint} output`);+ }+ /** Upload through the workspace file system (`sfs`) and mint a URL third parties can fetch. */+ async publish(artifact: BlobRef, resources: ResourceStore, key: string): Promise<string> {+ const bytes = await resources.get(artifact.resource);+ assert(bytes !== undefined && bytes.byteLength === artifact.size, `Reference Resource ${artifact.resource} is unavailable or has changed`);+ const path = `hypit/${artifact.resource}.${extensions[artifact.mediaType] ?? artifact.mediaType.split("/")[1] ?? "bin"}`;+ const put = await this.completeRun({ provider: "sfs", endpoint: "/put", input: { path, sizeBytes: bytes.byteLength } }, key);+ const uploadUrl = httpsUrl(put.uploadUrl, "Monid sfs /put output");+ const deadline = requestDeadline(this.timeout);+ try {+ const response = await deadline.wait(this.fetcher(uploadUrl, { method: "PUT", body: new Blob([new Uint8Array(bytes)]), signal: deadline.signal }));+ assert(response.ok, `Monid file upload returned HTTP ${response.status}`);+ } finally { deadline.finish(); }+ const cat = await this.completeRun({ provider: "sfs", endpoint: "/cat", input: { path, ttl: "1d" } }, key);+ return httpsUrl(cat.url, "Monid sfs /cat output");+ }+ 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(`Monid 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 resolverFor(client: MonidClient, context: EndpointInvocationContext, publicAssetUrl: CreateMonidProviderOptions["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 = publicAssetUrl === undefined+ ? client.publish(artifact, context.resources, apiKey(context.credentials))+ : publicAssetUrl(artifact, context.resources, fields);+ resolved.set(artifact.resource, promise);+ return promise;+ };+}++function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreateMonidProviderOptions["publicAssetUrl"]): AsyncEndpoint {+ return {+ async start(context) {+ try {+ const route = monidRouteForCapability(context.need.capability);+ assert(route !== undefined, "Monid does not implement this exact capability");+ const request = route.prepare(context.need.constraints);+ await context.reportProgress?.({ phase: `Preparing Monid request: bytedance ${request.endpoint}` });+ let input: Record<string, unknown>;+ try {+ input = await request.compile(resolverFor(client, context, publicAssetUrl));+ } catch (error) {+ throw new MonidServiceError(error instanceof MonidServiceError ? error.code : "MONID_ERROR",+ `Monid request preparation failed; endpoint=${request.endpoint}; generation not submitted: ${failureMessage(error)}`);+ }+ await context.reportProgress?.({ phase: `Submitting Monid request: bytedance ${request.endpoint}` });+ const { body: run } = await client.run({ provider: "bytedance", endpoint: request.endpoint, input }, apiKey(context.credentials));+ const handle: Handle = { contract: "hypit.monid-operation@1", runId: runId(run), route: route.key, startedAt: Date.now() };+ const receipt = { id: handle.runId };+ const ended = monidTerminalStatuses.includes(String(run.status) as typeof monidTerminalStatuses[number]);+ await context.checkpoint?.({ handle: canonicalize(handle), receipt, ...(ended ? { remoteEnded: true as const } : {}) });+ if (!ended) return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: String(run.status) }), receipt };+ const rejected = monidRunFailure(run, handle.runId);+ if (rejected !== undefined) return { ...failure(rejected), receipt };+ return { status: "ready", handle: canonicalize({ ...handle, url: outputVideoUrl(run) }), receipt };+ } catch (error) {+ return failure(error);+ }+ },+ async poll(context) {+ try {+ const handle = object(context.handle, "Monid handle") as unknown as Handle;+ const route = monidRouteForCapability(context.need.capability);+ assert(route !== undefined && handle.contract === "hypit.monid-operation@1" && handle.route === route.key, "Monid handle is invalid");+ const receipt = { id: handle.runId };+ if (Date.now() - handle.startedAt > maxOperationMs) {+ return { status: "failed", receipt, failure: { code: "MONID_OPERATION_TIMEOUT", message: `Monid run ${handle.runId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };+ }+ const run = await client.getRun(handle.runId, apiKey(context.credentials));+ const status = String(run.status);+ if (!monidTerminalStatuses.includes(status as typeof monidTerminalStatuses[number])) {+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };+ }+ const rejected = monidRunFailure(run, handle.runId);+ if (rejected !== undefined) return { ...failure(rejected), receipt };+ return { status: "ready", handle: canonicalize({ ...handle, url: outputVideoUrl(run) }), receipt };+ } catch (error) {+ return failure(error);+ }+ },+ async collect(context) {+ try {+ const handle = object(context.handle, "Monid handle") as unknown as Handle;+ const route = monidRouteForCapability(context.need.capability);+ assert(route !== undefined && handle.route === route.key, "Monid collection route differs");+ await context.reportProgress?.({ phase: "Receiving generated video" });+ const downloaded = await client.download(httpsUrl(handle.url, "Monid handle"));+ const blob = await context.resources.put(downloaded.bytes, downloaded.mediaType);+ return { status: "completed", result: { value: route.packageResult([blob]) }, receipt: { id: handle.runId } };+ } catch (error) {+ return failure(error);+ }+ },+ };+}++export function createMonidProvider(options: CreateMonidProviderOptions = {}) {+ const requestTimeoutMs = options.requestTimeoutMs ?? 300_000;+ const operationTimeoutMs = options.operationTimeoutMs ?? 30 * 60_000;+ const pollIntervalMs = options.pollIntervalMs ?? 10_000;+ for (const [name, value] of Object.entries({ requestTimeoutMs, operationTimeoutMs, pollIntervalMs })) {+ assert(Number.isSafeInteger(value) && value > 0, `Monid ${name} must be a positive integer`);+ }+ const client = new MonidClient(apiBaseUrl(options.baseUrl ?? "https://api.monid.ai"), requestTimeoutMs, Math.min(pollIntervalMs, 5_000), options.fetch ?? globalThis.fetch);+ const asyncEndpoint = endpoint(client, pollIntervalMs, operationTimeoutMs, options.publicAssetUrl);+ return defineEndpointPackage({+ module: monidProviderModuleRef, facet: "gateway", instance: options.instance ?? "monid.default", pool: options.pool ?? options.instance ?? "monid.default",+ pricing: { kind: "page", url: "https://monid.ai/tools/bytedance" },+ credentials: { apiKey: options.apiKey ?? credentialRef("os", "monid.api-key") },+ credentialInputs: { apiKey: { label: "Monid API key" } },+ defaultConcurrency: options.defaultConcurrency ?? 4,+ ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),+ capabilities: monidRoutes.map((route) => ({+ capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports,+ })),+ });+}diff --git a/packages/provider-monid/src/routes.ts b/packages/provider-monid/src/routes.tsnew file mode 100644index 00000000..93ee7b21--- /dev/null+++ b/packages/provider-monid/src/routes.ts@@ -0,0 +1,103 @@+import {+ compileWireRequest,+ selectWireModelForRequest,+ generationTypes,+ 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 { monidMappings } from "./mapping.js";++export type MonidPreparedRequest = {+ /** Monid endpoint path under the `bytedance` provider. */+ readonly endpoint: string;+ readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;+};++export type MonidRoute = GenerationWireMapping & {+ readonly key: string;+ readonly returns: TypeRef;+ readonly supports: (request: EndpointRequest) => EndpointSupport;+ readonly prepare: (constraints: CanonicalValue) => MonidPreparedRequest;+ 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 present(request: GenerationRequest, port: string): boolean {+ return (request.ports[port]?.length ?? 0) > 0;+}+function strings(value: unknown): readonly string[] {+ return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];+}++function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {+ if (scalar(request, "webSearch") === true) {+ return "Monid's Seedance endpoints document no web search field";+ }+ if (mapping.capability.name === "seedance-2.5" && present(request, "firstFrame") && scalar(request, "aspectRatio") !== "adaptive") {+ return `Seedance 2.5 frame mode takes only aspect-ratio adaptive, not ${String(scalar(request, "aspectRatio"))}`;+ }+ return undefined;+}++function contentItem(type: "image_url" | "video_url" | "audio_url", url: string, role: string) {+ return { type, [type]: { url }, role };+}++/** The ModelArk request body Monid relays: one `content` array of typed, role-tagged items plus the output settings. */+function arkInput(input: Record<string, unknown>): Record<string, unknown> {+ const first = input.first_frame;+ const last = input.last_frame;+ return {+ content: [+ { type: "text", text: input.text },+ ...(typeof first === "string" ? [contentItem("image_url", first, "first_frame")] : []),+ ...(typeof last === "string" ? [contentItem("image_url", last, "last_frame")] : []),+ ...strings(input.reference_image).map((url) => contentItem("image_url", url, "reference_image")),+ ...strings(input.reference_video).map((url) => contentItem("video_url", url, "reference_video")),+ ...strings(input.reference_audio).map((url) => contentItem("audio_url", url, "reference_audio")),+ ],+ resolution: input.resolution,+ ratio: input.ratio,+ duration: input.duration,+ generate_audio: input.generate_audio,+ };+}++function capabilityKey(capability: CapabilityRef): string {+ return `${capability.module.name}@${capability.module.version}#${capability.name}`;+}++export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) => ({+ ...mapping,+ key: capabilityKey(mapping.capability),+ returns: 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 {+ endpoint: selectWireModelForRequest(mapping, request),+ compile: async (resolve) => arkInput((await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),+ };+ },+ packageResult: (artifacts) => ({+ kind: "inline",+ value: canonicalize(sealGeneratedVideoSet({ videos: artifacts })),+ }),+}));++const byCapability = new Map(monidRoutes.map((route) => [route.key, route]));++export function monidRouteForCapability(capability: CapabilityRef): MonidRoute | undefined {+ return byCapability.get(capabilityKey(capability));+}diff --git a/packages/provider-monid/test/routes.test.ts b/packages/provider-monid/test/routes.test.tsnew file mode 100644index 00000000..6ff6077d--- /dev/null+++ b/packages/provider-monid/test/routes.test.ts@@ -0,0 +1,34 @@+import assert from "node:assert/strict";+import test from "node:test";+import { assertMappingCoversPorts } from "@hypit/generation";+import type { BlobRef, CanonicalValue } from "@hypit/protocol";+import { seedancePorts, sealSeedanceRequest } from "@hypit/seedance";++import { monidMappings } from "../src/mapping.js";+import { monidRouteForCapability } from "../src/routes.js";++const image: BlobRef = { kind: "blob", resource: "res_monid_1", size: 3, mediaType: "image/png" };+const resolve = async () => "https://sfs.monid.ai/signed";++test("every Monid mapping covers its model's ports", () => {+ for (const mapping of monidMappings) {+ assertMappingCoversPorts(seedancePorts[mapping.capability.name as keyof typeof seedancePorts], mapping);+ }+});++test("Seedance requests become the ModelArk input Monid relays", async () => {+ const route = monidRouteForCapability({ module: { name: "@hypit/seedance", version: "1" }, name: "seedance-2-mini" })!;+ const request = sealSeedanceRequest("seedance-2-mini", {+ prompt: ["turn"], referenceImage: [{ role: "image", artifact: image, fields: { personReference: true } }],+ resolution: ["720p"], aspectRatio: ["9:16"], duration: [6], generateAudio: [true], webSearch: [false],+ });+ const prepared = route.prepare(request as unknown as CanonicalValue);+ assert.equal(prepared.endpoint, "/v1/video/seedance-2.0-mini");+ assert.deepEqual(await prepared.compile(resolve), {+ content: [+ { type: "text", text: "turn" },+ { type: "image_url", image_url: { url: "https://sfs.monid.ai/signed" }, role: "reference_image" },+ ],+ resolution: "720p", ratio: "9:16", duration: 6, generate_audio: true,+ });+});diff --git a/packages/provider-pollo/README.md b/packages/provider-pollo/README.mdnew file mode 100644index 00000000..dc6becff--- /dev/null+++ b/packages/provider-pollo/README.md@@ -0,0 +1,59 @@+# `@hypit/provider-pollo`++Hypit Runtime Provider for a [Pollo AI](https://docs.pollo.ai) API platform account. Each capability+posts `{ "input": … }` to the model's generation path with the `x-api-key` header, polls+`GET /v1/generation/{taskId}/status` until every generation reaches `succeed`, downloads each+generation's `url` and stores the files in the current Build.++| Capability | Pollo generation path |+| --- | --- |+| `@hypit/minimax-h3@1#minimax-h3` | `/v1/generation/minimax/minimax-h3/video` |+| `@hypit/grok-imagine@1#grok-imagine-video-1.5-preview` | `/v1/generation/xai/grok-imagine-video-1-5/video` |+| `@hypit/gpt-image@1#gpt-image-2` | `/v1/generation/openai/gpt-image-2/image` |+| `@hypit/nano-banana@1#nano-banana-2` | `/v1/generation/google/nano-banana-2/image` |+| `@hypit/nano-banana@1#nano-banana-pro` | `/v1/generation/google/nano-banana-pro/image` |++Pollo documents further models; this Provider maps only the models the Distribution already+describes. Seedance and Seedream are not offered by Pollo.++MiniMax H3 requests send `prompt`, `duration`, `resolution` and `aspectRatio`; a first frame is+`image`, a last frame `imageTail`, and reference images, videos and audio become typed entries of+`refs`. Pollo renders 480p when `resolution` is omitted.++Service limits this Provider reports as unsupported before submitting:++- Grok Imagine 1.5 animates exactly one image and has no aspect-ratio field; author+ `aspect-ratio="auto"`.+- GPT Image 2 renders `1:1`, `3:2`, `2:3`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9` and `auto`;+ other ratios are unsupported. Pollo's `quality` field is left at its default.+- Nano Banana takes an explicit aspect ratio, not `auto`. `output-format` has no Pollo field and is+ not sent.++Pollo accepts reference media only by HTTP(S) URL. Configure `publicAssetUrl` when embedding the+Provider; without it, a request with reference media fails before submission, while text-only+requests proceed.++Runtime Profile example:++```json+{+ "endpoints": {+ "pollo.default": {+ "use": "@hypit/provider-pollo",+ "pool": "pollo.default",+ "config": {+ "apiKey": { "store": "platform", "key": "pollo.api-key" },+ "defaultConcurrency": 3,+ "pollIntervalMs": 10000+ }+ }+ }+}+```++`baseUrl` defaults to `https://pollo.ai/api/platform`. Store the API key with+`hypit auth login pollo.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote task and action+concurrency. HTTP failures keep Pollo's `errorCode`, message and `requestId`; a failed generation+keeps its `failMsg`, with any signed URL in the message redacted. Pollo stores generated files for+14 days; the Provider downloads them when the task completes.diff --git a/packages/provider-pollo/package.json b/packages/provider-pollo/package.jsonnew file mode 100644index 00000000..b7b50266--- /dev/null+++ b/packages/provider-pollo/package.json@@ -0,0 +1,22 @@+{+ "name": "@hypit/provider-pollo",+ "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/gpt-image": "workspace:*",+ "@hypit/grok-imagine": "workspace:*",+ "@hypit/minimax-h3": "workspace:*",+ "@hypit/nano-banana": "workspace:*"+ }+}diff --git a/packages/provider-pollo/src/activation.ts b/packages/provider-pollo/src/activation.tsnew file mode 100644index 00000000..a2d13c61--- /dev/null+++ b/packages/provider-pollo/src/activation.ts@@ -0,0 +1,62 @@+import {+ createRuntimeEndpointAdapterFacet,+ runtimeConfigCredentialRef,+ runtimeConfigActionLimits,+ runtimeConfigExact,+ runtimeConfigObject,+ runtimeConfigPositiveInteger,+ runtimeConfigString,+} from "@hypit/runtime-kit";++import { createPolloProvider } from "./provider.js";++const adapter = createRuntimeEndpointAdapterFacet({+ use: "@hypit/provider-pollo",+ activate(context) {+ if (context.pool === undefined) throw new Error("Pollo Provider Pool is required");+ const config = runtimeConfigObject(context.config, "Pollo");+ runtimeConfigExact(config, [+ "baseUrl",+ "apiKey",+ "defaultConcurrency",+ "actionLimits",+ "pollIntervalMs",+ "requestTimeoutMs",+ "operationTimeoutMs",+ ], "Pollo");+ const baseUrl = runtimeConfigString(config.baseUrl, "Pollo 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("Pollo baseUrl must use HTTPS or loopback");+ }+ }+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "Pollo apiKey");+ if (apiKey === undefined) throw new Error("Pollo apiKey CredentialRef is required");+ const actionLimits = runtimeConfigActionLimits(config.actionLimits);+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "Pollo defaultConcurrency");+ const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "Pollo pollIntervalMs");+ const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "Pollo requestTimeoutMs");+ const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "Pollo operationTimeoutMs");+ return {+ endpoint: createPolloProvider({+ 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;diff --git a/packages/provider-pollo/src/errors.ts b/packages/provider-pollo/src/errors.tsnew file mode 100644index 00000000..530ac3e5--- /dev/null+++ b/packages/provider-pollo/src/errors.ts@@ -0,0 +1,41 @@+/** Pollo's `{ errorCode, message, code, requestId }` envelope and generation `failMsg`, kept at the service boundary. */+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 safePolloReason(value: string): string {+ return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");+}++export class PolloServiceError extends Error {+ constructor(readonly code: string, message: string) { super(message); }+}++export class PolloHttpError extends PolloServiceError {+ constructor(readonly status: number, bodyText: string, request: { readonly method: string; readonly path: string }) {+ let body: Record<string, unknown> | undefined;+ try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }+ const code = text(body?.errorCode) ?? "POLLO_HTTP_ERROR";+ const reason = text(body?.message) ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);+ const requestId = text(body?.requestId);+ const facts = [+ `Pollo HTTP ${status}`, code, `${request.method} ${request.path}`,+ ...(requestId === undefined ? [] : [`request=${requestId}`]),+ ];+ super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safePolloReason(reason)}`}`);+ }+}++/** The first failed generation of a task; `undefined` when none failed. */+export function polloTaskFailure(generations: readonly Record<string, unknown>[], id: string): PolloServiceError | undefined {+ const failed = generations.find((generation) => generation.status === "failed");+ if (failed === undefined) return undefined;+ const reason = text(failed.failMsg);+ return new PolloServiceError("POLLO_TASK_FAILED",+ `Pollo task ${id} failed${reason === undefined ? "" : `: ${safePolloReason(reason)}`}`);+}diff --git a/packages/provider-pollo/src/index.ts b/packages/provider-pollo/src/index.tsnew file mode 100644index 00000000..691f1710--- /dev/null+++ b/packages/provider-pollo/src/index.ts@@ -0,0 +1,2 @@+export { createPolloProvider, polloProviderModuleRef } from "./provider.js";+export type { CreatePolloProviderOptions } from "./provider.js";diff --git a/packages/provider-pollo/src/mapping.ts b/packages/provider-pollo/src/mapping.tsnew file mode 100644index 00000000..50d97b3b--- /dev/null+++ b/packages/provider-pollo/src/mapping.ts@@ -0,0 +1,60 @@+import type { ModuleRef } from "@hypit/protocol";+import type { GenerationWireMapping } from "@hypit/generation";++const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };+const GROK: ModuleRef = { name: "@hypit/grok-imagine", version: "1" };+const GPT_IMAGE: ModuleRef = { name: "@hypit/gpt-image", version: "1" };+const NANO_BANANA: ModuleRef = { name: "@hypit/nano-banana", version: "1" };++/**+ * Pollo generation paths and the `input` fields each documents. The route model is the request+ * path under the Pollo platform base URL. Reference fields prefixed `refs_` are folded into MiniMax's+ * typed `refs` array by routes.ts.+ */+export const polloMappings: readonly GenerationWireMapping[] = [+ {+ capability: { module: MINIMAX, name: "minimax-h3" }, result: "video", routes: [{ model: "/v1/generation/minimax/minimax-h3/video" }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ duration: { as: "value", field: "duration" },+ resolution: { as: "value", field: "resolution" },+ aspectRatio: { as: "value", field: "aspectRatio" },+ firstFrame: { as: "url", field: "image" },+ lastFrame: { as: "url", field: "imageTail" },+ referenceImage: { as: "urlArray", field: "refs_image" },+ referenceVideo: { as: "urlArray", field: "refs_video" },+ referenceAudio: { as: "urlArray", field: "refs_audio" },+ },+ },+ {+ capability: { module: GROK, name: "grok-imagine-video-1.5-preview" }, result: "video",+ routes: [{ model: "/v1/generation/xai/grok-imagine-video-1-5/video" }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ duration: { as: "value", field: "duration" },+ images: { as: "urlArray", field: "images" },+ },+ },+ {+ capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image", routes: [{ model: "/v1/generation/openai/gpt-image-2/image" }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspectRatio" },+ resolution: { as: "value", field: "resolution" },+ background: { as: "value", field: "background" },+ images: { as: "urlArray", field: "images" },+ },+ },+ ...(["nano-banana-2", "nano-banana-pro"] as const).map((name): GenerationWireMapping => ({+ capability: { module: NANO_BANANA, name }, result: "image", routes: [{ model: `/v1/generation/google/${name}/image` }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ images: { as: "urlArray", field: "images" },+ aspectRatio: { as: "value", field: "aspectRatio" },+ resolution: { as: "value", field: "resolution" },+ outputFormat: { as: "value", field: "output_format" },+ },+ })),+];diff --git a/packages/provider-pollo/src/provider.ts b/packages/provider-pollo/src/provider.tsnew file mode 100644index 00000000..ff3ffdcd--- /dev/null+++ b/packages/provider-pollo/src/provider.ts@@ -0,0 +1,194 @@+import { requestDeadline } from "@hypit/runtime-kit";+import type { AsyncEndpoint, EndpointCredential, EndpointInvocationContext, EndpointOutcome } 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 { polloRouteForCapability, polloRoutes } from "./routes.js";+import { PolloHttpError, PolloServiceError, polloTaskFailure } from "./errors.js";++export const polloProviderModuleRef = { name: "@hypit/provider-pollo", version: "1" } as const;++export type CreatePolloProviderOptions = {+ 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 an HTTP(S) URL Pollo can fetch. Pollo accepts no inline media. */+ readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore, fields?: Readonly<Record<string, string | number | boolean>>) => Promise<string>;+};++type Handle = {+ readonly contract: "hypit.pollo-operation@1";+ readonly taskId: string;+ readonly route: string;+ readonly startedAt: number;+ readonly urls?: readonly 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, "Pollo 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, "Pollo apiKey credential is unavailable; store a Pollo 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 PolloServiceError ? error.code : "POLLO_ERROR", message: failureMessage(error) } };+}++class PolloClient {+ 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: { "x-api-key": key, ...(init.headers ?? {}) },+ }));+ const text = await deadline.wait(response.text());+ if (!response.ok) throw new PolloHttpError(response.status, text, { method: init.method ?? "GET", path });+ let body: unknown;+ try { body = text.length === 0 ? {} : JSON.parse(text); } catch { throw new Error(`Pollo returned invalid JSON (${response.status})`); }+ return object(body, "Pollo response");+ } finally { deadline.finish(); }+ }+ 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(`Pollo 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 resolverFor(context: EndpointInvocationContext, publicAssetUrl: CreatePolloProviderOptions["publicAssetUrl"]): GenerationArtifactUrlResolver {+ const resolved = new Map<string, Promise<string>>();+ return (artifact, fields) => {+ const existing = resolved.get(artifact.resource);+ if (existing !== undefined) return existing;+ assert(publicAssetUrl !== undefined,+ "Pollo accepts reference media only by HTTP(S) URL; configure publicAssetUrl for this Endpoint");+ const promise = publicAssetUrl(artifact, context.resources, fields);+ resolved.set(artifact.resource, promise);+ return promise;+ };+}++function endpoint(client: PolloClient, pollIntervalMs: number, maxOperationMs: number, publicAssetUrl: CreatePolloProviderOptions["publicAssetUrl"]): AsyncEndpoint {+ return {+ async start(context) {+ try {+ const route = polloRouteForCapability(context.need.capability);+ assert(route !== undefined, "Pollo does not implement this exact capability");+ const request = route.prepare(context.need.constraints);+ await context.reportProgress?.({ phase: `Preparing Pollo request: ${request.path}` });+ let body: Record<string, unknown>;+ try {+ body = await request.compile(resolverFor(context, publicAssetUrl));+ } catch (error) {+ throw new PolloServiceError(error instanceof PolloServiceError ? error.code : "POLLO_ERROR",+ `Pollo request preparation failed; path=${request.path}; generation not submitted: ${failureMessage(error)}`);+ }+ await context.reportProgress?.({ phase: `Submitting Pollo request: ${request.path}` });+ const response = await client.json(request.path, apiKey(context.credentials), {+ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),+ });+ assert(typeof response.taskId === "string" && response.taskId.length > 0, "Pollo response has no taskId");+ const handle: Handle = { contract: "hypit.pollo-operation@1", taskId: response.taskId, 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: String(response.status ?? "submitted") }), receipt };+ } catch (error) {+ return failure(error);+ }+ },+ async poll(context) {+ try {+ const handle = object(context.handle, "Pollo handle") as unknown as Handle;+ const route = polloRouteForCapability(context.need.capability);+ assert(route !== undefined && handle.contract === "hypit.pollo-operation@1" && handle.route === route.key, "Pollo handle is invalid");+ const receipt = { id: handle.taskId };+ if (Date.now() - handle.startedAt > maxOperationMs) {+ return { status: "failed", receipt, failure: { code: "POLLO_OPERATION_TIMEOUT", message: `Pollo task ${handle.taskId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };+ }+ const task = await client.json(`/v1/generation/${encodeURIComponent(handle.taskId)}/status`, apiKey(context.credentials));+ assert(Array.isArray(task.generations) && task.generations.length > 0, "Pollo task has no generations");+ const generations = task.generations.map((item, index) => object(item, `Pollo generation ${index + 1}`));+ const rejected = polloTaskFailure(generations, handle.taskId);+ if (rejected !== undefined) return { ...failure(rejected), receipt };+ const pending = generations.find((generation) => generation.status !== "succeed");+ if (pending !== undefined) {+ const status = String(pending.status);+ assert(status === "waiting" || status === "processing", `Pollo returned unknown generation status ${status}`);+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: status }), receipt };+ }+ const urls = generations.map((generation, index) => {+ assert(typeof generation.url === "string" && /^https?:\/\//u.test(generation.url), `Pollo generation ${index + 1} has no URL`);+ return generation.url;+ });+ return { status: "ready", handle: canonicalize({ ...handle, urls }), receipt };+ } catch (error) {+ return failure(error);+ }+ },+ async collect(context) {+ try {+ const handle = object(context.handle, "Pollo handle") as unknown as Handle;+ const route = polloRouteForCapability(context.need.capability);+ assert(route !== undefined && handle.route === route.key && Array.isArray(handle.urls), "Pollo collection route differs");+ await context.reportProgress?.({ phase: "Receiving generated files" });+ const blobs: BlobRef[] = [];+ for (const url of handle.urls) {+ const downloaded = await client.download(url);+ blobs.push(await context.resources.put(downloaded.bytes, downloaded.mediaType));+ }+ return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.taskId } };+ } catch (error) {+ return failure(error);+ }+ },+ };+}++export function createPolloProvider(options: CreatePolloProviderOptions = {}) {+ 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, `Pollo ${name} must be a positive integer`);+ }+ const client = new PolloClient(apiBaseUrl(options.baseUrl ?? "https://pollo.ai/api/platform"), requestTimeoutMs, options.fetch ?? globalThis.fetch);+ const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, operationTimeoutMs, options.publicAssetUrl);+ return defineEndpointPackage({+ module: polloProviderModuleRef, facet: "gateway", instance: options.instance ?? "pollo.default", pool: options.pool ?? options.instance ?? "pollo.default",+ pricing: { kind: "page", url: "https://api.pollo.ai/pricing" },+ credentials: { apiKey: options.apiKey ?? credentialRef("os", "pollo.api-key") },+ credentialInputs: { apiKey: { label: "Pollo API key" } },+ defaultConcurrency: options.defaultConcurrency ?? 4,+ ...(options.actionLimits === undefined ? {} : { actionLimits: options.actionLimits }),+ capabilities: polloRoutes.map((route) => ({+ capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, capacity: route.capability.name, supports: route.supports,+ })),+ });+}diff --git a/packages/provider-pollo/src/routes.ts b/packages/provider-pollo/src/routes.tsnew file mode 100644index 00000000..9b9e77f1--- /dev/null+++ b/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));+}diff --git a/packages/provider-pollo/test/routes.test.ts b/packages/provider-pollo/test/routes.test.tsnew file mode 100644index 00000000..59c3b944--- /dev/null+++ b/packages/provider-pollo/test/routes.test.ts@@ -0,0 +1,50 @@+import assert from "node:assert/strict";+import test from "node:test";+import { assertMappingCoversPorts } from "@hypit/generation";+import type { BlobRef, CanonicalValue } from "@hypit/protocol";+import { gptImage2Ports } from "@hypit/gpt-image";+import { grokImaginePorts, sealGrokImagineRequest } from "@hypit/grok-imagine";+import { minimaxH3Ports, sealMinimaxH3Request } from "@hypit/minimax-h3";+import { nanoBananaPorts } from "@hypit/nano-banana";++import { polloMappings } from "../src/mapping.js";+import { polloRouteForCapability } from "../src/routes.js";++const image: BlobRef = { kind: "blob", resource: "res_pollo_1", size: 3, mediaType: "image/png" };+const audio: BlobRef = { kind: "blob", resource: "res_pollo_2", size: 3, mediaType: "audio/wav" };+const resolve = async (artifact: { resource: string }) => `https://example.test/${artifact.resource}`;+const route = (module: string, name: string) => polloRouteForCapability({ module: { name: module, version: "1" }, name })!;+const constraints = (request: unknown) => request as CanonicalValue;++test("every Pollo mapping covers its model's ports", () => {+ const tables = { ...grokImaginePorts, ...nanoBananaPorts, "minimax-h3": minimaxH3Ports, "gpt-image-2": gptImage2Ports };+ for (const mapping of polloMappings) {+ assertMappingCoversPorts(tables[mapping.capability.name as keyof typeof tables], mapping);+ }+});++test("MiniMax H3 references become Pollo typed refs", async () => {+ const minimax = route("@hypit/minimax-h3", "minimax-h3");+ const request = sealMinimaxH3Request({+ prompt: ["walk"], duration: [6], resolution: ["2K"], aspectRatio: ["9:16"],+ referenceImage: [{ role: "image", artifact: image }], referenceAudio: [{ role: "audio", artifact: audio }],+ });+ const prepared = minimax.prepare(constraints(request));+ assert.equal(prepared.path, "/v1/generation/minimax/minimax-h3/video");+ assert.deepEqual(await prepared.compile(resolve), { input: {+ prompt: "walk", duration: 6, resolution: "2K", aspectRatio: "9:16",+ refs: [{ url: "https://example.test/res_pollo_1", type: "image" }, { url: "https://example.test/res_pollo_2", type: "audio" }],+ } });+});++test("Grok Imagine 1.5 sends its single image and takes only aspect-ratio auto", async () => {+ const grok = route("@hypit/grok-imagine", "grok-imagine-video-1.5-preview");+ const request = sealGrokImagineRequest("grok-imagine-video-1.5-preview", {+ prompt: ["spin"], aspectRatio: ["auto"], resolution: ["720p"], duration: [8], images: [{ role: "image", artifact: image }],+ });+ assert.deepEqual(await grok.prepare(constraints(request)).compile(resolve), { input: {+ prompt: "spin", resolution: "720p", duration: 8, image: "https://example.test/res_pollo_1",+ } });+ const framed = sealGrokImagineRequest("grok-imagine-video-1.5-preview", { ...request.ports, aspectRatio: ["16:9"] });+ assert.equal(grok.supports({ capability: grok.capability, returns: grok.returns, constraints: constraints(framed) }).status, "unsupported");+});diff --git a/packages/provider-tokendance/README.md b/packages/provider-tokendance/README.mdnew file mode 100644index 00000000..eca0c893--- /dev/null+++ b/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.diff --git a/packages/provider-tokendance/package.json b/packages/provider-tokendance/package.jsonnew file mode 100644index 00000000..78a714d6--- /dev/null+++ b/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:*"+ }+}diff --git a/packages/provider-tokendance/src/activation.ts b/packages/provider-tokendance/src/activation.tsnew file mode 100644index 00000000..2a2eec12--- /dev/null+++ b/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;diff --git a/packages/provider-tokendance/src/errors.ts b/packages/provider-tokendance/src/errors.tsnew file mode 100644index 00000000..078d83ff--- /dev/null+++ b/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)}`}`);+}diff --git a/packages/provider-tokendance/src/index.ts b/packages/provider-tokendance/src/index.tsnew file mode 100644index 00000000..fd660030--- /dev/null+++ b/packages/provider-tokendance/src/index.ts@@ -0,0 +1,2 @@+export { createTokenDanceProvider, tokenDanceProviderModuleRef } from "./provider.js";+export type { CreateTokenDanceProviderOptions } from "./provider.js";diff --git a/packages/provider-tokendance/src/mapping.ts b/packages/provider-tokendance/src/mapping.tsnew file mode 100644index 00000000..b10f2c27--- /dev/null+++ b/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" },+ },+ },+];diff --git a/packages/provider-tokendance/src/provider.ts b/packages/provider-tokendance/src/provider.tsnew file mode 100644index 00000000..3fee0ca2--- /dev/null+++ b/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 }),+ });+}diff --git a/packages/provider-tokendance/src/routes.ts b/packages/provider-tokendance/src/routes.tsnew file mode 100644index 00000000..5b0809a3--- /dev/null+++ b/packages/provider-tokendance/src/routes.ts@@ -0,0 +1,192 @@+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 { tokenDanceMappings } from "./mapping.js";++/** Which TokenDance protocol a capability submits through. */+export type TokenDanceProtocol = "ark-video" | "ark-image" | "minimax-video";++export type TokenDancePreparedRequest = {+ readonly model: string;+ readonly protocol: TokenDanceProtocol;+ readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;+};++/** Documented byte limits for one protocol's media inputs; an absent kind is not accepted inline. */+export type TokenDanceMediaLimits = {+ readonly image?: number;+ readonly video?: number;+ readonly audio?: number;+ /** Documented cap on the whole JSON request body, when inline media count toward it. */+ readonly body?: number;+};++const MB = 1_000_000;++/**+ * Ark: images under 30 MB and audio at most 15 MB may travel as Base64 within a 64 MB request body;+ * videos take URLs only. MiniMax: every kind is uploaded through its file API within these sizes.+ */+export const tokenDanceMediaLimits: Readonly<Record<TokenDanceProtocol, TokenDanceMediaLimits>> = {+ "ark-video": { image: 30 * MB, audio: 15 * MB, body: 64 * MB },+ "ark-image": { image: 30 * MB },+ "minimax-video": { image: 30 * MB, video: 50 * MB, audio: 15 * MB },+};++export type TokenDanceRoute = GenerationWireMapping & {+ readonly key: string;+ readonly returns: TypeRef;+ readonly protocol: TokenDanceProtocol;+ readonly mediaLimits: TokenDanceMediaLimits;+ readonly supports: (request: EndpointRequest) => EndpointSupport;+ readonly prepare: (constraints: CanonicalValue) => TokenDancePreparedRequest;+ 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 present(request: GenerationRequest, port: string): boolean {+ return (request.ports[port]?.length ?? 0) > 0;+}+function strings(value: unknown): readonly string[] {+ return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];+}++/** Seedream 5.0 lite pixel sizes for each resolution tier and aspect ratio, from the Ark image API reference. */+const SEEDREAM_SIZES: Readonly<Record<string, Readonly<Record<string, string>>>> = {+ basic: { "1:1": "2048x2048", "4:3": "2304x1728", "3:4": "1728x2304", "16:9": "2848x1600", "9:16": "1600x2848", "3:2": "2496x1664", "2:3": "1664x2496", "21:9": "3136x1344" },+ high: { "1:1": "3072x3072", "4:3": "3456x2592", "3:4": "2592x3456", "16:9": "4096x2304", "9:16": "2304x4096", "3:2": "3744x2496", "2:3": "2496x3744", "21:9": "4704x2016" },+ ultra: { "1:1": "4096x4096", "4:3": "4704x3520", "3:4": "3520x4704", "16:9": "5504x3040", "9:16": "3040x5504", "3:2": "4992x3328", "2:3": "3328x4992", "21:9": "6240x2656" },+};++function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {+ const ratio = scalar(request, "aspectRatio");+ if (mapping.capability.module.name === "@hypit/seedance") {+ if (mapping.capability.name === "seedance-2.5" && present(request, "firstFrame") && ratio !== "adaptive") {+ return `Seedance 2.5 frame mode on TokenDance takes only aspect-ratio adaptive, not ${String(ratio)}`;+ }+ return undefined;+ }+ if (mapping.capability.module.name === "@hypit/seedream") {+ const quality = String(scalar(request, "quality"));+ if (SEEDREAM_SIZES[quality]?.[String(ratio)] === undefined) {+ return `TokenDance Seedream 5.0 lite has no size for quality ${quality} at ${String(ratio)}`;+ }+ return undefined;+ }+ if (mapping.capability.module.name === "@hypit/minimax-h3") {+ const hasMedia = ["referenceImage", "referenceVideo", "referenceAudio", "firstFrame", "lastFrame"]+ .some((port) => present(request, port));+ if (!hasMedia && (ratio === undefined || ratio === "adaptive")) {+ return "MiniMax H3 text-to-video on TokenDance requires an explicit aspect-ratio";+ }+ }+ return undefined;+}++function contentItem(type: "image_url" | "video_url" | "audio_url", url: string, role: string) {+ return { type, [type]: { url }, role };+}++/** Ark and MiniMax both take one `content` array of typed, role-tagged items. */+function contentArray(input: Record<string, unknown>) {+ const first = input.first_frame;+ const last = input.last_frame;+ return [+ { type: "text", text: input.text },+ ...(typeof first === "string" ? [contentItem("image_url", first, "first_frame")] : []),+ ...(typeof last === "string" ? [contentItem("image_url", last, "last_frame")] : []),+ ...strings(input.reference_image).map((url) => contentItem("image_url", url, "reference_image")),+ ...strings(input.reference_video).map((url) => contentItem("video_url", url, "reference_video")),+ ...strings(input.reference_audio).map((url) => contentItem("audio_url", url, "reference_audio")),+ ];+}++function arkVideoBody(model: string, input: Record<string, unknown>): Record<string, unknown> {+ return {+ model,+ content: contentArray(input),+ resolution: input.resolution,+ ratio: input.ratio,+ duration: input.duration,+ generate_audio: input.generate_audio,+ ...(input.web_search === true ? { tools: [{ type: "web_search" }] } : {}),+ };+}++function arkImageBody(model: string, input: Record<string, unknown>): Record<string, unknown> {+ const images = strings(input.image);+ return {+ model,+ prompt: input.prompt,+ ...(images.length === 1 ? { image: images[0] } : images.length > 1 ? { image: images } : {}),+ size: SEEDREAM_SIZES[String(input.quality)]![String(input.aspect_ratio)]!,+ output_format: input.output_format,+ response_format: "url",+ watermark: false,+ };+}++function minimaxVideoBody(model: string, input: Record<string, unknown>): Record<string, unknown> {+ return {+ model,+ content: contentArray(input),+ resolution: input.resolution,+ duration: input.duration,+ ...(typeof input.ratio === "string" ? { ratio: input.ratio } : {}),+ };+}++function capabilityKey(capability: CapabilityRef): string {+ return `${capability.module.name}@${capability.module.version}#${capability.name}`;+}++export const tokenDanceRoutes: readonly TokenDanceRoute[] = tokenDanceMappings.map((mapping) => {+ const protocol: TokenDanceProtocol = mapping.capability.module.name === "@hypit/minimax-h3" ? "minimax-video"+ : mapping.result === "image" ? "ark-image" : "ark-video";+ const body = protocol === "ark-video" ? arkVideoBody : protocol === "ark-image" ? arkImageBody : minimaxVideoBody;+ return {+ ...mapping,+ key: capabilityKey(mapping.capability),+ returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,+ protocol,+ mediaLimits: tokenDanceMediaLimits[protocol],+ 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);+ const model = selectWireModelForRequest(mapping, request);+ return {+ model,+ protocol,+ compile: async (resolve) => body(model, (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(tokenDanceRoutes.map((route) => [route.key, route]));++export function tokenDanceRouteForCapability(capability: CapabilityRef): TokenDanceRoute | undefined {+ return byCapability.get(capabilityKey(capability));+}diff --git a/packages/provider-tokendance/test/routes.test.ts b/packages/provider-tokendance/test/routes.test.tsnew file mode 100644index 00000000..eee5fbca--- /dev/null+++ b/packages/provider-tokendance/test/routes.test.ts@@ -0,0 +1,55 @@+import assert from "node:assert/strict";+import test from "node:test";+import { assertMappingCoversPorts } from "@hypit/generation";+import type { BlobRef, CanonicalValue } from "@hypit/protocol";+import { minimaxH3Ports, sealMinimaxH3Request } from "@hypit/minimax-h3";+import { seedancePorts, sealSeedanceRequest } from "@hypit/seedance";+import { seedream5LitePorts, sealSeedreamRequest } from "@hypit/seedream";++import { tokenDanceMappings } from "../src/mapping.js";+import { tokenDanceRouteForCapability } from "../src/routes.js";++const image: BlobRef = { kind: "blob", resource: "res_td_1", size: 3, mediaType: "image/png" };+const resolve = async () => "data:image/png;base64,AQID";+const SEEDANCE = { name: "@hypit/seedance", version: "1" };+const route = (module: { name: string; version: string }, name: string) => tokenDanceRouteForCapability({ module, name })!;++test("every TokenDance mapping covers its model's ports", () => {+ const tables = { ...seedancePorts, "seedream-5-lite": seedream5LitePorts, "minimax-h3": minimaxH3Ports };+ for (const mapping of tokenDanceMappings) {+ assertMappingCoversPorts(tables[mapping.capability.name as keyof typeof tables], mapping);+ }+});++test("Seedance frame requests become Ark content items with roles", async () => {+ const request = sealSeedanceRequest("seedance-2-mini", {+ prompt: ["turn"], firstFrame: [{ role: "image", artifact: image, fields: { personReference: true } }],+ resolution: ["720p"], aspectRatio: ["adaptive"], duration: [5], generateAudio: [true], webSearch: [false],+ });+ const body = await route(SEEDANCE, "seedance-2-mini").prepare(request as unknown as CanonicalValue).compile(resolve);+ assert.deepEqual(body, {+ model: "seedance-2.0-mini",+ content: [+ { type: "text", text: "turn" },+ { type: "image_url", image_url: { url: "data:image/png;base64,AQID" }, role: "first_frame" },+ ],+ resolution: "720p", ratio: "adaptive", duration: 5, generate_audio: true,+ });+});++test("Seedream quality and ratio select the Ark pixel size", async () => {+ const request = sealSeedreamRequest({+ prompt: ["a cup"], aspectRatio: ["9:16"], quality: ["ultra"], outputFormat: ["png"], nsfwCheck: [true],+ });+ const body = await route({ name: "@hypit/seedream", version: "1" }, "seedream-5-lite").prepare(request as unknown as CanonicalValue).compile(resolve);+ assert.deepEqual(body, {+ model: "seedream-5.0-lite", prompt: "a cup", size: "3040x5504", output_format: "png", response_format: "url", watermark: false,+ });+});++test("MiniMax text-to-video without an aspect ratio is reported unsupported", () => {+ const request = sealMinimaxH3Request({ prompt: ["a kite"], duration: [5] });+ const minimax = route({ name: "@hypit/minimax-h3", version: "1" }, "minimax-h3");+ const support = minimax.supports({ capability: minimax.capability, returns: minimax.returns, constraints: request as unknown as CanonicalValue });+ assert.equal(support.status, "unsupported");+});diff --git a/packages/video-cli/package.json b/packages/video-cli/package.jsonindex e9c407e4..54c45b2f 100644--- a/packages/video-cli/package.json+++ b/packages/video-cli/package.json@@ -23,7 +23,11 @@"@hypit/package-loader-node": "workspace:*","@hypit/project-context-node": "workspace:*","@hypit/protocol": "workspace:*",+ "@hypit/provider-hiapi": "workspace:*","@hypit/provider-hypihub": "workspace:*",+ "@hypit/provider-monid": "workspace:*",+ "@hypit/provider-pollo": "workspace:*",+ "@hypit/provider-tokendance": "workspace:*","@hypit/runtime": "workspace:*","@hypit/runtime-kit": "workspace:*","@hypit/runtime-host-node": "workspace:*",diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex aecd89af..9ee15624 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -183,6 +183,9 @@ importers:'@hypit/protocol':specifier: workspace:*version: link:packages/protocol+ '@hypit/provider-hiapi':+ specifier: workspace:*+ version: link:packages/provider-hiapi'@hypit/provider-hyperframes-local':specifier: workspace:*version: link:packages/provider-hyperframes-local@@ -195,6 +198,15 @@ importers:'@hypit/provider-media-local':specifier: workspace:*version: link:packages/provider-media-local+ '@hypit/provider-monid':+ specifier: workspace:*+ version: link:packages/provider-monid+ '@hypit/provider-pollo':+ specifier: workspace:*+ version: link:packages/provider-pollo+ '@hypit/provider-tokendance':+ specifier: workspace:*+ version: link:packages/provider-tokendance'@hypit/provider-whisperx-local':specifier: workspace:*version: link:packages/provider-whisperx-local@@ -2206,6 +2218,43 @@ importers:packages/protocol: {}+ packages/provider-hiapi:+ dependencies:+ '@hypit/endpoint-kit':+ specifier: workspace:*+ version: link:../endpoint-kit+ '@hypit/generation':+ specifier: workspace:*+ version: link:../generation+ '@hypit/protocol':+ specifier: workspace:*+ version: link:../protocol+ '@hypit/runtime':+ specifier: workspace:*+ version: link:../runtime+ '@hypit/runtime-kit':+ specifier: workspace:*+ version: link:../runtime-kit+ devDependencies:+ '@hypit/gpt-image':+ specifier: workspace:*+ version: link:../gpt-image+ '@hypit/grok-imagine':+ specifier: workspace:*+ version: link:../grok-imagine+ '@hypit/minimax-h3':+ specifier: workspace:*+ version: link:../minimax-h3+ '@hypit/nano-banana':+ specifier: workspace:*+ version: link:../nano-banana+ '@hypit/seedance':+ specifier: workspace:*+ version: link:../seedance+ '@hypit/seedream':+ specifier: workspace:*+ version: link:../seedream+packages/provider-hyperframes-local:dependencies:'@hyperframes/engine':@@ -2378,6 +2427,87 @@ importers:specifier: workspace:*version: link:../driver-node+ packages/provider-monid:+ dependencies:+ '@hypit/endpoint-kit':+ specifier: workspace:*+ version: link:../endpoint-kit+ '@hypit/generation':+ specifier: workspace:*+ version: link:../generation+ '@hypit/protocol':+ specifier: workspace:*+ version: link:../protocol+ '@hypit/runtime':+ specifier: workspace:*+ version: link:../runtime+ '@hypit/runtime-kit':+ specifier: workspace:*+ version: link:../runtime-kit+ devDependencies:+ '@hypit/seedance':+ specifier: workspace:*+ version: link:../seedance++ packages/provider-pollo:+ dependencies:+ '@hypit/endpoint-kit':+ specifier: workspace:*+ version: link:../endpoint-kit+ '@hypit/generation':+ specifier: workspace:*+ version: link:../generation+ '@hypit/protocol':+ specifier: workspace:*+ version: link:../protocol+ '@hypit/runtime':+ specifier: workspace:*+ version: link:../runtime+ '@hypit/runtime-kit':+ specifier: workspace:*+ version: link:../runtime-kit+ devDependencies:+ '@hypit/gpt-image':+ specifier: workspace:*+ version: link:../gpt-image+ '@hypit/grok-imagine':+ specifier: workspace:*+ version: link:../grok-imagine+ '@hypit/minimax-h3':+ specifier: workspace:*+ version: link:../minimax-h3+ '@hypit/nano-banana':+ specifier: workspace:*+ version: link:../nano-banana++ packages/provider-tokendance:+ dependencies:+ '@hypit/endpoint-kit':+ specifier: workspace:*+ version: link:../endpoint-kit+ '@hypit/generation':+ specifier: workspace:*+ version: link:../generation+ '@hypit/protocol':+ specifier: workspace:*+ version: link:../protocol+ '@hypit/runtime':+ specifier: workspace:*+ version: link:../runtime+ '@hypit/runtime-kit':+ specifier: workspace:*+ version: link:../runtime-kit+ devDependencies:+ '@hypit/minimax-h3':+ specifier: workspace:*+ version: link:../minimax-h3+ '@hypit/seedance':+ specifier: workspace:*+ version: link:../seedance+ '@hypit/seedream':+ specifier: workspace:*+ version: link:../seedream+packages/provider-whisperx-local:dependencies:'@hypit/endpoint-kit':@@ -3436,9 +3566,21 @@ importers:'@hypit/protocol':specifier: workspace:*version: link:../protocol+ '@hypit/provider-hiapi':+ specifier: workspace:*+ version: link:../provider-hiapi'@hypit/provider-hypihub':specifier: workspace:*version: link:../provider-hypihub+ '@hypit/provider-monid':+ specifier: workspace:*+ version: link:../provider-monid+ '@hypit/provider-pollo':+ specifier: workspace:*+ version: link:../provider-pollo+ '@hypit/provider-tokendance':+ specifier: workspace:*+ version: link:../provider-tokendance'@hypit/runtime':specifier: workspace:*version: link:../runtimediff --git a/skills/hypit/references/environment/model-and-provider.md b/skills/hypit/references/environment/model-and-provider.mdindex 51ef8ae5..7756eb76 100644--- a/skills/hypit/references/environment/model-and-provider.md+++ b/skills/hypit/references/environment/model-and-provider.md@@ -97,7 +97,7 @@ Model and Provider extension or a release containing them. A missing model or unis a capability question, while an expired credential is an account question.A user's existing service or deployment remains a normal choice. Its Provider does not need to be-officially bundled. When an execution-service choice remains open, the maintained+officially bundled. When the user names a partner service, the maintained[model and deployment service page](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)introduces independent partners and links their own documentation. Use an introduction when itscapabilities help this production. Partners have their own accounts, pricing and APIs and use thediff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.mdindex e7e17db7..f124aef6 100644--- a/skills/hypit/references/environment/profile.md+++ b/skills/hypit/references/environment/profile.md@@ -66,7 +66,10 @@ describe availability; the user's request and recorded choices establish what toWhen the path is undecided, share the practical alternatives and your recommendation before a newaccount connection, substantial installation or paid call. Ask for the choice that is actually-unresolved. Once the route is agreed, carry out ordinary setup and work with progress updates.+unresolved: the recommended HypiHub, which continues this flow unchanged, or a partner API, which+the user picks from [this page](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)+([中文](https://github.com/hypit-ai/hypit/blob/main/docs/zh/guide/service-partners.md)) without a list from you.+Once the route is agreed, carry out ordinary setup and work with progress updates.Their decision can cover preparation as a whole. Record it in[Brief](../creation/brief.md#brief-preserves-user-authority); the Profile implements that choice.[Paid scope](../production/builds.md#work-within-the-agreed-paid-scope) explains how the commission