@hypit/hypit 0.0.1 → 0.1.0

package/packages/provider-hyperframes-local/src/program.ts

@@ -0,0 +1,58 @@
+import { execFile } from "node:child_process";
+
+import { probeMediaToolchain } from "@hypit/media-execution";
+import type { ManagedProgram, ManagedProgramState } from "@hypit/runtime-kit";
+
+function run(executable: string, args: readonly string[]): Promise<{ ok: boolean; output: string }> {
+  return new Promise((resolve) => {
+    execFile(executable, [...args], { timeout: 15_000, shell: false, windowsHide: true }, (error, stdout, stderr) => {
+      resolve(error === null
+        ? { ok: true, output: stdout.trim() }
+        : { ok: false, output: (stderr.trim() || error.message).split("\n").at(-1) ?? "" });
+    });
+  });
+}
+
+/**
+ * HyperFrames owns the browser cache behind its CLI. It is deployment state,
+ * not an author dependency, so the Endpoint lifecycle prepares it only
+ * when this Provider is selected.
+ */
+export function localHyperframesBrowserProgram(
+  input: {
+    readonly id: string;
+    readonly nodePath: string;
+    readonly hyperframesCliPath: string;
+    readonly ffprobePath: string;
+    readonly ffmpegPath?: string;
+  },
+): ManagedProgram {
+  const probeBrowser = async (): Promise<ManagedProgramState> => {
+    const located = await run(input.nodePath, [input.hyperframesCliPath, "browser", "path"]);
+    if (!located.ok) return { state: "down", detail: `HyperFrames browser is unavailable: ${located.output}` };
+    const path = located.output.trim();
+    if (path.length === 0 || path.includes("\n") || path.includes("\r")) {
+      return { state: "mismatch", detail: "HyperFrames returned an invalid browser path" };
+    }
+    const version = await run(path, ["--version"]);
+    if (!version.ok || version.output.length === 0) {
+      return { state: "mismatch", detail: `HyperFrames browser cannot start: ${version.output}` };
+    }
+    return { state: "ready" };
+  };
+  return {
+    id: input.id,
+    installation: {
+      probe: probeBrowser,
+      commands: [{ command: input.nodePath, args: [input.hyperframesCliPath, "browser", "ensure"] }],
+    },
+    async probe(): Promise<ManagedProgramState> {
+      const browser = await probeBrowser();
+      if (browser.state !== "ready") return browser;
+      const media = await probeMediaToolchain({ ffprobePath: input.ffprobePath, ...(input.ffmpegPath === undefined ? {} : { ffmpegPath: input.ffmpegPath }) });
+      return media.state === "ready"
+        ? { state: "ready" }
+        : { state: media.state, detail: media.detail };
+    },
+  };
+}

package/packages/provider-hyperframes-local/src/provider.ts

