@hypit/hypit 0.2.2 → 0.2.4

package/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`.

package/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:*"
+  }
+}

package/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;

package/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)}`}`);
+}

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

@@ -0,0 +1,2 @@
+export { createMonidProvider, monidProviderModuleRef } from "./provider.js";
+export type { CreateMonidProviderOptions } from "./provider.js";

package/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"),
+];

package/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,
+    })),
+  });
+}

package/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));
+}

package/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.