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(examples): add a project video Provider to the extension example (#250)
panxyingyyi02b37f0d0262
diff --git a/docs/guide/providers.md b/docs/guide/providers.mdindex 66beffd9..7495c357 100644--- a/docs/guide/providers.md+++ b/docs/guide/providers.md@@ -91,7 +91,36 @@ under `endpoints` and select it in `bindings` in the [Runtime Profile](./runtimeThe [complete project Provider example](https://github.com/hypit-ai/hypit/tree/main/examples/provider-package)demonstrates reference uploads, task receipts, collection and pricing using an illustrative API.-It also ships with the executable, so the Agent can adapt it without a repository checkout.+It also ships with the executable, so the Agent can adapt it without a repository checkout. It holds+two packages: `provider-images` for a generated image, and `provider-videos` for a generated video+whose service receives the wider reference vocabulary — images, videos, audio and first/last frames —+and returns its result through a separate collection step.++Implement the capability that matches your service's request shape; a service that renders both+images and video can declare both capabilities in one package. A service often supports a narrower+range than the Model's vocabulary allows, such as fewer resolutions or a lower maximum duration.+That difference belongs to the Provider: report it from the capability's `supports` so `plan` refuses+the request with a reason, rather than editing the shared Model or silently narrowing the author's+request.++## Model a remote video task++A service that renders video usually submits a job, polls it and then downloads the result, which+the Endpoint SDK expresses as three separate actions:++- `start` submits the request and returns `pending` with the service's task id. The HTTP bound covers+ the API call, not the render, so `start` returns as soon as the service accepts the job. Record the+ task id through `checkpoint` before returning, so an interrupted Build still names the remote work+ it began.+- `poll` returns `pending` while the job runs, `ready` when it finishes, or `failed` with the+ service's own error code. Return `wakeAfter(handle, delayMs)` to schedule the next check.+- `collect` downloads the finished media and stores it through `context.resources`, returning the+ Model's declared result value. Keeping collection separate from polling lets download capacity be+ configured independently of task capacity.++Inputs whose bytes do not exist until an upstream step runs stay ordinary graph edges. The URL+resolver passed to `compileWireRequest` is where your Provider uploads a reference and returns the+service's URL for it, so no other part of the system learns the service's upload protocol.## Prices and permissiondiff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.mdindex 5dc0a14d..cbdf75c7 100644--- a/docs/zh/guide/providers.md+++ b/docs/zh/guide/providers.md@@ -57,7 +57,19 @@ import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit[Endpoint SDK](https://github.com/hypit-ai/hypit/blob/main/packages/endpoint-kit/README.md) 维护处理接口、activation、资源声明和价格 API。将包编译为 JavaScript,由项目包管理器安装。在 [Runtime Profile](./runtime.md) 的 `endpoints` 中配置实例,并通过 `bindings` 选择它。-[完整项目 Provider 示例](https://github.com/hypit-ai/hypit/tree/main/examples/provider-package) 使用示意 API 展示参考上传、任务回执、结果收集与价格读取。示例随执行包分发,Agent 无需仓库 checkout 就能读取和改写。+[完整项目 Provider 示例](https://github.com/hypit-ai/hypit/tree/main/examples/provider-package) 使用示意 API 展示参考上传、任务回执、结果收集与价格读取。示例随执行包分发,Agent 无需仓库 checkout 就能读取和改写。它包含两个包:`provider-images` 对应生成图像,`provider-videos` 对应生成视频——后者的服务接收更宽的参考词汇(图像、视频、音频以及首尾帧),并通过独立的结果收集步骤返回产物。++实现与服务请求形态相匹配的那个 Capability;同时生成图像和视频的服务可以在同一个包里声明两个 Capability。服务实际支持的范围常常比 Model 词汇表更窄,例如分辨率更少或最长时长更低。这个差异属于 Provider:在 Capability 的 `supports` 中报告它,让 `plan` 带原因拒绝请求,而不是修改共享 Model 或悄悄收窄作者的请求。++## 为远程视频任务建模++渲染视频的服务通常先提交任务、再轮询、最后下载结果,Endpoint SDK 将其表达为三个独立动作:++- `start` 提交请求并以该服务的任务 id 返回 `pending`。HTTP 超时约束的是这次 API 调用而非渲染本身,因此 `start` 在服务受理任务后立即返回。返回前通过 `checkpoint` 记录任务 id,这样即使 Build 被中断,也能指出它已发起的远程工作。+- `poll` 在任务运行期间返回 `pending`,完成时返回 `ready`,失败时带服务自身的错误码返回 `failed`。用 `wakeAfter(handle, delayMs)` 安排下一次检查。+- `collect` 下载已完成的素材,通过 `context.resources` 存储,并返回 Model 声明的结果值。把收集与轮询分离,可以让下载并发与任务并发分别配置。++字节尚不存在、要等上游步骤产出的输入,仍是普通图边。`compileWireRequest` 接收的 URL resolver 就是 Provider 上传参考并返回服务 URL 的位置,系统的其他部分因此无需了解该服务的上传协议。## 价格与授权diff --git a/examples/provider-package/README.md b/examples/provider-package/README.mdindex 19afa7f3..99ae5cea 100644--- a/examples/provider-package/README.md+++ b/examples/provider-package/README.md@@ -1,10 +1,23 @@# A project-owned Provider-This complete package demonstrates an asynchronous image service through the public Hypit SDK.-The service protocol below is **illustrative**, not a live vendor API. Replace its mapping and-transport with the selected service's documented operations. The lifecycle test exercises the-example without a paid request. Implement the capabilities needed by the production; a service's-entire catalogue is not required.+This example shows a service that Hypit's official Distribution does not ship, implemented as a+project package through the public Hypit SDK. Two packages cover the two request shapes a service+usually differs on:++| Package | Model | Request | Lifecycle |+| --- | --- | --- | --- |+| `packages/provider-images` | `@hypit/gpt-image@1#gpt-image-2` | one image, optional references | asynchronous |+| `packages/provider-videos` | `@hypit/seedance@1#seedance-2-mini` | one video, references and frames | asynchronous |++Both service protocols are **illustrative**, not live vendor APIs. Replace the mapping and transport+with the selected service's documented operations. The lifecycle tests exercise the examples without+a paid request. Implement the capabilities needed by the production; a service's entire catalogue is+not required.++The video example is the one to read when the service renders **video**. A video request carries the+whole reference vocabulary — images, videos, audio and first/last frames — and the result is a large+remote task rather than a returned file. This is the shape most third-party video services use, and+the shape the official Distribution cannot supply for a service it does not know.## Follow one request@@ -46,25 +59,84 @@ does not claim remote cancellation.source and preserves the response with a concise description. It reads no graph and invents nofuture media duration. Rates and credentials do not supply spending permission.+## Follow a video request++A Seedance request reaches `@hypit/seedance@1#seedance-2-mini` and returns a generated video-set.+The Model declares the request; this Provider decides how the service receives it. Four things+differ from the image example, and each is the reason the video example exists.++**The reference vocabulary is wider, and each role maps to its own field.** The Model declares+`referenceImage`, `referenceVideo` and `referenceAudio` as separate ports precisely so each can map+to one wire field — a service that mixes them into one array cannot tell the roles apart. An image+reference also carries an optional `personReference` classification, which is why those ports use+`itemObject` rather than `urlArray`: the item field travels with the URL it belongs to.++```json+{ "references": [{ "url": "https://…/reference.png", "person": true }] }+```++`firstFrame` and `lastFrame` accept at most one item each, so their body fields are URLs.+This illustrative service accepts their optional person classification on `POST /uploads` through+`x-person-reference: true` or `false`. Their mappings declare `resourceFields: ["personReference"]`,+and the URL resolver sends that header when supplied. Replace this with the real service’s+documented transport; a field that the service cannot carry must be refused, never discarded.++**The service's range is narrower than the Model's, and the Provider states that.** Seedance 2 Mini+admits 480p/720p and 4–15 seconds; this illustrative service renders 720p up to 10 seconds. The+Model is not edited for that. `supports` reports the difference before submission, so `plan` refuses+the request with a reason instead of failing a paid job downstream:++```+This service renders at most 10 seconds, not 12+```++Do not widen the Model to fit one service. Do not silently clamp the author's number either — the+author wrote 12 seconds, and a 10-second result is a different video.++**Submission is an enqueue, not the render.** `start` returns as soon as the service acknowledges a+task, and the HTTP bound covers the API call, not the minutes the render may take. `poll` returns+`pending` while the task is `queued` or `running`, and the task id is checkpointed before `start`+returns, so an interrupted Build still names the remote work it began.++**The result is fetched in a separate `collect` step.** A finished task carries a signed URL; the+account key goes only to the service's own API. `collect` downloads the media, stores it through+`context.resources` and returns the Model's declared value. Because `poll` and `collect` are+separate actions, download capacity is configured independently of task capacity.++A task that reports `succeeded` without an output URL is a service contract violation, not a pending+job, and fails loudly. A `failed` task keeps the service's own error code and the received task id+as evidence, and redacts URLs from the message it republishes.++`assertMappingCoversPorts` checks declared ports and required item fields. Optional fields need+request-level checks and transport tests as well:+a mapping that forgets a reference role or an item field fails at load rather than after a paid+generation returns the wrong video. Where a Model port is genuinely optional, `whenAbsent` states+what the service should receive when the author omits it — the service then gets the value the+author's request implies, not a field left to its own default. The lifecycle test asserts the+mapping against the Model's own port table.+## Make it a package in the production-Copy `packages/provider-images` into the video's `packages/`. Choose your own package name and change-`providerModule.name` with it. Implement the actual service protocol, including its request limits,-upload/download limits and any OAuth or cancellation behavior it really offers. Configure the-selected service address; `images.example` is a placeholder that cannot generate media.+Copy the package matching your service's request shape — `packages/provider-images` or+`packages/provider-videos` — into the video's `packages/`. Choose your own package name and change+`providerModule.name` with it. A service that renders both images and video can implement both+capabilities in one package; `defineEndpointPackage` accepts several. Implement the actual service+protocol, including its request limits, upload/download limits and any OAuth or cancellation+behavior it really offers. Configure the selected service address; `images.example` and+`videos.example` are placeholders that cannot generate media.Use the active `@hypit/hypit` version as a development dependency. Build and install with the-project's package manager. In this repository the example uses `workspace:*` for that dependency;-replace it with your selected release when copying it out. The `@hypit/driver-node` and-`@hypit/gpt-image` development dependencies serve the repository test only and can be removed from-the copied package. For example:+project's package manager. In this repository the examples use `workspace:*` for that dependency;+replace it with your selected release when copying it out. The `@hypit/driver-node` and model+development dependencies (`@hypit/gpt-image`, `@hypit/seedance`) serve the repository tests only and+can be removed from the copied package. For example:```bash-cd packages/provider-images+cd packages/provider-videosnpm installnpm run buildcd ../..-npm install ./packages/provider-images+npm install ./packages/provider-videos```The package ships JavaScript. Its `hypit.activation` exports a Profile-selected Runtime facet;@@ -73,10 +145,14 @@ loading project packages. Keep the chosen package version and lockfile with theMerge the endpoint, credential store and binding from `hypit.runtime.json` into the project'schosen Profile. Preserve its other services and resolve bindings explicitly. Once the user chooses-that account, `hypit auth login images.personal` securely enters the key into its declared store.+that account, `hypit auth login videos.personal` securely enters the key into its declared store.`plan` checks the requested parameters; `pricing` supplies the service's rates. Submitting a realgeneration follows the agreed production scope and spending authority.+The service decides whether an Endpoint needs its own credential slot at all. A service that+authenticates through the platform it runs on, or one reached at a private address, may declare no+credentials or a non-secret account name; `defineEndpointPackage` takes whichever the service has.+## Owners- `src/provider.ts`: exact capability, mapping, service support, task lifecycle, pricing and capacity.diff --git a/examples/provider-package/hypit.runtime.json b/examples/provider-package/hypit.runtime.jsonindex c414c7c1..7fbbf88d 100644--- a/examples/provider-package/hypit.runtime.json+++ b/examples/provider-package/hypit.runtime.json@@ -6,7 +6,14 @@"images.personal": {"use": "@example/provider-images","config": { "baseUrl": "https://images.example", "apiKey": { "store": "platform", "key": "images.personal" } }+ },+ "videos.personal": {+ "use": "@example/provider-videos",+ "config": { "baseUrl": "https://videos.example", "apiKey": { "store": "platform", "key": "videos.personal" } }}},- "bindings": { "@hypit/gpt-image@1#gpt-image-2": "images.personal" }+ "bindings": {+ "@hypit/gpt-image@1#gpt-image-2": "images.personal",+ "@hypit/seedance@1#seedance-2-mini": "videos.personal"+ }}diff --git a/examples/provider-package/packages/provider-videos/package.json b/examples/provider-package/packages/provider-videos/package.jsonnew file mode 100644index 00000000..1020edf2--- /dev/null+++ b/examples/provider-package/packages/provider-videos/package.json@@ -0,0 +1,11 @@+{+ "name": "@example/provider-videos",+ "version": "0.0.0",+ "private": true,+ "type": "module",+ "hypit": { "activation": "./dist/activation.js" },+ "exports": { ".": "./dist/provider.js" },+ "files": ["dist"],+ "scripts": { "build": "tsc -p tsconfig.json" },+ "devDependencies": { "@hypit/hypit": "workspace:*", "typescript": "5.9.3", "@hypit/driver-node": "workspace:*", "@hypit/seedance": "workspace:*" }+}diff --git a/examples/provider-package/packages/provider-videos/src/activation.ts b/examples/provider-package/packages/provider-videos/src/activation.tsnew file mode 100644index 00000000..d236fac6--- /dev/null+++ b/examples/provider-package/packages/provider-videos/src/activation.ts@@ -0,0 +1,24 @@+import {+ createRuntimeEndpointAdapterFacet, runtimeConfigCredentialRef, runtimeConfigExact,+ runtimeConfigObject, runtimeConfigPositiveInteger, runtimeConfigString,+} from "@hypit/hypit/runtime-kit";+import { createVideoProvider, providerModule } from "./provider.js";++export default {+ format: "hypit.node-package@1" as const,+ hostFacets: [createRuntimeEndpointAdapterFacet({+ use: providerModule.name,+ activate(context) {+ const config = runtimeConfigObject(context.config, "Video service");+ runtimeConfigExact(config, ["baseUrl", "apiKey", "concurrency", "pollIntervalMs"], "Video service");+ const baseUrl = runtimeConfigString(config.baseUrl, "Video service baseUrl");+ const apiKey = runtimeConfigCredentialRef(config.apiKey, "Video service apiKey");+ if (!baseUrl || !apiKey || !context.pool) throw new Error("Video service requires baseUrl, apiKey and pool");+ return { endpoint: createVideoProvider({+ instance: context.instance, pool: context.pool, baseUrl, apiKey,+ concurrency: runtimeConfigPositiveInteger(config.concurrency, "concurrency") ?? 1,+ pollIntervalMs: runtimeConfigPositiveInteger(config.pollIntervalMs, "pollIntervalMs") ?? 5_000,+ }) };+ },+ })],+};diff --git a/examples/provider-package/packages/provider-videos/src/provider.ts b/examples/provider-package/packages/provider-videos/src/provider.tsnew file mode 100644index 00000000..daf58742--- /dev/null+++ b/examples/provider-package/packages/provider-videos/src/provider.ts@@ -0,0 +1,181 @@+import { canonicalize, defineEndpointPackage, wakeAfter } from "@hypit/hypit/endpoint-kit";+import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit/endpoint-kit";+import {+ compileWireRequest, generationTypes, mappingSupportsRequest,+ sealGeneratedVideoSet, selectWireModelForRequest,+} from "@hypit/hypit/generation";+import type { GenerationRequest, GenerationWireMapping } from "@hypit/hypit/generation";++export const providerModule = { name: "@example/provider-videos", version: "1" } as const;+export const capability = { module: { name: "@hypit/seedance", version: "1" }, name: "seedance-2-mini" } as const;++// This example service implements only this subset of the model. Its API is described in README.+export const mapping: GenerationWireMapping = {+ capability, result: "video", routes: [{ model: "seedance-2-mini" }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ duration: { as: "value", field: "duration" },+ resolution: { as: "value", field: "resolution" },+ aspectRatio: { as: "value", field: "ratio" },+ generateAudio: { as: "value", field: "audio" },+ webSearch: { as: "value", field: "search" },+ referenceImage: { as: "itemObject", field: "references", urlKey: "url", fieldKeys: { personReference: "person" } },+ referenceVideo: { as: "itemObject", field: "videoReferences", urlKey: "url", fieldKeys: { personReference: "person" } },+ referenceAudio: { as: "urlArray", field: "audioReferences" },+ firstFrame: { as: "url", field: "firstFrame", resourceFields: ["personReference"] },+ lastFrame: { as: "url", field: "lastFrame", resourceFields: ["personReference"] },+ },+};++// This service renders a narrower band than the model vocabulary allows, which it reports rather+// than widening: Seedance 2 Mini declares 480p/720p and 4–15 seconds, and this service renders 720p+// up to 10 seconds. The Model is unchanged; the difference belongs to this Endpoint.+const SUPPORTED_RESOLUTION = "720p";+const SUPPORTED_SECONDS = 10;++function object(value: unknown): Record<string, unknown> {+ if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected service object");+ return value as Record<string, unknown>;+}+function text(value: unknown): string {+ if (typeof value !== "string" || value.length === 0) throw new Error("Expected nonempty service text");+ return value;+}+// This illustrative service documents these fields as its public failure evidence.+function publicFailure(value: unknown): { code: string; message: string } | undefined {+ if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;+ const error = value as Record<string, unknown>;+ if (typeof error.code !== "string" || typeof error.message !== "string") return undefined;+ return { code: error.code, message: error.message.replace(/https?:\/\/\S+/giu, "[redacted-url]") };+}+function address(value: string): string {+ const url = new URL(value);+ if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) {+ throw new Error("Service URLs require HTTPS or loopback HTTP");+ }+ return url.href;+}++function serviceSupport(request: EndpointRequest) {+ const ports = (request.constraints as unknown as GenerationRequest).ports;+ const duration = ports.duration?.[0];+ if (typeof duration === "number" && duration > SUPPORTED_SECONDS) {+ return { status: "unsupported" as const,+ reason: `This service renders at most ${SUPPORTED_SECONDS} seconds, not ${duration}` };+ }+ const resolution = ports.resolution?.[0];+ if (resolution !== undefined && String(resolution) !== SUPPORTED_RESOLUTION) {+ return { status: "unsupported" as const,+ reason: `This service renders at ${SUPPORTED_RESOLUTION}, not ${String(resolution)}` };+ }+ return mappingSupportsRequest(mapping, request.constraints)+ ? { status: "supported" as const }+ : { status: "unsupported" as const, reason: "This service does not accept one of the requested inputs" };+}++export function createVideoProvider(options: {+ instance: string; pool: string; baseUrl: string; apiKey: CredentialRef;+ concurrency?: number; pollIntervalMs?: number; fetch?: typeof globalThis.fetch;+}) {+ const base = address(options.baseUrl).replace(/\/$/u, "");+ const fetcher = options.fetch ?? globalThis.fetch;+ const interval = options.pollIntervalMs ?? 5_000;+ const key = (credentials: Readonly<Record<string, { secret: string }>>) => text(credentials.apiKey?.secret);+ async function json(path: string, secret: string, init: RequestInit = {}) {+ const response = await fetcher(`${base}${path}`, {+ ...init, headers: { ...init.headers, authorization: `Bearer ${secret}` },+ // Submission enqueues a remote job and answers immediately; the bound is for the API, not the render.+ signal: AbortSignal.timeout(120_000),+ });+ if (!response.ok) {+ let error: ReturnType<typeof publicFailure>;+ try { error = publicFailure(object(await response.json()).error); }+ catch { /* A missing public error body leaves the HTTP evidence intact. */ }+ const requestId = response.headers.get("x-request-id");+ throw Object.assign(new Error(`Video service ${init.method ?? "GET"} ${path} returned HTTP ${response.status}`+ + (requestId === null ? "" : `; request=${requestId}`)+ + (error === undefined ? "" : `; ${error.code}: ${error.message}`)),+ error === undefined ? {} : { code: error.code });+ }+ return object(await response.json());+ }+ const endpoint: AsyncEndpoint = {+ async start(context) {+ const supported = serviceSupport(context.need);+ if (supported.status === "unsupported") throw new Error(supported.reason);+ const secret = key(context.credentials);+ const authored = context.need.constraints as unknown as GenerationRequest;+ const model = selectWireModelForRequest(mapping, authored);+ // This service has no catalogue query; its known request limits were checked above.+ await context.reportProgress?.({ phase: `Preparing video request: ${model}` });+ const request = await compileWireRequest(mapping, authored,+ async (artifact, fields) => {+ const bytes = await context.resources.get(artifact.resource);+ if (bytes === undefined) throw new Error("Reference media is unavailable");+ const upload = await fetcher(`${base}/uploads`, {+ method: "POST", headers: { "content-type": artifact.mediaType, authorization: `Bearer ${secret}`,+ ...(fields?.personReference === undefined ? {} : { "x-person-reference": String(fields.personReference) }),+ },+ body: new Blob([new Uint8Array(bytes)]), signal: AbortSignal.timeout(120_000),+ });+ if (!upload.ok) throw new Error(`Video service POST /uploads returned HTTP ${upload.status}`);+ return address(text(object(await upload.json()).url));+ });+ await context.reportProgress?.({ phase: `Submitting video request: ${model}` });+ const task = await json("/videos", secret, {+ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(request),+ });+ const id = text(task.id), handle = { id }, receipt = { id };+ await context.checkpoint?.({ handle, receipt });+ return { ...wakeAfter(handle, interval), receipt };+ },+ async poll(context) {+ const id = text(object(context.handle).id);+ const task = await json(`/videos/${encodeURIComponent(id)}`, key(context.credentials));+ const status = text(task.status);+ if (status === "queued" || status === "running") {+ return wakeAfter({ id }, interval, Date.now(), { phase: status });+ }+ if (status === "failed") {+ const error = publicFailure(task.error);+ return { status: "failed", receipt: { id }, failure: {+ code: error?.code ?? "VIDEO_SERVICE_FAILED",+ message: `Video service task ${id} failed${error === undefined ? "" : `: ${error.message}`}`,+ } };+ }+ if (status !== "succeeded") throw new Error("Video service returned an unknown task state");+ // A completed task without a result URL is a service contract violation, not a pending job.+ return { status: "ready", handle: { id, url: address(text(task.output)) } };+ },+ async collect(context) {+ // The service returns a signed asset URL; account credentials go only to its API.+ const url = address(text(object(context.handle).url));+ await context.reportProgress?.({ phase: "Receiving generated video" });+ // One delivered video is bounded here; a larger file belongs with a streaming resource port.+ const response = await fetcher(url, { signal: AbortSignal.timeout(600_000) });+ if (!response.ok) throw new Error(`Video download returned HTTP ${response.status}`);+ const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();+ if (!mediaType?.startsWith("video/")) throw new Error("Video service returned a non-video result");+ const artifact = await context.resources.put(new Uint8Array(await response.arrayBuffer()), mediaType);+ return { status: "completed", result: { value: {+ kind: "inline", value: canonicalize(sealGeneratedVideoSet({ videos: [artifact] })),+ } } };+ },+ };+ return defineEndpointPackage({+ module: providerModule, facet: "videos", instance: options.instance, pool: options.pool,+ credentials: { apiKey: options.apiKey }, credentialInputs: { apiKey: { label: "Video service API key" } },+ defaultConcurrency: options.concurrency ?? 1,+ actionLimits: { submit: { concurrency: 1 }, poll: { concurrency: 4 }, collect: { concurrency: 2 } },+ pricing: { kind: "page", url: `${base}/pricing` },+ async readPricing(context) {+ const model = selectWireModelForRequest(mapping, context.request.constraints as unknown as GenerationRequest,+ context.request.pendingInputs?.map((input) => input.input));+ const path = `/rates?model=${encodeURIComponent(model)}`;+ const source = `${base}${path}`;+ const rates = await json(path, key(await context.credentials()));+ return [{ source, data: canonicalize(rates), summary: text(rates.description) }];+ },+ capabilities: [{ capability, returns: generationTypes.videoSet, lifecycle: "asynchronous", supports: serviceSupport, endpoint }],+ });+}diff --git a/examples/provider-package/packages/provider-videos/test/provider.test.ts b/examples/provider-package/packages/provider-videos/test/provider.test.tsnew file mode 100644index 00000000..18ff39c6--- /dev/null+++ b/examples/provider-package/packages/provider-videos/test/provider.test.ts@@ -0,0 +1,201 @@+import assert from "node:assert/strict";+import test from "node:test";+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";+import { sealSeedanceRequest } from "@hypit/seedance";+import type { BlobRef, EndpointStartContext } from "@hypit/hypit/endpoint-kit";+import { canonicalize } from "@hypit/hypit/endpoint-kit";+import { generationTypes } from "@hypit/hypit/generation";+import { assertMappingCoversPorts } from "@hypit/hypit/generation";+import { seedancePorts } from "@hypit/seedance";+import { capability, createVideoProvider, mapping } from "../src/provider.js";++test("project video Provider accounts for every port the Seedance Model declares", () => {+ // The check that turns a forgotten reference role or item field into a load-time failure+ // instead of a paid generation returning the wrong video.+ assertMappingCoversPorts(seedancePorts["seedance-2-mini"], mapping);+});++test("project video Provider uploads a reference, retains its receipt and collects the generated video", async () => {+ const resources = new MemoryResourceStore();+ const source = await resources.put(new Uint8Array([1, 2, 3]), "image/png");+ const calls: string[] = [];+ const progress: string[] = [];+ let checkpoint: unknown;+ const provider = createVideoProvider({+ instance: "videos.personal", pool: "videos.personal", baseUrl: "https://videos.example",+ apiKey: { store: "os", key: "videos.personal" }, pollIntervalMs: 0,+ fetch: async (input, init) => {+ const url = new URL(String(input)); calls.push(url.pathname);+ if (url.hostname === "assets.example") {+ assert.equal(init?.signal === undefined, false);+ assert.equal(progress.at(-1), "Receiving generated video");+ return new Response(new Uint8Array([4, 5, 6]), { headers: { "content-type": "video/mp4" } });+ }+ assert.equal((init?.headers as Record<string, string>).authorization, "Bearer test-key");+ if (url.pathname === "/rates") return Response.json({ description: "$0.40 per second of video", unit: "second", usd: 0.4 });+ if (url.pathname === "/uploads") {+ assert.equal(progress.at(-1), "Preparing video request: seedance-2-mini");+ assert.deepEqual(new Uint8Array(await (init?.body as Blob).arrayBuffer()), new Uint8Array([1, 2, 3]));+ return Response.json({ url: "https://assets.example/reference.png" });+ }+ if (url.pathname === "/videos") {+ assert.equal(progress.at(-1), "Submitting video request: seedance-2-mini");+ assert.deepEqual(JSON.parse(String(init?.body)), {+ model: "seedance-2-mini",+ input: {+ prompt: "A slow push-in", duration: 5, resolution: "720p", ratio: "9:16",+ audio: true, search: false,+ references: [{ url: "https://assets.example/reference.png", person: true }],+ },+ });+ return Response.json({ id: "received-job" });+ }+ if (url.pathname === "/videos/received-job") {+ assert.deepEqual(checkpoint, { handle: { id: "received-job" }, receipt: { id: "received-job" } });+ return Response.json({ status: "succeeded", output: "https://assets.example/output.mp4" });+ }+ throw new Error(`Unexpected path ${url.pathname}`);+ },+ });+ const constraints = canonicalize(sealSeedanceRequest("seedance-2-mini", {+ prompt: ["A slow push-in"],+ duration: [5],+ resolution: ["720p"],+ aspectRatio: ["9:16"],+ generateAudio: [true],+ webSearch: [false],+ referenceImage: [{ role: "image", artifact: source, fields: { personReference: true } }],+ }));+ const need = { id: "need:example", capability, returns: generationTypes.videoSet, constraints, result: "record:example" } as const;+ const registry = new EndpointRegistry(); await provider.install(registry);+ const resolution = registry.resolve(need);+ assert.equal(resolution.status, "resolved");+ assert.equal(resolution.registration.kind, "asynchronous");+ const endpoint = resolution.registration.endpoint;+ const context: EndpointStartContext = {+ need, command: { kind: "fulfill-need", id: "command:example", need }, operation: "operation:example",+ resources, credentials: { apiKey: { secret: "test-key" } },+ checkpoint: async (value) => { checkpoint = value; },+ reportProgress: async (value) => { progress.push(value.phase); },+ };+ const pricing = await provider.readPricing!({ request: need, credentials: async () => context.credentials });+ assert.equal(pricing[0]?.summary, "$0.40 per second of video");+ const start = await endpoint.start(context); assert.equal(start.status, "pending");+ const ready = await endpoint.poll({ ...context, handle: start.handle }); assert.equal(ready.status, "ready");+ const collected = await endpoint.collect!({ ...context, handle: ready.handle }); assert.equal(collected.status, "completed");+ assert.equal(collected.result.value.kind, "inline");+ const videos = (collected.result.value.value as unknown as { videos: BlobRef[] }).videos;+ assert.equal(videos[0]?.mediaType, "video/mp4");+ assert.deepEqual(await resources.get(videos[0]!.resource), new Uint8Array([4, 5, 6]));+ assert.deepEqual(calls, ["/rates", "/uploads", "/videos", "/videos/received-job", "/output.mp4"]);+ assert.deepEqual(progress, ["Preparing video request: seedance-2-mini", "Submitting video request: seedance-2-mini", "Receiving generated video"]);+});++test("project video Provider reports its narrower service range without changing the model", async () => {+ const provider = createVideoProvider({+ instance: "videos.personal", pool: "videos.personal", baseUrl: "https://videos.example",+ apiKey: { store: "os", key: "videos.personal" },+ });+ const need = (ports: Parameters<typeof sealSeedanceRequest>[1]) => ({+ id: "need:range", capability, returns: generationTypes.videoSet,+ constraints: canonicalize(sealSeedanceRequest("seedance-2-mini", ports)), result: "record:range",+ });+ const prompted = { prompt: ["A slow push-in"], generateAudio: [true], webSearch: [false] };+ const supported = provider.offers[0]!.supports!(+ need({ ...prompted, duration: [5], resolution: ["720p"], aspectRatio: ["9:16"] }));+ assert.equal(supported.status, "supported");+ // The Model admits both of these; this Endpoint is what narrows them.+ const tooLong = provider.offers[0]!.supports!(need({ ...prompted, duration: [12], resolution: ["720p"], aspectRatio: ["9:16"] }));+ assert.equal(tooLong.status, "unsupported");+ assert.match(tooLong.status === "unsupported" ? tooLong.reason : "", /at most 10 seconds, not 12/u);+ const tooSmall = provider.offers[0]!.supports!(need({ ...prompted, duration: [5], resolution: ["480p"], aspectRatio: ["9:16"] }));+ assert.equal(tooSmall.status, "unsupported");+ assert.match(tooSmall.status === "unsupported" ? tooSmall.reason : "", /renders at 720p, not 480p/u);+});++test("project video Provider keeps the received task id when the render fails remotely", async () => {+ const calls: string[] = [];+ let checkpointed = false;+ const provider = createVideoProvider({+ instance: "videos.personal", pool: "videos.personal", baseUrl: "https://videos.example",+ apiKey: { store: "os", key: "videos.personal" }, pollIntervalMs: 0,+ fetch: async (input) => {+ const path = new URL(String(input)).pathname;+ calls.push(path);+ if (path === "/videos") return Response.json({ id: "job-one" });+ return Response.json({+ status: "failed",+ error: { code: "content_filtered", message: "Rejected; see https://videos.example/private?token=hidden" },+ debug: { secret: "not-public" },+ });+ },+ });+ const need = {+ id: "need:failure", capability, returns: generationTypes.videoSet,+ constraints: canonicalize(sealSeedanceRequest("seedance-2-mini", {+ prompt: ["A slow push-in"], duration: [5], resolution: ["720p"], aspectRatio: ["9:16"],+ generateAudio: [true], webSearch: [false],+ })),+ result: "record:failure",+ };+ const registry = new EndpointRegistry();+ await provider.install(registry);+ const resolved = registry.resolve(need);+ assert.equal(resolved.status, "resolved");+ assert.equal(resolved.registration.kind, "asynchronous");+ const endpoint = resolved.registration.endpoint;+ const context: EndpointStartContext = {+ command: { kind: "fulfill-need", id: "command:failure", need }, need, operation: "operation:failure",+ resources: new MemoryResourceStore(), credentials: { apiKey: { secret: "test-key" } },+ checkpoint: async () => { checkpointed = true; },+ };+ const started = await endpoint.start(context);+ assert.equal(started.status, "pending");+ const failed = await endpoint.poll({ ...context, handle: started.handle });+ assert.equal(failed.status, "failed");+ assert.equal(failed.status === "failed" ? failed.failure.code : "", "content_filtered");+ assert.match(failed.status === "failed" ? failed.failure.message : "", /task job-one failed/u);+ // Public evidence is preserved and the redacted URL is not republished.+ assert.doesNotMatch(failed.status === "failed" ? failed.failure.message : "", /not-public|token=hidden|test-key/u);+ assert.deepEqual(failed.receipt, { id: "job-one" });+ assert.equal(checkpointed, true);+ assert.deepEqual(calls, ["/videos", "/videos/job-one"]);+});++test("first and last frame person flags reach the upload API, including false", async () => {+ const resources = new MemoryResourceStore();+ const image = await resources.put(new Uint8Array([1]), "image/png");+ const flags: (string | null)[] = [];+ const provider = createVideoProvider({+ instance: "videos.personal", pool: "videos.personal", baseUrl: "https://videos.example",+ apiKey: { store: "os", key: "example" },+ fetch: async (input, init) => {+ const path = new URL(String(input)).pathname;+ if (path === "/uploads") {+ flags.push(new Headers(init?.headers).get("x-person-reference"));+ return Response.json({ url: `https://assets.example/frame-${flags.length}.png` });+ }+ assert.equal(path, "/videos");+ const sent = JSON.parse(String(init?.body));+ assert.equal(sent.input.firstFrame, "https://assets.example/frame-1.png");+ assert.equal(sent.input.lastFrame, "https://assets.example/frame-2.png");+ return Response.json({ id: "frames" });+ },+ });+ const need = { id: "need:frames", capability, returns: generationTypes.videoSet, result: "record:frames",+ constraints: canonicalize(sealSeedanceRequest("seedance-2-mini", {+ prompt: ["A presenter"], duration: [5], resolution: ["720p"], aspectRatio: ["9:16"],+ generateAudio: [true], webSearch: [false],+ firstFrame: [{ role: "image", artifact: image, fields: { personReference: true } }],+ lastFrame: [{ role: "image", artifact: image, fields: { personReference: false } }],+ })),+ };+ const registry = new EndpointRegistry(); await provider.install(registry);+ const selected = registry.resolve(need);+ assert.equal(selected.status, "resolved");+ assert.equal(selected.registration.kind, "asynchronous");+ await selected.registration.endpoint.start({ need, command: { kind: "fulfill-need", id: "frames", need },+ operation: "frames", resources, credentials: { apiKey: { secret: "test" } },+ });+ assert.deepEqual(flags, ["true", "false"]);+});diff --git a/examples/provider-package/packages/provider-videos/tsconfig.json b/examples/provider-package/packages/provider-videos/tsconfig.jsonnew file mode 100644index 00000000..741d98f2--- /dev/null+++ b/examples/provider-package/packages/provider-videos/tsconfig.json@@ -0,0 +1,9 @@+{+ "compilerOptions": {+ "target": "ES2023", "module": "NodeNext", "moduleResolution": "NodeNext",+ "lib": ["ES2023", "DOM"], "strict": true, "noUncheckedIndexedAccess": true,+ "exactOptionalPropertyTypes": true, "verbatimModuleSyntax": true,+ "declaration": true, "rootDir": "src", "outDir": "dist", "skipLibCheck": true+ },+ "include": ["src/**/*.ts"]+}diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 265e81c9..aecd89af 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -364,6 +364,21 @@ importers:specifier: 5.9.3version: 5.9.3+ examples/provider-package/packages/provider-videos:+ devDependencies:+ '@hypit/driver-node':+ specifier: workspace:*+ version: link:../../../../packages/driver-node+ '@hypit/hypit':+ specifier: workspace:*+ version: link:../../../..+ '@hypit/seedance':+ specifier: workspace:*+ version: link:../../../../packages/seedance+ typescript:+ specifier: 5.9.3+ version: 5.9.3+examples/semantic-composition/packages/chat-scene:devDependencies:'@hypit/hypit':diff --git a/skills/hypit/references/environment/model-and-provider.md b/skills/hypit/references/environment/model-and-provider.mdindex ae9e606b..51ef8ae5 100644--- a/skills/hypit/references/environment/model-and-provider.md+++ b/skills/hypit/references/environment/model-and-provider.md@@ -164,6 +164,14 @@ actual protocol. It demonstrates reference upload, receipt, polling, collection,without introducing a second scheduler. For a new Model, the Model SDK README includes the definitionand author-package activation example.+It ships two packages, and the request shape decides which one to follow: `provider-images` for a+generated image, `provider-videos` for a generated video. A video service usually receives a wider+reference vocabulary — images, videos, audio and first/last frames, each role mapping to its own wire+field — and returns its result through a separate `collect` step after `poll` reports the job ready.+A service that only supports part of the Model's declared range, such as fewer resolutions or a lower+maximum duration, reports that from `supports` so `plan` refuses the request with a reason; the shared+Model stays unchanged and the author's number is never silently narrowed.+## Use the public SDK| Import | Responsibility |