@hypit/hypit 0.1.8 → 0.1.10

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

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { requestDeadline } from "@hypit/runtime-kit";
 import type { AsyncEndpoint, EndpointCredential, EndpointFulfillment, EndpointInvocationContext, EndpointPollContext, EndpointPricingReader, EndpointStartContext, EndpointOutcome, ImmediateEndpointHandler } from "@hypit/endpoint-kit";
 import { defineEndpointPackage, wakeAfter } from "@hypit/endpoint-kit";
@@ -16,10 +17,35 @@ import {
 } from "@hypit/whisperx";
 import type { WhisperXTranscriptResponse } from "@hypit/whisperx";
 import { hypiHubRouteForCapability, hypiHubRoutes } from "./routes.js";
+import type { HypiHubModelOperation } from "./routes.js";
 import { HypiHubUploader } from "./upload.js";
 import type { RuntimeDoctorDiagnostic } from "@hypit/runtime-kit";
 import { createHypiHubAuth, hypiHubCredentialNeedsRefresh } from "./oauth.js";
 import type { HypiHubAuth } from "./oauth.js";
+import { HypiHubHttpError, HypiHubServiceError, hypiHubJobFailure } from "./errors.js";
+
+function distributionVersion(): string {
+  try {
+    const manifest = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8")) as {
+      readonly name?: unknown; readonly version?: unknown;
+    };
+    if (manifest.name !== "@hypit/hypit" || typeof manifest.version !== "string" || manifest.version.length === 0) {
+      return "unknown";
+    }
+    return manifest.version;
+  } catch {
+    return "unknown";
+  }
+}
+
+const userAgent = `hypit/${distributionVersion()}`;
+
+const identifiedFetch = (fetcher: typeof globalThis.fetch): typeof globalThis.fetch =>
+  async (input, init) => {
+    const headers: Record<string, string> = { "user-agent": userAgent };
+    new Headers(init?.headers).forEach((value, name) => { headers[name] = value; });
+    return await fetcher(input, { ...init, headers });
+  };
 
 export const hypiHubProviderModuleRef = { name: "@hypit/provider-hypihub", version: "1" } as const;
 
@@ -64,18 +90,15 @@ function apiBaseUrl(value: string): string {
 }
 function credential(credentials: Readonly<Record<string, EndpointCredential>>) {
   const value = credentials.apiKey?.secret;
-  assert(typeof value === "string" && value.length > 0, "HypiHub login is unavailable; run hypit auth login for HypiHub");
+  assert(typeof value === "string" && value.length > 0, "HypiHub apiKey credential is unavailable; configure this Endpoint's credential with a HypiHub API key or OAuth login");
   return credentials.apiKey!;
 }