@@ -0,0 +1,62 @@
+import { defineEndpointPackage } from "@hypit/endpoint-kit";
+import { mediaTypes } from "@hypit/media";
+import { renderHyperframesCapabilities, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
+import { canonicalize } from "@hypit/protocol";
+import { resolveNodePackageExecutable } from "@hypit/package-loader-node";
+import { renderHyperframesVisual, resolveExecutionOptions } from "./render.js";
+import type { HyperframesExecutionOptions } from "./options.js";
+
+export type * from "./options.js";
+export const localHyperframesProviderModuleRef = { name: "@hypit/provider-hyperframes-local", version: "1" } as const;
+export type CreateLocalHyperframesProviderOptions = HyperframesExecutionOptions & {
+  readonly instance?: string;
+  readonly pool?: string;
+  /** Used by managed browser installation, not frame capture. */
+  readonly nodePath?: string;
+  readonly hyperframesCliPath?: string;
+  /** Whole render requests admitted concurrently; independent of frame workers. */
+  readonly defaultConcurrency?: number;
+  /** Shared Chrome slots across Need executions using this pool. */
+  readonly browserCapacity?: number;
+};
+
+export function defaultHyperframesCliPath(): string {
+  return resolveNodePackageExecutable("hyperframes", "hyperframes", { from: import.meta.url });
+}
+
+export function createLocalHyperframesProvider(config: CreateLocalHyperframesProviderOptions) {
+  const execution = resolveExecutionOptions(config);
+  const pool = config.pool ?? config.instance ?? "hyperframes.local";
+  const browsers = `capacity:${pool}/browsers`;
+  if (config.browserCapacity !== undefined && (!Number.isSafeInteger(config.browserCapacity) || config.browserCapacity < 1)) {
+    throw new Error("HyperFrames browserCapacity must be a positive integer");
+  }
+  return defineEndpointPackage({
+    module: localHyperframesProviderModuleRef,
+    facet: "render",
+    instance: config.instance ?? "hyperframes.local",
+    pool,
+    pricing: { kind: "local" },
+    defaultConcurrency: config.defaultConcurrency ?? 1,
+    capabilities: [{
+      lifecycle: "immediate" as const,
+      capability: renderHyperframesCapabilities.renderVisual,
+      returns: mediaTypes.renderedVisual,
+      ...(config.browserCapacity === undefined ? {} : {
+        resources: [{ id: browsers, limit: config.browserCapacity }],
+        unitsForRequest: (request: import("@hypit/endpoint-kit").EndpointRequest) => {
+          verifyHyperframesVisualRequest(request.constraints);
+          const { document, range } = request.constraints;
+          return { [browsers]: Math.min(execution.workers,
+            range === undefined ? document.frameCount : range.endFrameExclusive - range.startFrame) };
+        },
+      }),
+      handler: async (context) => {
+        const request = context.need.constraints;
+        verifyHyperframesVisualRequest(request);
+        const visual = await renderHyperframesVisual(request, { ...config, workers: execution.workers, resources: context.resources });
+        return { value: { kind: "inline", value: canonicalize(visual) } };
+      },
+    }],
+  });
+}

package/packages/provider-hyperframes-local/src/render.ts

@@ -0,0 +1,114 @@
+import { createReadStream } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { availableParallelism, tmpdir } from "node:os";
+import { join } from "node:path";
+import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
+import { stageHyperframesProject } from "@hypit/hyperframes/project";
+import { sealRenderedVisual } from "@hypit/media";
+import type { MediaFrameRange, RenderedVisual } from "@hypit/media";
+import { verifyCompositableSurfaceBytes } from "@hypit/media-execution";
+import { verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
+import type { HyperframesVisualRequest } from "@hypit/render-hyperframes";
+import { isStreamingResourceStore } from "@hypit/runtime";
+import type { HyperframesExecutionOptions } from "./options.js";
+import { assert, positiveInteger } from "./process.js";
+import { runCaptureProcess } from "./capture-process.js";
+import { finished } from "node:stream/promises";
+
+export type HyperframesRenderProgress =
+  | { readonly phase: "prepared"; readonly workers: number; readonly sourceFrames: number; readonly elapsedMs: number }
+  | { readonly phase: "worker-initializing" | "worker-start" | "worker-complete"; readonly worker: number; readonly range: MediaFrameRange;
+      readonly browserPid: number | undefined; readonly elapsedMs: number }
+  | { readonly phase: "complete"; readonly frames: number; readonly elapsedMs: number };
+
+export type RenderHyperframesVisualOptions = HyperframesExecutionOptions & {
+  readonly resources: EndpointInvocationContext["resources"];
+  readonly signal?: AbortSignal;
+  readonly onProgress?: (event: HyperframesRenderProgress) => void;
+};
+
+export function resolveExecutionOptions(options: HyperframesExecutionOptions) {
+  const workers = options.workers ?? "auto";
+  assert(workers === "auto" || (Number.isSafeInteger(workers) && workers > 0),
+    "workers must be auto or a positive safe integer");
+  const quality = options.quality ?? "standard";
+  assert(["draft", "standard", "high"].includes(quality), "HyperFrames quality is invalid");
+  const browserGpu = options.browserGpu ?? "hardware";
+  assert(["auto", "software", "hardware"].includes(browserGpu), "HyperFrames browserGpu is invalid");
+  return {
+    workers: workers === "auto" ? Math.min(4, Math.max(1, Math.floor(availableParallelism() / 2))) : workers,
+    quality, browserGpu,
+    ffmpegPath: options.ffmpegPath ?? "ffmpeg",
+    ffprobePath: options.ffprobePath ?? "ffprobe",
+    initializationTimeoutMs: options.initializationTimeoutMs === undefined
+      ? undefined
+      : positiveInteger(options.initializationTimeoutMs, "initializationTimeoutMs"),
+    frameTimeoutMs: options.frameTimeoutMs === undefined
+      ? undefined
+      : positiveInteger(options.frameTimeoutMs, "frameTimeoutMs"),
+    processTimeoutMs: positiveInteger(options.processTimeoutMs ?? 30 * 60_000, "processTimeoutMs"),
+    maxProcessOutputBytes: positiveInteger(options.maxProcessOutputBytes ?? 4 * 1024 * 1024, "maxProcessOutputBytes"),
+    maxRenderedBytes: positiveInteger(options.maxRenderedBytes ?? 16 * 1024 * 1024 * 1024, "maxRenderedBytes"),
+  };
+}
+
+/** Execute one attempt. Its deadline includes resource preparation and output storage. */
+export async function renderHyperframesVisual(
+  request: HyperframesVisualRequest,
+  options: RenderHyperframesVisualOptions,
+): Promise<RenderedVisual> {
+  verifyHyperframesVisualRequest(request);
+  const config = resolveExecutionOptions(options);
+  const { document } = request;
+  const range = request.range ?? { startFrame: 0, endFrameExclusive: document.frameCount };
+  const controller = new AbortController();
+  const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
+  const started = performance.now();
+  let phase = "preparing resources";
+  const timer = setTimeout(() => controller.abort(new Error(`HyperFrames render timed out during ${phase}`)), config.processTimeoutMs);
+  let work: string | undefined;
+  try {
+    signal.throwIfAborted();
+    work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
+    await stageHyperframesProject({ document, directory: work, signal,
+      read: async (artifact, readSignal) => {
+        const io = { signal: readSignal! };
+        const bytes = isStreamingResourceStore(options.resources)
+          ? await options.resources.open(artifact.resource, io) : await options.resources.get(artifact.resource, io);
+        assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
+        return bytes;
+      },
+      validateSurface: (surface, bytes, probeSignal) => verifyCompositableSurfaceBytes({ surface, bytes,
+        ffprobePath: config.ffprobePath, processTimeoutMs: config.processTimeoutMs,
+        maxProbeOutputBytes: config.maxProcessOutputBytes, signal: probeSignal! }),
+    });
+    phase = "rendering frames";
+    await runCaptureProcess({ document, range, config, directory: work,
+      engineModule: import.meta.resolve("@hyperframes/engine"),
+      producerModule: import.meta.resolve("@hyperframes/producer"),
+    }, signal, (event) => options.onProgress?.({ ...event, elapsedMs: Math.round(performance.now() - started) }));
+    signal.throwIfAborted();
+    phase = "storing output";
+    const output = join(work, "visual.mp4");
+    let artifact;
+    if (isStreamingResourceStore(options.resources)) {
+      const stream = createReadStream(output, { signal });
+      const closed = finished(stream).catch(() => {});
+      try { artifact = await options.resources.putStream(stream, "video/mp4", { signal }); }
+      finally { stream.destroy(); await closed; }
+    } else {
+      artifact = await options.resources.put(await readFile(output, { signal }), "video/mp4", { signal });
+    }
+    signal.throwIfAborted();
+    const frameCount = range.endFrameExclusive - range.startFrame;
+    options.onProgress?.({ phase: "complete", frames: frameCount, elapsedMs: Math.round(performance.now() - started) });
+    return sealRenderedVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas, artifact });
+  } catch (error) {
+    if (signal.aborted) throw signal.reason;
+    controller.abort(error);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    if (work !== undefined) await rm(work, { recursive: true, force: true });
+  }
+}

