@hypit/hypit 0.2.2 → 0.2.4

package/packages/credential-store-file/src/store.ts

@@ -1,5 +1,6 @@
+import { replaceFile } from "@hypit/file-io-node";
 import { randomUUID } from "node:crypto";
-import { mkdir, open, rename, rm, stat, unlink } from "node:fs/promises";
+import { mkdir, open, rm, stat, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { verifyCredentialRef } from "@hypit/runtime";
 import type { CredentialRef, CredentialValue, WritableCredentialStore } from "@hypit/runtime";
@@ -8,26 +9,6 @@ function missing(error: unknown): boolean {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
-/**
- * One process reads a credential for one Endpoint action while another action's refresh replaces
- * it, so a read handle and a replacement can reach the same document at the same instant. Windows
- * refuses to replace a file any handle still holds. Each document's work takes its turn instead,
- * keyed by path so separate Store instances over one directory share the same order. Keys are
- * independent: a turn on one document never delays another.
- */
-const documentTurns = new Map<string, Promise<unknown>>();
-
-function onDocument<T>(path: string, work: () => Promise<T>): Promise<T> {
-  const turn = (documentTurns.get(path) ?? Promise.resolve()).then(work, work);
-  // The successor waits for this turn to settle, not to succeed, and the last turn clears the path.
-  const settled = turn.then(() => undefined, () => undefined);
-  documentTurns.set(path, settled);
-  void settled.then(() => {
-    if (documentTurns.get(path) === settled) documentTurns.delete(path);
-  });
-  return turn;
-}
-
 function credentialValue(value: unknown): CredentialValue {
   if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid credential value");
   const record = value as Record<string, unknown>;
@@ -64,10 +45,6 @@ export class FileCredentialStore implements WritableCredentialStore {
   async resolve(ref: CredentialRef): Promise<CredentialValue | undefined> {
     if (!this.owns(ref)) return undefined;
     const path = this.#path(ref);
-    return await onDocument(path, async () => await this.#read(path));
-  }
-
-  async #read(path: string): Promise<CredentialValue | undefined> {
     try { await this.#privateDirectory(false); } catch (error) {
       if (missing(error)) return undefined;
       throw error;
@@ -93,25 +70,21 @@ export class FileCredentialStore implements WritableCredentialStore {
   async put(ref: CredentialRef, value: CredentialValue): Promise<void> {
     const path = this.#path(ref);
     const contents = JSON.stringify(credentialValue(value));
-    await onDocument(path, async () => {
-      await this.#privateDirectory(true);
-      const temporary = join(this.directory, `.write-${randomUUID()}.tmp`);
-      const file = await open(temporary, "wx", 0o600);
-      try {
-        try { await file.writeFile(`${contents}\n`, "utf8"); } finally { await file.close(); }
-        await rename(temporary, path);
-      } finally { await rm(temporary, { force: true }); }
-    });
+    await this.#privateDirectory(true);
+    const temporary = join(this.directory, `.write-${randomUUID()}.tmp`);
+    const file = await open(temporary, "wx", 0o600);
+    try {
+      try { await file.writeFile(`${contents}\n`, "utf8"); } finally { await file.close(); }
+      await replaceFile(temporary, path);
+    } finally { await rm(temporary, { force: true }); }
   }
 
   async delete(ref: CredentialRef): Promise<boolean> {
     const path = this.#path(ref);
     // Deletion never opens or decodes the old document.
-    return await onDocument(path, async () => {
-      try { await unlink(path); return true; } catch (error) {
-        if (missing(error)) return false;
-        throw error;
-      }
-    });
+    try { await unlink(path); return true; } catch (error) {
+      if (missing(error)) return false;
+      throw error;
+    }
   }
 }

package/packages/credential-store-os/runtime/windows-credential.ps1

@@ -35,8 +35,7 @@ switch ($Operation) {
     @{ found = $true; secret = [Convert]::ToBase64String($bytes) } | ConvertTo-Json -Compress
   }
   "write" {
-    $existing = Find-Credential
-    if ($null -ne $existing) { $vault.Remove($existing) }
+    # Add replaces the same resource/account; do not destroy the old value before it succeeds.
     $bytes = [Convert]::FromBase64String([string]$request.secret)
     $secret = [System.Text.Encoding]::UTF8.GetString($bytes)
     $credential = New-Object Windows.Security.Credentials.PasswordCredential(

package/packages/credential-store-os/src/store.ts

@@ -1,5 +1,5 @@
-import { execFile, spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { windowsCredential } from "./windows.js";
 
 import { verifyCredentialRef } from "@hypit/runtime";
 import type {
@@ -59,72 +59,6 @@ function macosDeleter(service: string): OsCredentialDeleter {
   });
 }
 
-type WindowsCredentialResult = {
-  readonly found?: boolean;
-  readonly deleted?: boolean;
-  readonly secret?: string;
-};
-
-const windowsScript = fileURLToPath(new URL("../runtime/windows-credential.ps1", import.meta.url));
-
-const windowsCredentialTimeoutMs = 10_000;
-
-function windowsCredential(
-  operation: "read" | "write" | "delete",
-  service: string,
-  account: string,
-  secret?: string,
-): Promise<WindowsCredentialResult> {
-  return new Promise((resolve, reject) => {
-    const child = spawn("powershell.exe", [
-      "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
-      "-File", windowsScript, "-Operation", operation,
-    ], { shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-    const fail = (error: Error): void => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      reject(error);
-    };
-    const timer = setTimeout(() => {
-      fail(new Error(`Windows credential ${operation} for ${account} timed out`));
-      child.kill("SIGKILL");
-    }, windowsCredentialTimeoutMs);
-    child.on("error", fail);
-    child.stdout.on("data", (chunk: Buffer) => {
-      stdout += chunk.toString("utf8");
-      if (stdout.length > 4 * 1024 * 1024) fail(new Error("Windows credential response is too large"));
-    });
-    child.stderr.on("data", (chunk: Buffer) => {
-      stderr += chunk.toString("utf8");
-      if (stderr.length > 64 * 1024) fail(new Error("Windows credential error is too large"));
-    });
-    child.on("close", (code) => {
-      if (settled) return;
-      clearTimeout(timer);
-      if (code !== 0) {
-        fail(new Error(`Windows credential ${operation} for ${account} failed${stderr.trim().length === 0 ? "" : `: ${stderr.trim()}`}`));
-        return;
-      }
-      try {
-        const result = JSON.parse(stdout.replace(/^\uFEFF/u, "").trim()) as WindowsCredentialResult;
-        settled = true;
-        resolve(result);
-      } catch {
-        fail(new Error(`Windows credential ${operation} returned an invalid response`));
-      }
-    });
-    child.stdin.end(JSON.stringify({
-      service,
-      account,
-      ...(secret === undefined ? {} : { secret: Buffer.from(secret, "utf8").toString("base64") }),
-    }));
-  });
-}
-
 function windowsBackend(): {
   readonly read: OsCredentialReader;
   readonly write: OsCredentialWriter;

package/packages/credential-store-os/src/windows.ts

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+type WindowsCredentialResult = {
+  readonly found?: boolean;
+  readonly deleted?: boolean;
+  readonly secret?: string;
+};
+
+const windowsScript = fileURLToPath(new URL("../runtime/windows-credential.ps1", import.meta.url));
+
+/** The OS adapter owns this one child; Node owns its timeout, bounded output and termination. */
+export function windowsCredential(
+  operation: "read" | "write" | "delete",
+  service: string,
+  account: string,
+  secret?: string,
+): Promise<WindowsCredentialResult> {
+  return new Promise((resolve, reject) => {
+    const child = execFile("powershell.exe", [
+      "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+      "-File", windowsScript, "-Operation", operation,
+    ], {
+      shell: false, windowsHide: true, encoding: "utf8", timeout: 10_000,
+      maxBuffer: 4 * 1024 * 1024,
+    }, (error, stdout, stderr) => {
+      if (error !== null) {
+        reject(new Error(`Windows credential ${operation} for ${account} failed`
+          + (error.code === undefined ? "" : ` (${error.code})`)
+          + (error.killed ? " (child terminated)" : "")
+          + (stderr.trim().length === 0 ? "" : `: ${stderr.trim()}`)));
+        return;
+      }
+      try { resolve(JSON.parse(stdout.replace(/^\uFEFF/u, "").trim()) as WindowsCredentialResult); }
+      catch { reject(new Error(`Windows credential ${operation} returned an invalid response`)); }
+    });
+    // A closed input pipe is an operation failure too. Do not leave the child waiting for a request.
+    child.stdin!.on("error", () => {
+      child.kill();
+      reject(new Error(`Windows credential ${operation} request could not be written`));
+    });
+    child.stdin!.end(JSON.stringify({
+      service, account,
+      ...(secret === undefined ? {} : { secret: Buffer.from(secret, "utf8").toString("base64") }),
+    }));
+  });
+}

package/packages/credential-store-platform/README.md

@@ -53,7 +53,8 @@ credential stored in a locker stays in that locker; a credential stored in a fil
 
 On macOS and Windows the credential is held by the platform locker, with exactly the rules of
 `@hypit/credential-store-os`: it is encrypted and access-controlled by the operating system, and it
-is not readable from another machine.
+follows that locker’s access and synchronization policy. Windows Credential Locker may roam
+credentials through the user’s Microsoft account.
 
 On Linux the credential is held by an owner-private document with exactly the rules of
 `@hypit/credential-store-file`: unencrypted JSON, one document per key, directory mode `0700`, file

package/packages/credential-store-platform/src/activation.ts

@@ -1,10 +1,10 @@
+import { join, resolve } from "node:path";
 import {
   createRuntimeCredentialStoreAdapterFacet,
   runtimeConfigExact,
   runtimeConfigObject,
   runtimeConfigString,
 } from "@hypit/runtime-kit";
-import { resolveCredentialDirectory } from "@hypit/credential-store-file";
 import { PlatformCredentialStore } from "./store.js";
 
 const platformCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet({
@@ -23,7 +23,7 @@ const platformCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet(
       value: new PlatformCredentialStore({
         // Linux uses the same directory the file Store uses by default, so a Profile
         // that switches between them on Linux finds the credential it stored.
-        directory: resolveCredentialDirectory(context.hostStateRoot, path, "platform CredentialStore"),
+        directory: path === undefined ? join(context.hostStateRoot, "credentials") : resolve(context.hostStateRoot, path),
         ...(service === undefined ? {} : { service }),
       }),
     };

package/packages/file-io-node/README.md

@@ -0,0 +1,20 @@
+# `@hypit/file-io-node`
+
+Node filesystem operations shared by file-backed adapters. This package has no knowledge of
+credentials, Build Results, Runtime or repository formats.
+
+`replaceFile(from, to)` publishes a complete file at a destination on the same filesystem. The
+caller owns creating and closing the source file, its contents and permissions, and temporary-file
+cleanup. Existing readers retain the old file; subsequent opens see the new file. The destination
+may be absent. Concurrent replacements are ordered by the filesystem, with the last replacement
+supplying the current value.
+
+POSIX uses Node's `rename`. Windows uses `SetFileInformationByHandle(FileRenameInfoEx)` with
+`REPLACE_IF_EXISTS | POSIX_SEMANTICS`, the same primitive previously owned by `build-result`.
+This avoids `MoveFileExW` rejecting replacement while another process has the destination open.
+The native structure layout comes from Koffi; constants are Windows API values.
+
+There is no pre-read, queue, lock file, retry or fallback. Windows filesystems must support this
+operation; unsupported operations, access denials and other I/O errors are reported to the caller.
+Read-only destinations are not overridden. The package does not promise power-loss durability or
+coordinate transactions across multiple files.

package/packages/file-io-node/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@hypit/file-io-node",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "koffi": "3.2.1"
+  }
+}

package/packages/file-io-node/src/index.ts

@@ -0,0 +1 @@
+export { replaceFile } from "./replace-file.js";

package/packages/{build-result → file-io-node}/src/replace-file-windows.ts

@@ -1,4 +1,4 @@
-import { toNamespacedPath } from "node:path";
+import { resolve, toNamespacedPath } from "node:path";
 import koffi from "koffi";
 
 const kernel = koffi.load("kernel32.dll");
@@ -35,7 +35,7 @@ function failure(syscall: string, from: string, to: string): Error {
  * https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/4217551b-d2c0-42cb-9dc1-69a716cf6d0c
  */
 export function replaceWindowsFile(from: string, to: string): void {
-  const filename = Buffer.from(toNamespacedPath(to), "utf16le");
+  const filename = Buffer.from(toNamespacedPath(resolve(to)), "utf16le");
   const nameOffset = koffi.offsetof(renameInfo, "FileName");
   // Win32 requires a NUL-terminated FileName even though FileNameLength excludes
   // that terminator. Buffer.alloc leaves the final WCHAR zero-initialized.
@@ -45,7 +45,7 @@ export function replaceWindowsFile(from: string, to: string): void {
   info.writeUInt32LE(filename.length, koffi.offsetof(renameInfo, "FileNameLength"));
   filename.copy(info, nameOffset);
 
-  const handle = createFile(toNamespacedPath(from), DELETE, SHARE_READ_WRITE_DELETE,
+  const handle = createFile(toNamespacedPath(resolve(from)), DELETE, SHARE_READ_WRITE_DELETE,
     null, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, 0) as number | bigint;
   if (handle === -1 || handle === -1n) throw failure("CreateFileW", from, to);
   try {

package/packages/generation/README.md

@@ -37,3 +37,9 @@ Media wire mappings (`url`, `urlArray`, `itemObject`) may declare `resourceField
 paths against the declared media fields. False, zero and empty strings remain values; omitted fields
 remain absent. The resolver implements the service protocol; this package knows no particular
 service or classification. Providers using custom transports carry those fields through that boundary.
+
+A Model item field being optional means authors may omit it. If a request supplies that field,
+`mappingSupportsRequest` and final wire compilation require the mapping to carry it through
+`fieldKeys` or `resourceFields`, including an explicit `false`. A service may support requests
+without a particular optional field and refuse requests that supply it; no field is silently dropped.
+Final compilation checks the whole request before resolving or uploading any reference.

package/packages/generation/src/mapping.ts

@@ -89,8 +89,9 @@ export function selectWireModelForRequest(
   request: GenerationRequest,
   pendingPorts: readonly string[] = [],
 ): string {
-  assert(mappingSupportsRequest(mapping, request),
-    `${mapping.capability.name} request contains a port this Provider cannot map`);
+  const unsupported = unsupportedRequestField(mapping, request);
+  assert(unsupported === undefined,
+    `${mapping.capability.name} request contains ${unsupported} this Provider cannot map`);
   const present = new Set(presentPorts(request));
   for (const port of pendingPorts) {
     assert(mapping.fields[port] !== undefined,
@@ -149,19 +150,38 @@ export async function compileWireRequest(
   return { model, input: canonicalize(input) };
 }
 
-/** Does this request only use ports this mapping can write? Needs no model package. */
-export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {
+/** Describe only a supplied value the mapping cannot carry; no model table or saved verdict. */
+function unsupportedRequestField(mapping: GenerationWireMapping, value: unknown): string | undefined {
   const request = value as GenerationRequest | undefined;
-  if (request === undefined || request.ports === null || typeof request.ports !== "object") return false;
-  return Object.keys(request.ports).every((port) => mapping.fields[port] !== undefined);
+  if (request === undefined || request === null || request.ports === null || typeof request.ports !== "object") {
+    return "invalid ports";
+  }
+  for (const [port, supplied] of Object.entries(request.ports)) {
+    const field = mapping.fields[port];
+    if (field === undefined) return `port ${port}`;
+    if (field.as !== "url" && field.as !== "urlArray" && field.as !== "itemObject") continue;
+    for (const item of supplied as readonly GenerationMediaValue[]) {
+      for (const name of Object.keys(item.fields ?? {})) {
+        if (!field.resourceFields?.includes(name)
+          && !(field.as === "itemObject" && Object.hasOwn(field.fieldKeys, name))) {
+          return `field ${port}.${name}`;
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Optional fields may be omitted by authors, but supplied fields must reach the service. */
+export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {
+  return unsupportedRequestField(mapping, value) === undefined;
 }
 
 /**
- * Prove one service mapping covers every port the model declares.
+ * Check structural port coverage and required item fields against the model declaration.
  *
- * This is the check the old hand-written per-model translators could not have:
- * a forgotten reference role or item field used to surface only after a paid
- * generation returned the wrong result.
+ * A service may omit optional item capabilities. mappingSupportsRequest and final compilation
+ * additionally refuse requests that actually supply such an unmapped field.
  */
 export function assertMappingCoversPorts(
   table: GenerationPortTable,

package/packages/media-execution/src/execute.ts

@@ -689,7 +689,7 @@ export async function executeNormalizeMedia(
       await runProcess({
         executable: env.ffmpegPath,
         argv: ["-y", ...visualInput, "-an", "-vf", filter,
-          "-frames:v", String(plan.frameCount), "-fps_mode", "cfr", ...encoderArgs, output],
+          "-frames:v", String(plan.frameCount), "-r", fps, "-fps_mode", "cfr", ...encoderArgs, output],
         timeoutMs: env.processTimeoutMs,
         maxStdoutBytes: 64 * 1024,
         ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
@@ -951,7 +951,8 @@ export async function executeTransformMedia(
       argv.push("-map", "0:v:0", "-an", "-vf", plan.videoFilters.join(","));
     }
     argv.push(
-      "-frames:v", String(plan.frameCount), "-fps_mode", "cfr",
+      "-frames:v", String(plan.frameCount),
+      "-r", `${media.timeline.frameRate.numerator}/${media.timeline.frameRate.denominator}`, "-fps_mode", "cfr",
       "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p",
       "-movflags", "+faststart", output,
     );

package/packages/media-execution/src/toolchain.ts

@@ -1,18 +1,14 @@
 import { execFile } from "node:child_process";
+import { mediaProcessEnv } from "./process-env.js";
 
 export type MediaToolchainState =
   | { readonly state: "ready"; readonly ffprobeVersion: string; readonly ffmpegVersion?: string }
   | { readonly state: "down" | "mismatch"; readonly detail: string };
 
-const REQUIRED_ENCODERS = ["aac", "libx264", "pcm_s16le"] as const;
-const REQUIRED_FILTERS = [
-  "aformat", "amix", "aresample", "asetpts", "atempo", "atrim",
-  "loop", "pad", "scale", "select", "setpts", "setsar", "trim",
-] as const;
-
-function run(executable: string, args: readonly string[]): Promise<{ ok: boolean; output: string }> {
+function run(executable: string, args: readonly string[], env: NodeJS.ProcessEnv): Promise<{ ok: boolean; output: string }> {
   return new Promise((resolve) => {
     execFile(executable, [...args], {
+      env,
       timeout: 15_000,
       shell: false,
       windowsHide: true,
@@ -29,22 +25,18 @@ function firstLine(value: string): string {
   return value.split(/\r?\n/u, 1)[0]?.trim() ?? "";
 }
 
-function missingNames(output: string, required: readonly string[]): readonly string[] {
-  return required.filter((name) => !new RegExp(`(?:^|\\s)${name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}(?:\\s|$)`, "mu")
-    .test(output));
-}
-
 /**
- * Compatibility probe for a deployment-owned FFmpeg toolchain. It deliberately
- * checks the commands the shared execution body uses instead of requiring one
- * blessed version number. A managed distribution may pin binaries separately;
- * a custom installation remains valid when it supplies the same capability.
+ * Check availability of the selected executables in their execution environment.
+ * This does not predict compatibility with every future media command: the execution
+ * implementation owns those commands and reports the tool's actual failure.
  */
 export async function probeMediaToolchain(options: {
   readonly ffprobePath: string;
   readonly ffmpegPath?: string;
+  readonly environment?: NodeJS.ProcessEnv;
 }): Promise<MediaToolchainState> {
-  const probeVersion = await run(options.ffprobePath, ["-version"]);
+  const env = options.environment ?? mediaProcessEnv();
+  const probeVersion = await run(options.ffprobePath, ["-version"], env);
   if (!probeVersion.ok) {
     return { state: "down", detail: `${options.ffprobePath} is unavailable: ${probeVersion.output}` };
   }
@@ -52,28 +44,10 @@ export async function probeMediaToolchain(options: {
   if (ffprobeVersion.length === 0) return { state: "mismatch", detail: "ffprobe returned no version" };
   if (options.ffmpegPath === undefined) return { state: "ready", ffprobeVersion };
 
-  const [ffmpegVersionResult, encoders, filters] = await Promise.all([
-    run(options.ffmpegPath, ["-version"]),
-    run(options.ffmpegPath, ["-hide_banner", "-encoders"]),
-    run(options.ffmpegPath, ["-hide_banner", "-filters"]),
-  ]);
+  const ffmpegVersionResult = await run(options.ffmpegPath, ["-version"], env);
   if (!ffmpegVersionResult.ok) {
     return { state: "down", detail: `${options.ffmpegPath} is unavailable: ${ffmpegVersionResult.output}` };
   }
-  if (!encoders.ok || !filters.ok) {
-    return { state: "mismatch", detail: "ffmpeg could not enumerate its encoders and filters" };
-  }
-  const missingEncoders = missingNames(encoders.output, REQUIRED_ENCODERS);
-  const missingFilters = missingNames(filters.output, REQUIRED_FILTERS);
-  if (missingEncoders.length > 0 || missingFilters.length > 0) {
-    return {
-      state: "mismatch",
-      detail: [
-        missingEncoders.length === 0 ? "" : `missing encoders ${missingEncoders.join(", ")}`,
-        missingFilters.length === 0 ? "" : `missing filters ${missingFilters.join(", ")}`,
-      ].filter(Boolean).join("; "),
-    };
-  }
   const ffmpegVersion = firstLine(ffmpegVersionResult.output);
   return ffmpegVersion.length === 0
     ? { state: "mismatch", detail: "ffmpeg returned no version" }

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

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