-function guidedMessage(error: unknown): string {
-  const message = error instanceof Error ? error.message : String(error);
-  return /API key is unavailable|HypiHub login is unavailable|HTTP 401\b/iu.test(message)
-    ? `${message}. Sign in to HypiHub at https://hypit.ai with hypit auth login`
-    : message;
+function failureMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
 }
 function failure(error: unknown): EndpointOutcome {
-  const message = guidedMessage(error);
-  return { status: "failed", failure: { code: "HYPIHUB_ERROR", message } };
+  const message = failureMessage(error);
+  return { status: "failed", failure: { code: error instanceof HypiHubServiceError ? error.code : "HYPIHUB_ERROR", message } };
 }
 
 function jobId(value: Record<string, unknown>): string {
@@ -84,17 +107,13 @@ function jobId(value: Record<string, unknown>): string {
   return id;
 }
 
-type HypiHubModelOperation = "images" | "image_edits" | "videos" | "audio_speech" | "transcriptions";
-
 async function verifyModelRoute(client: HypiHubClient, auth: HypiHubAuth, model: string, operation: HypiHubModelOperation): Promise<void> {
   const card = await client.json(`/models/${encodeURIComponent(model)}`, auth);
   const endpoints = card.endpoints;
-  assert(Array.isArray(endpoints) && endpoints.includes(operation),
-    `HypiHub model ${model} is not enabled for ${operation} with this API key`);
-}
-
-class HypiHubHttpError extends Error {
-  constructor(readonly status: number, message: string) { super(message); }
+  assert(Array.isArray(endpoints) && endpoints.every((value) => typeof value === "string"),
+    `HypiHub model ${model} returned no valid operation list; support for ${operation} is unknown`);
+  assert(endpoints.includes(operation),
+    `HypiHub model ${model} does not list operation ${operation}; listed operations: ${endpoints.join(", ") || "none"}`);
 }
 
 class HypiHubClient {
@@ -118,7 +137,7 @@ class HypiHubClient {
     this.timeout = options.timeout;
     this.oauthTimeout = options.oauthTimeout;
     this.downloadAttempts = options.downloadAttempts;
-    this.fetcher = options.fetcher;
+    this.fetcher = identifiedFetch(options.fetcher);
     this.uploader = new HypiHubUploader({
       baseUrl: this.baseUrl,
       requestTimeoutMs: this.timeout,
@@ -141,7 +160,13 @@ class HypiHubClient {
         await auth.refresh();
         return await this.json(path, auth, init, false, onResponse);
       }
-      if (!response.ok) throw new HypiHubHttpError(response.status, `HypiHub returned HTTP ${response.status}: ${text.slice(0, 300)}`);
+      if (!response.ok) {
+        const input = typeof init.body === "string" ? JSON.parse(init.body) as Record<string, unknown> : undefined;
+        throw new HypiHubHttpError(response.status, response, text, {
+          method: init.method ?? "GET", url: `${this.baseUrl}${path}`,
+          ...(typeof input?.model === "string" ? { model: input.model } : {}),
+        });
+      }
       try { body = text.length === 0 ? {} : JSON.parse(text); } catch { throw new Error(`HypiHub returned invalid JSON (${response.status})`); }
       return object(body, "HypiHub response");
     } finally { deadline.finish(); }
@@ -210,7 +235,10 @@ class HypiHubClient {
         return await this.speech(auth, body, false);
       }
       if (!response.ok) {
-        throw new Error(`HypiHub returned HTTP ${response.status}: ${Buffer.from(bytes).toString("utf8").slice(0, 300)}`);
+        throw new HypiHubHttpError(response.status, response, Buffer.from(bytes).toString("utf8"), {
+          method: "POST", url: `${this.baseUrl}/audio/speech`,
+          ...(typeof body.model === "string" ? { model: body.model } : {}),
+        });
       }
       const responseType = response.headers.get("content-type")?.split(";", 1)[0] ?? "audio/mpeg";
       if (!responseType.includes("json")) return [{ bytes, mediaType: responseType }];
@@ -308,8 +336,7 @@ function cardIdentifiers(card: Record<string, unknown>): readonly string[] {
   return [card.id, card.canonical_name].filter((name): name is string => typeof name === "string");
 }
 
-/** The additional model names a card answers to. HypiHub publishes the per-operation
- *  routing names used by the Provider mapping table as aliases of one canonical card. */
+/** Additional names explicitly published by the service for this card. */
 function cardAliases(card: Record<string, unknown>): readonly string[] {
   return Array.isArray(card.aliases)
     ? card.aliases.filter((name): name is string => typeof name === "string")
@@ -325,7 +352,7 @@ export async function diagnoseHypiHubProvider(
   },
 ): Promise<readonly RuntimeDoctorDiagnostic[]> {
   const apiKey = context.credentials.apiKey?.secret;
-  assert(typeof apiKey === "string" && apiKey.length > 0, "HypiHub login is unavailable");
+  assert(typeof apiKey === "string" && apiKey.length > 0, "HypiHub credential is unavailable");
   if (hypiHubCredentialNeedsRefresh(apiKey)) return [{
     severity: "warning",
     code: "HYPIHUB_OAUTH_REFRESH_UNCHECKED",
@@ -377,23 +404,13 @@ export async function diagnoseHypiHubProvider(
     if (!available) diagnostics.push({
       severity: "error",
       code: "HYPIHUB_CAPABILITY_UNAVAILABLE",
-      message: `HypiHub login cannot currently route ${capabilityKey(capability)}`,
+      message: `The HypiHub catalogue returned for this credential does not list a route for ${capabilityKey(capability)}`,
       subject: capabilityKey(capability),
     });
   }
   return diagnostics;
 }
 
-function generationOperation(route: (typeof hypiHubRoutes)[number], input: Record<string, unknown>): HypiHubModelOperation {
-  if (route.media === "audio") return "audio_speech";
-  if (route.media === "video") return "videos";
-  const hasReferences = Object.entries(input).some(([key, value]) => {
-    if (!["images", "reference_images", "reference_image_urls", "reference_videos", "reference_audios", "first_frame", "last_frame"].includes(key)) return false;
-    return Array.isArray(value) ? value.length > 0 : typeof value === "string" && value.length > 0;
-  });
-  return hasReferences ? "image_edits" : "images";
-}
-
 async function complete(client: HypiHubClient, auth: HypiHubAuth, route: (typeof hypiHubRoutes)[number], id: string, artifacts: ResourceStore): Promise<EndpointOutcome> {
   const response = await client.json(`/jobs/${encodeURIComponent(id)}/assets`, auth); const items = response.items;
   assert(Array.isArray(items) && items.length > 0, "HypiHub job has no assets"); const blobs: BlobRef[] = [];
@@ -401,14 +418,44 @@ async function complete(client: HypiHubClient, auth: HypiHubAuth, route: (typeof
   return { status: "completed", result: { value: route.packageResult(blobs) } };
 }
 
-async function synthesizeAudio(client: HypiHubClient, context: EndpointInvocationContext, publicAssetUrl: CreateHypiHubProviderOptions["publicAssetUrl"]): Promise<EndpointFulfillment> {
+async function prepareGeneration(client: HypiHubClient, context: EndpointInvocationContext, publicAssetUrl: CreateHypiHubProviderOptions["publicAssetUrl"]) {
   const route = hypiHubRouteForCapability(context.need.capability);
-  assert(route !== undefined && route.media === "audio", "HypiHub does not implement this exact capability");
+  assert(route !== undefined, "HypiHub does not implement this exact capability");
+  const request = route.prepare(context.need.constraints);
   const auth = authFor(context, client);
-  const compiled = await route.compile(context.need.constraints, async (artifact, fields) => publicAssetUrl === undefined
-    ? await client.upload(artifact, context.resources, auth, fields)
-    : await publicAssetUrl(artifact, context.resources, fields));
-  await verifyModelRoute(client, auth, compiled.model, "audio_speech");
+  await context.reportProgress?.({ phase: `Reading HypiHub model catalogue: ${request.model} (${request.operation})` });
+  try {
+    await verifyModelRoute(client, auth, request.model, request.operation);
+  } catch (error) {
+    throw new HypiHubServiceError(error instanceof HypiHubServiceError ? error.code : "HYPIHUB_ERROR",
+      `HypiHub model catalogue check failed; model=${request.model}; operation=${request.operation}; references uploaded=0; generation not submitted: ${failureMessage(error)}`);
+  }
+  await context.reportProgress?.({ phase: `Preparing HypiHub request: ${request.model} (${request.operation})` });
+  const uploaded = new Map<string, Promise<string>>();
+  const resolve = (artifact: BlobRef, fields?: Readonly<Record<string, string | number | boolean>>): Promise<string> => {
+    const key = JSON.stringify([artifact.resource, canonicalize(fields ?? {})]);
+    const existing = uploaded.get(key);
+    if (existing !== undefined) return existing;
+    const promise = publicAssetUrl === undefined
+      ? client.upload(artifact, context.resources, auth, fields)
+      : publicAssetUrl(artifact, context.resources, fields);
+    uploaded.set(key, promise);
+    return promise;
+  };
+  let compiled;
+  try {
+    compiled = await request.compile(resolve);
+  } catch (error) {
+    throw new HypiHubServiceError(error instanceof HypiHubServiceError ? error.code : "HYPIHUB_ERROR",
+      `HypiHub request preparation failed; model=${request.model}; operation=${request.operation}; generation not submitted: ${failureMessage(error)}`);
+  }
+  return { route, auth, compiled, operation: request.operation };
+}
+
+async function synthesizeAudio(client: HypiHubClient, context: EndpointInvocationContext, publicAssetUrl: CreateHypiHubProviderOptions["publicAssetUrl"]): Promise<EndpointFulfillment> {
+  const { route, auth, compiled, operation } = await prepareGeneration(client, context, publicAssetUrl);
+  assert(route.media === "audio", "HypiHub audio capabilities use an immediate endpoint");
+  await context.reportProgress?.({ phase: `Submitting HypiHub request: ${compiled.model} (${operation})` });
   const audio = await client.speech(auth, { model: compiled.model, ...(compiled.input as Record<string, unknown>) });
   const artifacts = await Promise.all(audio.map(async (item) => await context.resources.put(item.bytes, item.mediaType)));
   return { value: route.packageResult(artifacts) };
@@ -418,33 +465,20 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
   return {
     async start(context: EndpointStartContext) {
       try {
-        const route = hypiHubRouteForCapability(context.need.capability);
-        assert(route !== undefined, "HypiHub does not implement this exact capability");
-        const auth = authFor(context, client);
-        const uploaded = new Map<string, Promise<string>>();
-        const resolve = (artifact: BlobRef, fields?: Readonly<Record<string, string | number | boolean>>): Promise<string> => {
-          const key = JSON.stringify([artifact.resource, canonicalize(fields ?? {})]);
-          const existing = uploaded.get(key);
-          if (existing !== undefined) return existing;
-          const promise = publicAssetUrl === undefined
-            ? client.upload(artifact, context.resources, auth, fields)
-            : publicAssetUrl(artifact, context.resources, fields);
-          uploaded.set(key, promise);
-          return promise;
-        };
-        const compiled = await route.compile(context.need.constraints, resolve);
+        const { route, auth, compiled, operation } = await prepareGeneration(client, context, publicAssetUrl);
         assert(route.media !== "audio", "HypiHub audio capabilities use an immediate endpoint");
         const input = compiled.input as Record<string, unknown>;
-        const operation = generationOperation(route, input);
         const path = operation === "image_edits" ? "/images/edits"
           : operation === "images" ? "/images/generations" : "/videos";
-        await verifyModelRoute(client, auth, compiled.model, operation);
+        await context.reportProgress?.({ phase: `Submitting HypiHub request: ${compiled.model} (${operation})` });
         const response = await client.json(path, auth, { method: "POST", headers: { "content-type": "application/json", "idempotency-key": context.operation }, body: JSON.stringify({ model: compiled.model, ...input }) });
         const status = response.status;
         const remoteEnded = status === "succeeded" || status === "completed";
         const handle: Handle = { contract: "hypit.hypihub-operation@1", jobId: jobId(response), route: capabilityKey(route.capability), startedAt: Date.now() };
         const receipt = { id: handle.jobId };
         await context.checkpoint?.({ handle: canonicalize(handle), receipt, ...(remoteEnded ? { remoteEnded: true as const } : {}) });
+        const rejected = hypiHubJobFailure(response, handle.jobId);
+        if (rejected !== undefined) return { ...failure(rejected), receipt };
         return remoteEnded ? { status: "ready", handle: canonicalize(handle), receipt }
           : { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: "submitted" }), receipt };
       } catch (error) {
@@ -457,15 +491,13 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
         assert(route !== undefined && handle.contract === "hypit.hypihub-operation@1" && handle.route === capabilityKey(route.capability), "HypiHub handle is invalid");
         if (Date.now() - handle.startedAt > maxOperationMs) {
           return { status: "failed",
-            failure: { code: "HYPIHUB_OPERATION_TIMEOUT", message: "HypiHub operation timed out" } };
+            receipt: { id: handle.jobId },
+            failure: { code: "HYPIHUB_OPERATION_TIMEOUT", message: `HypiHub job ${handle.jobId} exceeded this Provider's operationTimeoutMs (${maxOperationMs}); remote outcome is unknown` } };
         }
         const job = await client.json(`/jobs/${encodeURIComponent(handle.jobId)}`, authFor(context, client)); const status = job.status;
         if (status === "queued" || status === "running" || status === "in_progress") return wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: String(status) });
-        if (status === "failed" || status === "queue_expired" || status === "cancelled") {
-          const detail = [job.error, job.message, job.reason, job.detail]
-            .find((value) => typeof value === "string" && value.length > 0);
-          throw new Error(`HypiHub job ${status}${typeof detail === "string" ? `: ${detail}` : ""}`);
-        }
+        const rejected = hypiHubJobFailure(job, handle.jobId);
+        if (rejected !== undefined) return { ...failure(rejected), receipt: { id: handle.jobId } };
         if (status !== "succeeded" && status !== "completed") throw new Error(`HypiHub returned unknown job status ${String(status)}`);
         return { status: "ready", handle: context.handle, receipt: { id: handle.jobId } };
       } catch (error) {
@@ -473,10 +505,12 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
       }
     },
     async collect(context) {
-      const handle = object(context.handle, "HypiHub handle") as unknown as Handle;
-      const route = hypiHubRouteForCapability(context.need.capability);
-      assert(route !== undefined && handle.route === capabilityKey(route.capability), "HypiHub collection route differs");
-      return await complete(client, authFor(context, client), route, handle.jobId, context.resources);
+      try {
+        const handle = object(context.handle, "HypiHub handle") as unknown as Handle;
+        const route = hypiHubRouteForCapability(context.need.capability);
+        assert(route !== undefined && handle.route === capabilityKey(route.capability), "HypiHub collection route differs");
+        return await complete(client, authFor(context, client), route, handle.jobId, context.resources);
+      } catch (error) { return failure(error); }
     },
 
   };
@@ -529,13 +563,8 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
     fetcher: options.fetch ?? globalThis.fetch,
   });
   const asyncEndpoint = endpoint(client, options.pollIntervalMs ?? 10_000, operationTimeoutMs, options.publicAssetUrl);
-  const audioEndpoint: ImmediateEndpointHandler = async (context) => {
-    try {
-      return await synthesizeAudio(client, context, options.publicAssetUrl);
-    } catch (error) {
-      throw new Error(guidedMessage(error), { cause: error });
-    }
-  };
+  const audioEndpoint: ImmediateEndpointHandler = async (context) =>
+    await synthesizeAudio(client, context, options.publicAssetUrl);
   const transcriptionModel = options.transcriptionModel?.trim() || "victor-upmeet/whisperx";
   const whisperXEndpoint: ImmediateEndpointHandler = async (context) => {
     try {
@@ -564,7 +593,7 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
       await context.reportProgress?.({ phase: "Word timing ready" });
       return { value: { kind: "inline", value: canonicalize(evidence) } };
     } catch (error) {
-      throw new Error(guidedMessage(error), { cause: error });
+      throw new Error(failureMessage(error), { cause: error });
     }
   };
   const oauthOrigin = new URL(options.baseUrl ?? "https://hypit.ai").origin;
@@ -574,7 +603,7 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
     readPricing: hypiHubPricingReader(pricingClient, transcriptionModel),
     credentials: { apiKey: options.apiKey ?? credentialRef("os", "hypihub.oauth") },
     credentialInputs: { apiKey: {
-      label: "HypiHub login",
+      label: "HypiHub credential",
       acquisition: {
         kind: "oauth2-pkce",
         authorizationEndpoint: new URL("/oauth/consent", oauthOrigin).toString(),

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

@@ -1,5 +1,6 @@
 import {
   compileWireRequest,
+  selectWireModelForRequest,
   generationTypes,
   sealGeneratedAudioSet,
   sealGeneratedImageSet,
@@ -11,12 +12,21 @@ import type { BlobRef, CapabilityRef, CanonicalValue, StoredValue, TypeRef } fro
 import type { EndpointRequest, EndpointSupport } from "@hypit/endpoint-kit";
 import { hypiHubMappings } from "./mapping.js";
 
+export type HypiHubModelOperation = "images" | "image_edits" | "videos" | "audio_speech" | "transcriptions";
+
+/** Request identity is available before resolving any reference into a service URL. */
+export type HypiHubPreparedRequest = {
+  readonly model: string;
+  readonly operation: HypiHubModelOperation;
+  readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<{ readonly model: string; readonly input: CanonicalValue }>;
+};
+
 export type HypiHubRoute = (typeof hypiHubMappings)[number] & {
   readonly key: string;
   readonly returns: TypeRef;
   readonly media: "image" | "video" | "audio";
   readonly supports?: (request: EndpointRequest) => EndpointSupport;
-  readonly compile: (constraints: CanonicalValue, resolve: GenerationArtifactUrlResolver) => Promise<{ readonly model: string; readonly input: CanonicalValue }>;
+  readonly prepare: (constraints: CanonicalValue) => HypiHubPreparedRequest;
   readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
 };
 
@@ -60,11 +70,22 @@ export const hypiHubRoutes: readonly HypiHubRoute[] = hypiHubMappings.map((mappi
         return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
       },
     } : {}),
-    compile: async (constraints, resolve) => {
+    prepare: (constraints) => {
       const request = constraints as unknown as GenerationRequest;
       const rejection = hypiHubGenerationRejection(mapping, request);
       if (rejection !== undefined) throw new Error(rejection);
-      return normalizeHypiHubRequest(mapping, await compileWireRequest(mapping, request, resolve));
+      const model = selectWireModelForRequest(mapping, request);
+      // Image editing is determined by authored media ports, before their URLs exist.
+      const hasReferences = Object.entries(mapping.fields).some(([port, field]) =>
+        (field.as === "url" || field.as === "urlArray" || field.as === "itemObject")
+          && (request.ports[port]?.length ?? 0) > 0);
+      const operation = mapping.result === "audio" ? "audio_speech" : mapping.result === "video" ? "videos"
+        : hasReferences ? "image_edits" : "images";
+      return {
+        model,
+        operation,
+        compile: async (resolve) => normalizeHypiHubRequest(mapping, await compileWireRequest(mapping, request, resolve)),
+      };
     },
     packageResult: (artifacts) => ({
       kind: "inline",

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

@@ -2,6 +2,7 @@ import { requestDeadline } from "@hypit/runtime-kit";
 import { createHash } from "node:crypto";
 
 import type { HypiHubAuth } from "./oauth.js";
+import { HypiHubHttpError, HypiHubServiceError, safeHypiHubReason } from "./errors.js";
 
 type UploadAuth = HypiHubAuth | string;
 
@@ -47,12 +48,6 @@ function apiBaseUrl(value: string): string {
   return `${trimmed.replace(/\/(?:v1beta|v1)$/iu, "")}/v1`;
 }
 
-class HypiHubHTTPError extends Error {
-  constructor(readonly status: number, message: string, readonly retryAfterMs?: number, readonly code?: string) {
-    super(message);
-  }
-}
-
 export type HypiHubUploaderOptions = {
   readonly baseUrl: string;
   readonly requestTimeoutMs: number;
@@ -149,7 +144,7 @@ export class HypiHubUploader {
 
   private safeReason(error: unknown): string {
     const message = error instanceof Error ? error.message : String(error);
-    return message.replace(/https?:\/\/\S+/giu, "[redacted-url]").slice(0, 300);
+    return safeHypiHubReason(message);
   }
 
   private async json(path: string, auth: UploadAuth, init: RequestInit = {}): Promise<Record<string, unknown>> {
@@ -159,7 +154,7 @@ export class HypiHubUploader {
       try {
         return await this.jsonOnce(path, auth, init, Math.max(1, deadline - Date.now()));
       } catch (error) {
-        const http = error instanceof HypiHubHTTPError ? error : undefined;
+        const http = error instanceof HypiHubHttpError ? error : undefined;
         // Existing-session operations are idempotent. A new session may only
         // be retried after an explicit 429 rejection, never an unknown result.
         const retryable = http !== undefined
@@ -200,14 +195,9 @@ export class HypiHubUploader {
         if (response.ok) throw new Error(`HypiHub returned invalid JSON (${response.status})`);
       }
       if (!response.ok) {
-        const errorBody = body !== null && typeof body === "object" && "error" in body ? body.error : undefined;
-        const code = errorBody !== null && typeof errorBody === "object" && "code" in errorBody
-          && typeof errorBody.code === "string" ? errorBody.code : undefined;
-        const retryAfter = response.headers.get("retry-after");
-        const parsedRetry = retryAfter === null ? NaN : /^\d+$/u.test(retryAfter.trim())
-          ? Number(retryAfter) * 1000 : Date.parse(retryAfter) - Date.now();
-        throw new HypiHubHTTPError(response.status, `HypiHub returned HTTP ${response.status}: ${this.safeReason(text)}`,
-          Number.isFinite(parsedRetry) ? Math.max(0, parsedRetry) : undefined, code);
+        throw new HypiHubHttpError(response.status, response, text, {
+          method: init.method ?? "GET", url: `${this.baseUrl}${path}`,
+        });
       }
       return object(body, "HypiHub response");
     } finally {
@@ -365,12 +355,12 @@ export class HypiHubUploader {
       this.log(`multipart upload failed upload=${uploadId} reason=${this.safeReason(error)}`);
       try { await this.json(`/files/uploads/${encodeURIComponent(uploadId)}`, auth, { method: "DELETE" }); }
       catch (cancelError) {
-        if (!(cancelError instanceof HypiHubHTTPError && (cancelError.status === 404
+        if (!(cancelError instanceof HypiHubHttpError && (cancelError.status === 404
           || (cancelError.status === 409 && cancelError.code === "upload_completed")))) {
           this.log(`upload cancellation still pending upload=${uploadId} reason=${this.safeReason(cancelError)}`);
         }
       }
-      throw new Error(this.safeReason(error));
+      throw error instanceof HypiHubServiceError ? error : new Error(this.safeReason(error));
     }
   }
 

package/packages/provider-whisperx-local/README.md

@@ -85,8 +85,14 @@ Program needs restarting, and account for active work using it.
 
 Preparation commands write `install.log`; the running service writes `program.log`, with stderr in
 `program.err.log` on Windows. Inspect the stderr file for Python model-loading and download messages.
+`programs status` reports these files as `installationLogPath`, `logPath` and `errorLogPath` when they
+exist, even before installation finishes. Preparation notices name the Python environment and NLTK
+commands separately. The service logs the start and completion of ASR loading, transcription,
+language-alignment model loading and alignment, with elapsed times. Loading may include a download;
+transfer details come from the underlying client, not an estimated percentage from the Provider.
 The service health endpoint becomes available after ASR loading. A startup readiness wait expiring
-can leave that process still loading; check its reported PID and logs before starting another process.
+can leave that process still loading. Its PID is recorded when spawned; repeated `up` observes it,
+and `programs down` can stop it during loading. PID liveness and service readiness are separate facts.
 
 Python installation, Python packages, NLTK sentence data, ASR weights and language-alignment weights
 are separate downloads. `UV_PYTHON_INSTALL_MIRROR` configures a Python distribution mirror;

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

@@ -126,10 +126,12 @@ export function localWhisperXProgram(options: LocalWhisperXProgramOptions): Mana
         probe: installationProbe,
         prepareBeforeStart: true,
         commands: [{
+          label: "Prepare the locked Python environment",
           command: "uv",
           args: ["sync", "--project", localWhisperXManagedProject, "--frozen", "--no-editable"],
           env: { UV_PROJECT_ENVIRONMENT: environment },
         }, {
+          label: "Prepare NLTK sentence data",
           command: pythonEnvironmentCommand(environment, "hypit-whisperx-prepare"),
           args: ["--nltk-data", nltkData],
           env: { HYPIT_WHISPERX_NLTK_DATA: nltkData },

package/packages/runtime-host-node/src/index.ts

@@ -203,6 +203,8 @@ export type RuntimeHostProviderQuery = {
 export type ManagedProgramProgress = {
   readonly id: string;
   readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
+  readonly logPath?: string;
+  readonly detail?: string;
 };
 
 export type ManagedProgramReport = {
@@ -215,6 +217,8 @@ export type ManagedProgramReport = {
     | { readonly state: "mismatch"; readonly detail: string };
   readonly detail?: string;
   readonly logPath?: string;
+  readonly installationLogPath?: string;
+  readonly errorLogPath?: string;
   readonly pid?: number;
 };
 

package/packages/runtime-kit/README.md

@@ -45,3 +45,6 @@ video package by name.
 before a cold start, even when the installation probe already passes. The declared commands use the
 Provider's ordinary package manager. A healthy running Program is reused before this preparation is
 considered; Runtime does not inspect source files or infer implementation versions.
+`ManagedProgramCommand.label` optionally names a command's purpose for progress and log headings.
+It is display text supplied by the Program owner, not a phase to persist or interpret. Runtime
+reports generic process/probe facts; the service itself owns domain-specific progress in its logs.

package/packages/runtime-kit/src/index.ts

@@ -33,6 +33,8 @@ export type RuntimeDoctorDiagnostic = {
 };
 
 export type ManagedProgramCommand = {
+  /** Optional human-readable purpose, supplied by the program owner. Not a lifecycle state. */
+  readonly label?: string;
   readonly command: string;
   readonly args: readonly string[];
   readonly cwd?: string;

package/packages/runtime-local/README.md

@@ -6,12 +6,29 @@ worklist. Project-owned Build Results hold finished public Outputs.
 Managed Program preparation writes subprocess stdout and stderr directly to that Program's
 `install.log`, so dependency-download output is readable before installation finishes. Installation
 and startup progress expose `logPath`; failed installation reports retain it with a short error.
+Each preparation command adds its owner-supplied purpose (or executable name) and start/end time to
+the log. Command arguments and environment values are not copied into these headings.
 The files belong to the Program's configured state directory. Service output uses `program.log`
 and, on Windows, a separate `program.err.log` for stderr. Keeping installation output separate
 preserves it when Windows opens fresh service logs at startup.
 The CLI retains Program failure reasons, PIDs and log paths in `programs` and `runtime up` reports.
 Human output stays compact for successful preparation; `programs status --verbose` also shows
 ready helpers, and JSON retains the reported details independently of verbosity.
+With `--json`, preparation notices use stderr; stdout remains the final JSON result. Status reports
+existing `installationLogPath`, `logPath` and Windows `errorLogPath` separately. These paths identify
+historical files, not currently running phases.
+
+Each Program Home has OS-owned exclusion for preparation, spawning and stopping. Concurrent lifecycle
+commands for that home return the observed facts and a busy explanation; other Programs remain
+independent. The empty `lifecycle.lock` file is only a lock address. The OS releases ownership on
+command exit; no phase record, expiry, stale-lock deletion or recovery procedure is attached to it.
+This uses the Distribution's existing native binding dependency for POSIX `flock` and Windows
+exclusive file handles, rather than coordinating all services in a central table.
+
+Startup publishes `process.pid` before waiting for the probe, then releases exclusion. Repeated `up`
+observes that live process; `down` can stop it while it is still loading. A readiness observation
+timeout leaves the process alone and reports that it remains alive. This is Program lifecycle
+coordination, separate from Build execution; it does not retry or recover Builds.
 
 A Runtime Profile selects only the environmental parts that genuinely vary:
 

package/packages/runtime-local/package.json

@@ -24,7 +24,8 @@
     "@hypit/runtime-kit": "workspace:*",
     "@hypit/runtime-host-node": "workspace:*",
     "@hypit/store-sqlite": "workspace:*",
-    "@hypit/validation": "workspace:*"
+    "@hypit/validation": "workspace:*",
+    "koffi": "3.2.1"
   },
   "devDependencies": {
     "@hypit/build-result": "workspace:*",

package/packages/runtime-local/src/program-lock.ts

@@ -0,0 +1,40 @@
+import { closeSync, openSync } from "node:fs";
+import { constants } from "node:os";
+import { join, toNamespacedPath } from "node:path";
+import koffi from "koffi";
+
+// The OS owns exclusion and releases it when the calling process exits. The empty file
+// is only an address: never unlink it, infer a phase from it, or expire another owner's lock.
+const library = koffi.load(process.platform === "win32" ? "kernel32.dll" : null);
+const flock = process.platform === "win32" ? undefined : library.func("int flock(int fd, int operation)");
+const createFile = process.platform === "win32"
+  ? library.func("intptr_t __stdcall CreateFileW(const char16_t *path, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t attributes, intptr_t templateFile)") : undefined;
+const lastError = process.platform === "win32" ? library.func("uint32_t __stdcall GetLastError()") : undefined;
+const closeHandle = process.platform === "win32" ? library.func("int __stdcall CloseHandle(intptr_t file)") : undefined;
+
+/** Try once. An occupied program returns immediately; unrelated programs remain independent. */
+export function tryProgramLock(directory: string): (() => void) | undefined {
+  const path = join(directory, "lifecycle.lock");
+  let close: () => void;
+  if (createFile !== undefined) {
+    // OPEN_ALWAYS, no sharing: exclusive while the handle is open, including across CLI processes.
+    const handle = createFile(toNamespacedPath(path), 0xc0000000, 0, null, 4, 0x80, 0);
+    if (handle === -1 || handle === -1n) {
+      const code = lastError!();
+      if (code === 32 || code === 33) return undefined;
+      throw new Error(`Cannot acquire Program ownership at ${path}: Windows error ${code}`);
+    }
+    close = () => { closeHandle!(handle); };
+  } else {
+    const fd = openSync(path, "a");
+    if (flock!(fd, 2 | 4) !== 0) { // LOCK_EX | LOCK_NB
+      const code = koffi.errno();
+      closeSync(fd);
+      if (code === constants.errno.EAGAIN || code === constants.errno.EWOULDBLOCK) return undefined;
+      throw new Error(`Cannot acquire Program ownership at ${path}: errno ${code}`);
+    }
+    close = () => { closeSync(fd); };
+  }
+  let released = false;
+  return () => { if (!released) { released = true; close(); } };
+}