package/packages/provider-hyperframes-local/src/sampling.ts

@@ -0,0 +1,89 @@
+import type { MediaFrameRange } from "@hypit/media";
+import { assert } from "./process.js";
+
+type Rational = { readonly numerator: bigint; readonly denominator: bigint };
+export type VideoSlot = MediaFrameRange & {
+  readonly id: string;
+  readonly src: string;
+  readonly sourceFrame: Rational;
+  readonly sourceRate: Rational;
+  readonly sourceFps: { readonly num: number; readonly den: number };
+};
+
+function rational(value: string, label: string): Rational {
+  assert(/^\d+\/[1-9]\d*$/u.test(value), `HyperFrames ${label} must be a non-negative rational`);
+  const [a, b] = value.split("/");
+  return { numerator: BigInt(a!), denominator: BigInt(b!) };
+}
+
+/** Read the compiler's exact frame markers, without reconstructing author intent from seconds. */
+export function videoSlots(html: string): VideoSlot[] {
+  return [...html.matchAll(/<video\b[^>]*>/gu)].map(([tag]) => {
+    const attribute = (name: string): string => {
+      const value = new RegExp(`(?:\\s)${name}="([^"]*)"`, "u").exec(tag)?.[1];
+      assert(value !== undefined, `HyperFrames video lacks ${name}; compile its frame sampling before rendering`);
+      return value.replaceAll("&amp;", "&").replaceAll("&quot;", '"').replaceAll("&lt;", "<").replaceAll("&gt;", ">");
+    };
+    const sourceFps = rational(attribute("data-hypit-source-fps"), "source frame rate");
+    const slot = {
+      id: attribute("id"), src: attribute("src"),
+      startFrame: Number(attribute("data-hypit-start-frame")),
+      endFrameExclusive: Number(attribute("data-hypit-end-frame")),
+      sourceFrame: rational(attribute("data-hypit-source-frame"), "source frame"),
+      sourceRate: rational(attribute("data-hypit-source-rate"), "source rate"),
+      sourceFps: { num: Number(sourceFps.numerator), den: Number(sourceFps.denominator) },
+    };
+    assert(Number.isSafeInteger(slot.startFrame) && slot.startFrame >= 0
+      && Number.isSafeInteger(slot.endFrameExclusive) && slot.endFrameExclusive > slot.startFrame
+      && Number.isSafeInteger(slot.sourceFps.num) && slot.sourceFps.num > 0
+      && Number.isSafeInteger(slot.sourceFps.den), "HyperFrames video frame mapping is invalid");
+    return slot;
+  });
+}
+
+/** A decoded frame owns [n, n+1) in source-frame coordinates. */
+export function sourceFrameAt(slot: VideoSlot, frame: number): number {
+  const a = slot.sourceFrame;
+  const r = slot.sourceRate;
+  const value = Number((a.numerator * r.denominator
+    + BigInt(frame - slot.startFrame) * r.numerator * a.denominator) / (a.denominator * r.denominator));
+  assert(Number.isSafeInteger(value) && value >= 0, "HyperFrames source frame exceeds safe arithmetic");
+  return value;
+}
+
+export function sourceWindows(slots: readonly VideoSlot[], range: MediaFrameRange) {
+  const sources = new Map<string, { fps: VideoSlot["sourceFps"]; windows: MediaFrameRange[] }>();
+  for (const slot of slots) {
+    const first = Math.max(range.startFrame, slot.startFrame);
+    const last = Math.min(range.endFrameExclusive, slot.endFrameExclusive) - 1;
+    if (last < first) continue;
+    let source = sources.get(slot.src);
+    if (source === undefined) {
+      source = { fps: slot.sourceFps, windows: [] };
+      sources.set(slot.src, source);
+    }
+    assert(source.fps.num * slot.sourceFps.den === slot.sourceFps.num * source.fps.den,
+      "One HyperFrames source has conflicting frame rates");
+    source.windows.push({ startFrame: sourceFrameAt(slot, first), endFrameExclusive: sourceFrameAt(slot, last) + 1 });
+  }
+  return [...sources].map(([src, source]) => {
+    const windows: MediaFrameRange[] = [];
+    for (const window of source.windows.sort((a, b) => a.startFrame - b.startFrame)) {
+      const previous = windows.at(-1);
+      if (previous !== undefined && window.startFrame <= previous.endFrameExclusive) {
+        windows[windows.length - 1] = { startFrame: previous.startFrame,
+          endFrameExclusive: Math.max(previous.endFrameExclusive, window.endFrameExclusive) };
+      } else windows.push(window);
+    }
+    return { src, fps: source.fps, windows };
+  });
+}
+
+export function distributeFrameRange(range: MediaFrameRange, workers: number): MediaFrameRange[] {
+  const count = range.endFrameExclusive - range.startFrame;
+  const active = Math.min(count, workers);
+  return Array.from({ length: active }, (_, index) => ({
+    startFrame: range.startFrame + Math.floor(index * count / active),
+    endFrameExclusive: range.startFrame + Math.floor((index + 1) * count / active),
+  }));
+}

package/packages/provider-hypihub/README.md

@@ -0,0 +1,143 @@
+# `@hypit/provider-hypihub`
+
+Thin Hypit Runtime Provider for a HypiHub deployment. It is an optional default gateway for
+paid generation and WhisperX alignment requests; callers may keep their own Provider and select HypiHub only
+when its OAuth login is configured.
+
+It maps the currently shipped image/video model capabilities to HypiHub, including image edits and
+image-to-video first-frame inputs, submits jobs, polls them, downloads the first-class assets and
+admits them into the current Build's working byte area. Image references use HypiHub's documented
+`reference_images` object shape (`[{ "url": "…" }]`); video references use the public
+`reference_image_urls`, `reference_videos`, and `reference_audios` fields (with `ref_video_url`
+for one video). First/last-frame images use `first_frame` and `last_frame`.
+
+The current HypiHub GPT Image 2 route exposes the same request surface as its KIE upstream:
+
+| Resolution | Ratios unavailable at this Endpoint | `background` |
+| --- | --- | --- |
+| `1K` | none | optional |
+| `2K` | `5:4`, `4:5`, `3:1`, `1:3`, `9:21` | omit |
+| `4K` | `3:1`, `1:3`, `9:21` | omit |
+
+HypiHub owns this support check independently: it neither imports the KIE Provider nor narrows the
+GPT Image model package. When the service surface changes, this Provider can change without changing
+the model or another Provider.
+
+For moving portraits, [Volcengine Matting](../volcengine-matting/README.md) maps
+`@hypit/volcengine-matting@1#matte-portrait-video` to `POST /v1/videos` with
+`model: "matte-portrait-video"`, `ref_video_url` and `format` (`WEBM` by default, or `MOV`).
+Both formats carry transparency. The source video uses the same upload transport as other video
+references; the returned job uses the same polling and asset collection lifecycle. The selected
+account's `/v1/models` establishes availability. The processed video enters ordinary Normalize,
+then either semantic alignment for a Script performance or Media Track for B-roll.
+
+The existing [Background Removal](../background-removal/README.md) package handles single images
+through KIE Recraft. This Provider does not bind that separate image capability either.
+
+Runtime Profile example:
+
+```json
+{
+  "endpoints": {
+    "hypihub.default": {
+      "use": "@hypit/provider-hypihub",
+      "pool": "hypihub.default",
+      "config": {
+        "baseUrl": "https://hypit.ai",
+        "apiKey": { "store": "os", "key": "hypihub.oauth" },
+        "defaultConcurrency": 3,
+        "pollIntervalMs": 10000
+      }
+    }
+  }
+}
+```
+
+Remote transcription exposes the same `@hypit/whisperx` alignment capability implemented by the local
+WhisperX Provider. The Runtime Profile selects which Endpoint serves it. Run
+`hypit auth login hypihub.default --runtime hypit.runtime.json` to sign in with HypiHub OAuth when
+choosing HypiHub. A Profile may set `baseUrl`
+to the selected deployment's origin or an existing `/v1`/`/v1beta` base. The Runtime Provider
+normalizes it to `/v1`; missing or insufficient user
+credentials should be resolved at [hypit.ai](https://hypit.ai). Referenced image, audio and video
+Resources are uploaded through a session from `POST /v1/files/uploads`, followed by the private
+regional multipart instructions returned by HypiHub. The Provider follows the server-selected part
+size and part concurrency, retries a failed part with a fresh signed URL, completes or cancels that
+one upload, and then passes the returned HTTPS URL to generation or transcription. One
+Resource identity is uploaded once within one Runtime operation. Hypit keeps no upload catalog or
+cross-Build cache. Embedded callers may replace this transport with `publicAssetUrl`.
+
+OAuth login stores the access token, refresh token and expiry as one opaque credential value. The
+browser callback only confirms that authorization returned to the CLI; the CLI reports success after
+the bounded token exchange and Credential Store write complete. `oauthRequestTimeoutMs` controls that
+exchange and defaults to 30 seconds, independently of the longer inference request timeout. The
+Provider refreshes that value shortly before expiry or after an unauthorised response when the
+selected Store is writable. Its Endpoint receives only the credential slot it declared and a narrow
+operation for replacing that same slot; it cannot enumerate the Store, choose another key or read
+another Endpoint's credentials. A raw credential remains an ordinary static API key.
+
+The service currently requires whole-file and per-part SHA-256 values as fields of its signed upload
+protocol. They exist only while transferring bytes; Hypit never uses them as Resource identity,
+Result metadata, lookup keys or reuse evidence. Signed URLs and their query credentials are removed
+from surfaced upload errors.
+
+The default remote alignment model is `victor-upmeet/whisperx`; `transcriptionModel` may select another
+HypiHub model that exposes the `transcriptions` route. `hypit doctor` reads the authenticated model
+catalog to verify configured capabilities; ordinary preflight never makes that request. The package
+declares HypiHub's public pricing page, `https://hypit.ai/commercial/pricing/`, as its price source.
+For each selected Need, `readPricing` resolves the corresponding HypiHub model and returns the service's
+authenticated `GET /v1/pricing?model=<model>` response unchanged together with that URL. It covers
+generation, alignment, Voice Design, and Voice Clone through the same mechanism;
+the Provider does not maintain a second list of billing formulas or calculate a request total.
+
+HypiHub declares MiMo Voice Design and Voice Clone together with every other capability it serves; it
+never hides one. Voice Design produces an accepted voice-reference Resource, and Voice Clone uses
+that reference to produce independent speech. Hypit does not expose MiMo preset voices. When another
+selected Endpoint offers the same capability (a local WhisperX or the official MiMo
+Provider), the Runtime Profile's `bindings` say which Endpoint serves it.
+
+Execution policy remains local to this Provider:
+
+| Profile field | Default | What it controls |
+| --- | ---: | --- |
+| `requestTimeoutMs` | 300 seconds | ordinary Provider HTTP requests |
+| `oauthRequestTimeoutMs` | 30 seconds | OAuth token exchange and refresh |
+| `pricingRequestTimeoutMs` | 30 seconds | authenticated pricing requests |
+| `operationTimeoutMs` | 20 minutes | one remote asynchronous operation |
+| `uploadConcurrency` | 8 | whole file sessions per origin/credential within this process |
+| `uploadPartTimeoutMs` | 5 minutes | one upload part |
+| `uploadPartAttempts` | 3 | attempts for one upload part |
+| `downloadAttempts` | 3 | attempts to collect one result |
+
+`defaultConcurrency` controls the total shared capacity of this Profile's HypiHub pool. Optional `capabilityConcurrency`
+sets narrower group limits, for example `{ "seedance-2-mini": 2, "transcription": 1 }`.
+Image/video/speech groups use the exact capability name; WhisperX uses `transcription`. These limits
+coordinate this Runtime's requests; HypiHub remains
+responsible for service-wide account limits. Immediate speech/transcription slots cover the
+active HTTP invocation, while asynchronous image/video slots cover remote work until completion or local execution failure.
+
+For asynchronous image/video jobs, `actionLimits` configures the common `submit`, `poll` and `collect`
+admission budgets. Each accepts `concurrency` and `rate: { limit, periodMs }`, shared by the pool.
+These limits count lifecycle actions; Provider-specific upload parts and HTTP requests remain inside
+those actions. Synchronous speech and transcription retain their ordinary request capacity.
+
+A submission, polling or collection error ends the local attempt. Known job IDs and credential
+references remain available in Result receipts; a timeout with no ID is recorded as such. A job can
+be inspected at `/jobs/<id>` and its generated assets at `/jobs/<id>/assets` on the selected API base.
+The next production attempt uses a new Run and Build. Runtime bindings never switch from a user's
+own Provider to HypiHub after a key, quota or transport failure.
+
+`uploadConcurrency` bounds whole files inside the Provider transport. Uploader instances in the same
+process share the limit for the same service origin and current credential; the smallest outstanding
+limit applies. Token refresh can change that grouping. Separate processes are not coordinated by this
+local limit. It is a positive safe integer; HypiHub still enforces its own account quota. Part
+concurrency is separately negotiated by HypiHub for each file. These are transport limits inside a
+Runtime action, not additional Build admission limits.
+
+Signing, completing and cancelling a known upload session may retry temporary transport failures
+within at most four attempts and the smaller of `requestTimeoutMs` or 120 seconds. A new upload
+session is retried only after an explicit temporary 429 rejection; an unknown creation result ends
+the attempt. Daily and storage quota errors fail immediately. Active part workers finish before the
+session is cancelled. An unconfirmed cancellation logs its upload ID without exposing signed URLs.
+OAuth refresh retries the rejected control request on the same session. None of this resumes a
+failed Build or changes the selected Provider.

package/packages/provider-hypihub/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@hypit/provider-hypihub",
+  "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:*",
+    "@hypit/speech-evidence": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/whisperx": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/driver-node": "workspace:*",
+    "@hypit/mimo-speech": "workspace:*",
+    "@hypit/seedance": "workspace:*",
+    "@hypit/speech": "workspace:*",
+    "@hypit/volcengine-matting": "workspace:*"
+  }
+}

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

@@ -0,0 +1,91 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigCredentialRef,
+  runtimeConfigActionLimits,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createHypiHubProvider, diagnoseHypiHubProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-hypihub",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("HypiHub Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "HypiHub");
+    runtimeConfigExact(config, [
+      "baseUrl",
+      "apiKey",
+      "defaultConcurrency",
+      "actionLimits",
+      "capabilityConcurrency",
+      "pollIntervalMs",
+      "requestTimeoutMs",
+      "oauthRequestTimeoutMs",
+      "pricingRequestTimeoutMs",
+      "operationTimeoutMs",
+      "uploadConcurrency",
+      "uploadPartTimeoutMs",
+      "uploadPartAttempts",
+      "downloadAttempts",
+      "transcriptionModel",
+    ], "HypiHub");
+    const baseUrl = runtimeConfigString(config.baseUrl, "HypiHub 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("HypiHub baseUrl must use HTTPS or loopback");
+      }
+    }
+    const apiKey = runtimeConfigCredentialRef(config.apiKey, "HypiHub apiKey");
+    if (apiKey === undefined) throw new Error("HypiHub apiKey CredentialRef is required");
+    const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HypiHub defaultConcurrency");
+    const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "HypiHub pollIntervalMs");
+    const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "HypiHub requestTimeoutMs");
+    const oauthRequestTimeoutMs = runtimeConfigPositiveInteger(config.oauthRequestTimeoutMs, "HypiHub oauthRequestTimeoutMs");
+    const pricingRequestTimeoutMs = runtimeConfigPositiveInteger(config.pricingRequestTimeoutMs, "HypiHub pricingRequestTimeoutMs");
+    const operationTimeoutMs = runtimeConfigPositiveInteger(config.operationTimeoutMs, "HypiHub operationTimeoutMs");
+    const uploadConcurrency = runtimeConfigPositiveInteger(config.uploadConcurrency, "HypiHub uploadConcurrency");
+    const uploadPartTimeoutMs = runtimeConfigPositiveInteger(config.uploadPartTimeoutMs, "HypiHub uploadPartTimeoutMs");
+    const uploadPartAttempts = runtimeConfigPositiveInteger(config.uploadPartAttempts, "HypiHub uploadPartAttempts");
+    const downloadAttempts = runtimeConfigPositiveInteger(config.downloadAttempts, "HypiHub downloadAttempts");
+    const transcriptionModel = runtimeConfigString(config.transcriptionModel, "HypiHub transcriptionModel");
+    const capabilityConcurrency = config.capabilityConcurrency === undefined ? undefined : Object.fromEntries(
+      Object.entries(runtimeConfigObject(config.capabilityConcurrency, "HypiHub capabilityConcurrency"))
+        .map(([name, value]) => [name, runtimeConfigPositiveInteger(value, `HypiHub ${name} capacity`)!]),
+    );
+    const options = {
+        instance: context.instance,
+        pool: context.pool,
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        apiKey,
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(actionLimits === undefined ? {} : { actionLimits }),
+        ...(capabilityConcurrency === undefined ? {} : { capabilityConcurrency }),
+        ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+        ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+        ...(oauthRequestTimeoutMs === undefined ? {} : { oauthRequestTimeoutMs }),
+        ...(pricingRequestTimeoutMs === undefined ? {} : { pricingRequestTimeoutMs }),
+        ...(operationTimeoutMs === undefined ? {} : { operationTimeoutMs }),
+        ...(uploadConcurrency === undefined ? {} : { uploadConcurrency }),
+        ...(uploadPartTimeoutMs === undefined ? {} : { uploadPartTimeoutMs }),
+        ...(uploadPartAttempts === undefined ? {} : { uploadPartAttempts }),
+        ...(downloadAttempts === undefined ? {} : { downloadAttempts }),
+        ...(transcriptionModel === undefined ? {} : { transcriptionModel }),
+      };
+    return {
+      endpoint: createHypiHubProvider(options),
+      diagnose: async (doctor) => await diagnoseHypiHubProvider(options, doctor),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [adapter],
+};
+
+export default hypitPackage;

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

@@ -0,0 +1,2 @@
+export { createHypiHubProvider, hypiHubProviderModuleRef } from "./provider.js";
+export type { CreateHypiHubProviderOptions } from "./provider.js";