@hypit/hypit 0.1.7 → 0.1.9

package/packages/cli/src/machine-view.ts

@@ -9,6 +9,8 @@ type ProgramStateView = {
   readonly detail?: string;
   readonly pid?: number;
   readonly logPath?: string;
+  readonly installationLogPath?: string;
+  readonly errorLogPath?: string;
 };
 type AttentionView = { readonly message: string; readonly action?: string };
 
@@ -18,12 +20,12 @@ export type OperationalMachineView =
   | { readonly format: "hypit.cli-runtime-selection@1"; readonly selected: boolean; readonly removed?: boolean; readonly profile?: string; readonly project?: string }
   | { readonly format: "hypit.cli-paths@1"; readonly project: string; readonly projectState: string; readonly profileSource: "argument" | "project" | "none"; readonly selectionFile: string; readonly profile?: string; readonly runtimeData?: string; readonly hostState: string; readonly machinePackages: string; readonly distribution?: string }
   | { readonly format: "hypit.cli-package@1"; readonly action: "install" | "status"; readonly package: string; readonly ready: boolean }
-  | { readonly format: "hypit.cli-programs@1"; readonly action: "up" | "down" | "status"; readonly ready: boolean; readonly programCount: number; readonly readyCount: number; readonly programs: readonly ProgramStateView[]; readonly omittedPrograms?: number }
+  | { readonly format: "hypit.cli-programs@1"; readonly action: "up" | "down" | "status"; readonly ok: boolean; readonly ready: boolean; readonly programCount: number; readonly readyCount: number; readonly programs: readonly ProgramStateView[]; readonly omittedPrograms?: number }
   | { readonly format: "hypit.cli-runtime-up@1"; readonly ready: boolean; readonly worker: string; readonly preparedPackages: number; readonly programs: { readonly total: number; readonly ready: number; readonly items: readonly ProgramStateView[] } }
   | { readonly format: "hypit.cli-runtime-logs@1"; readonly lines: readonly string[]; readonly totalLines: number; readonly omittedLines: number; readonly path?: string }
   | { readonly format: "hypit.cli-runtime-down@1"; readonly worker: string }
   | { readonly format: "hypit.cli-runtime-status@1"; readonly ready: boolean; readonly attention: boolean; readonly worker: { readonly state: string; readonly configuration?: string }; readonly builds: Readonly<Record<string, number>>; readonly programs: { readonly total: number; readonly ready: number; readonly unavailable: readonly ProgramStateView[] }; readonly capacity: { readonly active: number } }
-  | { readonly format: "hypit.cli-auth-status@1"; readonly endpoint: string; readonly credentials: readonly { readonly endpoint: string; readonly slot: string; readonly label: string; readonly kind: string; readonly configured: boolean; readonly writable: boolean }[]; readonly omittedCredentials?: number }
+  | { readonly format: "hypit.cli-auth-status@1"; readonly endpoint: string; readonly credentials: readonly { readonly endpoint: string; readonly slot: string; readonly label: string; readonly kind: string; readonly configured: boolean; readonly writable: boolean; readonly acquisition?: { readonly kind: string; readonly authorizationEndpoint: string } }[]; readonly omittedCredentials?: number }
   | { readonly format: "hypit.cli-auth-change@1"; readonly endpoint: string; readonly slot: string; readonly configured: boolean; readonly changed?: boolean }
   | { readonly format: "hypit.cli-builds@1"; readonly builds: readonly { readonly id: string; readonly createdAt: string; readonly title?: string; readonly outcome: string; readonly run?: string; readonly targetCount: number; readonly targets?: readonly string[]; readonly omittedTargets?: number; readonly outputCount: number }[]; readonly next?: string }
   | { readonly format: "hypit.cli-history@1"; readonly output: string; readonly source?: string; readonly entries: readonly { readonly build: string; readonly title?: string; readonly createdAt: string; readonly outcome: string; readonly output: CliOutputView }[]; readonly next?: string }

package/packages/cli/src/main.ts

@@ -17,6 +17,7 @@ import { createPlanOutput, createPricingOutput, writeCliHelp, writeCliOutput } f
 import type { CliIo, CliMachineView } from "./output.js";
 import { parseCommand } from "./arguments.js";
 import type { CliCommand, RuntimeOption } from "./command.js";
+import { commandHint } from "./command-hint.js";
 import { assertPlannedRequests, assertPreflight, createCatalogDescriptor, describePlanNeeds, describePlanPricing, describePlanProviders, evaluatePlanNeeds, preflightPlan } from "./build-planning.js";
 import { buildProgressLines, observeBuild } from "./observation.js";
 import { isProjectResultCommand, runProjectResultCommand } from "./commands/results.js";
@@ -62,7 +63,8 @@ export async function runCli(
   distribution: CliDistribution,
 ): Promise<void> {
   if (argv.length === 0 || argv[0] === "help" || argv.includes("--help")) {
-    const topic = argv[0] === "help" ? argv[1] : argv.includes("--help") ? argv[0] : undefined;
+    const topic = argv[0] === "help" ? argv[1] : argv[0] === "--help" ? undefined
+      : argv.includes("--help") ? argv[0] : undefined;
     writeCliHelp(io, topic);
     return;
   }
@@ -179,14 +181,11 @@ export async function runCli(
 
   let runtimeProfile = acceptsRuntimeContext(args) ? args.runtimeProfile : undefined;
   let runtimeSelectionFile: string | undefined;
-  const runtimeWasExplicit = runtimeProfile !== undefined;
-  let runtimeNeedsHint = runtimeWasExplicit;
   if (acceptsRuntimeContext(args) && runtimeProfile === undefined && args.command !== "logs") {
     const selected = await findRuntimeProfile(await commandProjectRoot());
     if (selected !== undefined) {
       runtimeProfile = selected.profile;
       runtimeSelectionFile = selected.selectionFile;
-      runtimeNeedsHint = false;
     }
   }
   const runtimeController = async (profile: string): Promise<CliRuntimeController> => {
@@ -227,6 +226,7 @@ export async function runCli(
   if (isExecutionCommand(args)) {
     await runExecutionCommand({
       args,
+      projectRoot: await commandProjectRoot(),
       runtimeProfile,
       io,
       runtimeHost,
@@ -346,6 +346,7 @@ export async function runCli(
     if (runtimeProfile === undefined) {
       throw new Error("build requires a Runtime; run hypit runtime init, select one with runtime use, or pass --runtime <profile>");
     }
+    const commandScope = { projectRoot: projectResultsRoot, runtimeProfile: resolve(runtimeProfile) };
     const buildResults = await projectResults(projectResultsRoot);
     let loadedRun;
     try {
@@ -434,7 +435,7 @@ export async function runCli(
         ]),
       ].join(" · ");
       if (args.follow && "view" in built && !args.presentation.json) {
-        const acceptedView = buildStatusView({ id: built.id, runtime: built.view });
+        const acceptedView = buildStatusView({ id: built.id, runtime: built.view, commandScope });
         const targets = built.view.targets.slice(0, args.limit);
         writeOperational({
           format: "hypit.cli-build@1",
@@ -451,15 +452,15 @@ export async function runCli(
         built = await observeBuild(runtime, built, {
           ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
           controller,
+          commandScope,
           readResult: async () => await buildResults.repository.read(built.id),
-          ...(args.presentation.json ? {} : {
-            onProgress: (progress) => {
-              for (const line of buildProgressLines(progress, {
-                verbose: args.presentation.verbose,
-                limit: args.limit,
-              })) io.write(`${line}\n`);
-            },
-          }),
+          onProgress: (progress) => {
+            const report = io.writeProgress ?? (args.presentation.json ? undefined : io.write);
+            for (const line of buildProgressLines(progress, {
+              verbose: args.presentation.verbose,
+              limit: args.limit,
+            })) report?.(`${line}\n`);
+          },
         });
       }
       const finished = "completion" in built;
@@ -490,6 +491,7 @@ export async function runCli(
       });
       const buildView = buildStatusView({
         id: built.id,
+        commandScope,
         ...(activeView === undefined ? {} : { runtime: activeView }),
         ...(finishedResult === undefined ? {} : { result: finishedResult }),
         verbose: args.presentation.verbose,
@@ -500,7 +502,7 @@ export async function runCli(
           ? buildView
           : { ...buildView, title: args.title },
       };
-      const runtimeHint = runtimeNeedsHint ? ` --runtime ${runtimeProfile}` : "";
+      const resultScope = { projectRoot: projectResultsRoot };
       const resultTargets = finishedResult?.targets.flatMap((name) => {
         const output = finishedResult.outputs[name];
         return output === undefined ? [] : [{ name, output }];
@@ -508,11 +510,11 @@ export async function runCli(
       const finishedLines = resultTargets.length === 0 && targetPresentations.length === 0
         ? [
             ...(completionReason === undefined ? [] : [`Reason   ${completionReason}`]),
-            `Inspect  hypit inspect ${built.id}`,
+            `Inspect  ${commandHint(["inspect", built.id], resultScope)}`,
           ]
         : [
             ...(completionReason === undefined ? [] : [`Reason   ${completionReason}`]),
-            `Inspect  hypit inspect ${built.id}`,
+            `Inspect  ${commandHint(["inspect", built.id], resultScope)}`,
             ...resultTargets
               .filter((item) => item.output.value.kind === "inline")
               .slice(0, args.limit)
@@ -523,14 +525,14 @@ export async function runCli(
               .filter((item) => item.output.value.kind !== "inline")
               .slice(0, args.limit)
               .map((item) =>
-                `Export   hypit get ${built.id} --output ${item.name} --to <path>`),
+                `Export   ${commandHint(["get", built.id, "--output", item.name], resultScope)} --to <path>`),
             ...(resultTargets.length > 0 ? [] : targetPresentations
               .filter((item) => item.inline !== undefined)
               .slice(0, args.limit)
               .map((item) => `Result   ${item.published.name} = ${item.inline}`)),
           ];
       const humanTitle = issue !== undefined
-        ? "Result needs attention"
+        ? "Build needs attention"
         : finished
           ? buildOutcome === "complete"
             ? "Build complete"
@@ -550,14 +552,14 @@ export async function runCli(
           ] : []),
           ...(issue === undefined ? [] : [
             ["Execution", buildOutcome ?? machine.build.work.state] as const,
-            ["Result", "needs attention"] as const,
+            [issue.scope === "cleanup" ? "Cleanup" : "Result", "needs attention"] as const,
           ]),
         ], finished ? finishedLines : issue !== undefined ? [
-          `Result   ${issue.scope}: ${issue.message}`,
-          `Finish   hypit result finish ${built.id}${runtimeHint}`,
+          `Attention  ${issue.scope}: ${issue.message}`,
+          `Finish   ${commandHint(["result", "finish", built.id], commandScope)}`,
         ] : [
-          `Watch    hypit status ${built.id}${runtimeHint} --watch`,
-          `Cancel   hypit cancel ${built.id}${runtimeHint}`,
+          `Watch    ${commandHint(["status", built.id, "--watch"], commandScope)}`,
+          `Cancel   ${commandHint(["cancel", built.id], commandScope)}`,
         ]);
       if (buildOutcome === "failed" || issue !== undefined) io.setExitCode?.(1);
     } finally {

package/packages/cli/src/observation.ts

@@ -1,6 +1,8 @@
 import type { BuildResultManifest } from "@hypit/build-result";
 
 import type { CliBuildSubmission, CliBuildView, CliRuntimeControl, CliRuntimeController } from "./runtime-port.js";
+import { commandHint } from "./command-hint.js";
+import type { CommandScope } from "./command-hint.js";
 import { formatOperationProgress } from "./runtime-view.js";
 
 const FIRST_HEARTBEAT_MS = 30_000;
@@ -122,6 +124,7 @@ export async function observeBuildView(
     readonly maxWaitMs?: number;
     readonly controller?: CliRuntimeController;
     readonly onProgress?: (value: BuildProgressView) => void;
+    readonly commandScope?: CommandScope;
   } = {},
 ): Promise<CliBuildView | undefined> {
   let view: CliBuildView | undefined = initial;
@@ -158,8 +161,9 @@ export async function observeBuildView(
       const worker = await options.controller.worker.status();
       if (worker.state !== "running") {
         throw new Error(
-          `Runtime Worker is ${worker.state}; Build ${build} remains durable. `
-          + `Run hypit runtime up, then run hypit status ${build} --watch again`,
+          `Runtime Worker is ${worker.state}; stopped watching Build ${build}. `
+          + `Inspect the Runtime with ${commandHint(["runtime", "status"], options.commandScope)}; `
+          + `read execution evidence with ${commandHint(["logs", build], options.commandScope)}`,
         );
       }
     }
@@ -184,6 +188,7 @@ export async function observeBuild(
     readonly controller?: CliRuntimeController;
     readonly readResult: () => Promise<BuildResultManifest | undefined>;
     readonly onProgress?: (value: BuildProgressView) => void;
+    readonly commandScope?: CommandScope;
   },
 ): Promise<CliBuildSubmission> {
   const finishFromResult = async (): Promise<CliBuildSubmission> => {

package/packages/cli/src/output.ts

@@ -3,6 +3,7 @@ import { relative, resolve } from "node:path";
 import type { CanonicalValue } from "@hypit/protocol";
 
 import type { OperationalMachineView } from "./machine-view.js";
+import { CliUsageError } from "./usage-error.js";
 
 export type CliTerminal = {
   readonly isTTY: boolean;
@@ -970,6 +971,9 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       "  hypit auth login <endpoint-instance> [--runtime <profile>] [--slot <name>] [--from <secret-file>]",
       "  hypit auth logout <endpoint-instance> [--runtime <profile>] [--slot <name>]",
       "  All auth actions accept --workspace <project> to use that project's selection.",
+      "  status shows credential presence and the Provider's declared browser login, if any.",
+      "  login opens that browser flow or securely prompts for the secret; --from imports a secret instead.",
+      "  Configure the service's Endpoint first. Storing a key does not install a Provider or select bindings.",
     ],
   };
   const selected = topics[topic];
@@ -986,6 +990,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
       io.write(`${selected.join("\n")}\n`);
       return;
     }
+    throw new CliUsageError(`Unknown help topic ${JSON.stringify(topic)}`, "hypit help");
   }
   io.write([
     colors.accent(colors.strong("Hypit")),
@@ -1044,6 +1049,7 @@ export function renderCliError(error: unknown, options: {
       error: {
         code,
         message: source.message,
+        ...(source instanceof CliUsageError ? { help: source.help } : {}),
         ...(options.debug && trace !== undefined && trace.length > 0 ? { trace } : {}),
       },
     }, null, 2)}\n`;
@@ -1058,6 +1064,8 @@ export function renderCliError(error: unknown, options: {
   ];
   if (options.debug && trace !== undefined && trace.length > 0) {
     lines.push("", colors.dim(trace));
+  } else if (source instanceof CliUsageError) {
+    lines.push("", `Usage    ${source.help}`);
   } else {
     lines.push("", colors.dim("Run with --debug to include the internal stack trace."));
   }

package/packages/cli/src/usage-error.ts

@@ -0,0 +1,8 @@
+/** Argument errors point to public usage rather than an internal stack trace. */
+export class CliUsageError extends Error {
+  readonly code = "CLI_USAGE";
+  constructor(message: string, readonly help: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CliUsageError";
+  }
+}

package/packages/cli/src/view.ts

@@ -8,6 +8,8 @@ import type {
 import { buildIdCreatedAt } from "@hypit/protocol";
 import type { TypeRef } from "@hypit/protocol";
 import type { BuildView } from "@hypit/runtime-host-node";
+import { commandHint } from "./command-hint.js";
+import type { CommandScope } from "./command-hint.js";
 
 export type PublicOutputKind = "scalar" | "resource" | "composite";
 
@@ -159,6 +161,7 @@ export function buildStatusView(options: {
   readonly result?: BuildResultManifest;
   readonly resultReadError?: string;
   readonly verbose?: boolean;
+  readonly commandScope?: CommandScope;
 }): CliBuildStatusView {
   const resultState = options.resultReadError !== undefined
     ? "unavailable" as const
@@ -195,7 +198,7 @@ export function buildStatusView(options: {
       attention: issue !== undefined
         ? {
             message: issue.message,
-            ...(issue.scope === "result" ? { action: `hypit result finish ${options.id}` } : {}),
+            action: commandHint(["result", "finish", options.id], options.commandScope),
           }
         : { message: options.resultReadError! },
     }),

package/packages/driver-node/README.md

@@ -17,6 +17,11 @@ Build. Credentials are resolved only for slots declared by the selected endpoint
 of the same credential are coalesced. Cancellation is best effort and never rolls back completed work.
 A failed action retains its receipt and error for the Result; the Driver does not retry or reconcile it.
 
+Immediate calls and asynchronous submit, poll and collect actions receive the same progress and
+diagnostic callbacks. Progress reaches the caller while the action is running; changes of phase also
+enter the execution log. The Endpoint supplies the content, and the Driver forwards it with the
+selected Endpoint identity without interpreting service-specific phases or treating progress as a receipt.
+
 `acceptOperation()` validates an already received value without making a remote call. Runtime can
 retain such a sibling result when another Need fails, without polling unfinished jobs to completion.
 The Driver validates returned values before offering a command result to Core. It does not load

package/packages/driver-node/src/driver.ts

@@ -22,6 +22,7 @@ import type {
   CredentialStore,
   CredentialValue,
   OperationSnapshot,
+  OperationProgress,
   OperationStore,
   RuntimeExecutionContext,
   RuntimeExecutionResult,
@@ -349,6 +350,23 @@ export class NodeDriver {
     return result;
   }
 
+  #endpointObservers(endpoint: string, context?: RuntimeExecutionContext) {
+    let phase: string | undefined;
+    return {
+      reportProgress: async (progress: OperationProgress) => {
+        await context?.reportProgress?.({ endpoint, progress });
+        if (progress.phase !== phase) {
+          phase = progress.phase;
+          await context?.recordExecution?.({ endpoint, kind: "phase", phase });
+        }
+      },
+      ...(context?.recordExecution === undefined ? {} : {
+        reportDiagnostic: (diagnostic: import("@hypit/runtime").ExecutionDiagnostic) =>
+          context.recordExecution!({ endpoint, kind: "diagnostic", ...diagnostic }),
+      }),
+    };
+  }
+
   async #advanceOperationStep(
     operation: OperationSnapshot,
     registration: EndpointRegistration,
@@ -374,10 +392,7 @@ export class NodeDriver {
         command: structuredClone(command), need: structuredClone(command.need),
         resources: this.#resourceStore(operation.build), operation: operation.id,
         credentials: await this.#endpointCredentials({ ...registration, credentials: operation.credentials ?? registration.credentials ?? {} }),
-        ...(runtimeContext.recordExecution === undefined ? {} : {
-          reportDiagnostic: (diagnostic: import("@hypit/runtime").ExecutionDiagnostic) =>
-            runtimeContext.recordExecution!({ endpoint: operation.endpoint, kind: "diagnostic", ...diagnostic }),
-        }),
+        ...this.#endpointObservers(operation.endpoint, runtimeContext),
         checkpoint: async (checkpoint: import("@hypit/endpoint-kit").EndpointCheckpoint) => {
           await operations.update(operation.id, { status: "pending", ...checkpoint,
             submission: "accepted", acknowledgedAt: operation.acknowledgedAt ?? Date.now(), wakeAt: Date.now(), progress: { phase: checkpoint.remoteEnded ? "collecting" : "submitted" } });
@@ -493,7 +508,6 @@ export class NodeDriver {
         );
       }
     }
-    let phase: string | undefined;
     await context?.recordExecution?.({ endpoint: executable.endpointId, kind: "started" });
     try {
       const result = await executable.registration.handler({
@@ -501,16 +515,7 @@ export class NodeDriver {
         need: structuredClone(executable.command.need),
         resources: this.#resourceStore(context?.build),
         credentials: await this.#endpointCredentials(executable.registration),
-        reportProgress: async (progress) => {
-          await context?.reportProgress?.({ endpoint: executable.endpointId, progress });
-          if (progress.phase !== phase) {
-            phase = progress.phase;
-            await context?.recordExecution?.({ endpoint: executable.endpointId, kind: "phase", phase });
-          }
-        },
-        ...(context?.recordExecution === undefined ? {} : {
-          reportDiagnostic: (diagnostic) => context.recordExecution!({ endpoint: executable.endpointId, kind: "diagnostic", ...diagnostic }),
-        }),
+        ...this.#endpointObservers(executable.endpointId, context),
       });
       const event = await this.#endpointEvent(state, executable, result);
       await context?.recordExecution?.({ endpoint: executable.endpointId, kind: "completed" });

package/packages/endpoint-kit/README.md

@@ -35,12 +35,21 @@ without changing Core demand. Each resource declares a `limit` and optional `uni
 A capability may add `resources` and a pure `unitsForRequest(request)` resolver for quantities of
 already declared resources. Runtime admits all claims atomically for one `fulfill-need` Command.
 
-A long immediate call can report its current activity with
+A running immediate call or asynchronous action can report its current activity with
 `await context.reportProgress?.({ phase: "processing", completed: 12, total: 40, unit: "items" })`.
 The Provider chooses meaningful phases and quantities and reports non-secret, human-readable facts.
 The Runtime attaches them to the currently executing Command; they do not change its outcome,
 scheduling or Core facts. Completion clears the live activity. Direct callers may omit the callback.
-For asynchronous work, return `progress` in the existing pending outcome instead.
+For asynchronous work, these callbacks describe work inside `start`, `poll` or `collect`, such as
+preparing references or downloading results. A returned `pending.progress` describes the acknowledged
+remote task between actions. Neither form of progress substitutes for a received task ID or receipt.
+
+Separate facts available from the request from actions needed to fulfill it. Check known input
+limits and determine the requested service operation before transferring its resources. If the
+service exposes account-specific capability information, use that evidence for the selected request;
+an API without such a query needs no invented discovery step. A Provider owns the meaning of its
+public error codes and reasons. Preserve the failed operation and that evidence, distinguishing what
+was never submitted from a submission whose remote outcome is unknown.
 
 Asynchronous execution moves forward through `start`, `poll`, and optional `collect`. `start` returns
 a task handle; `pending` means an acknowledged task is still running. `ready` records remote completion

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

@@ -101,7 +101,7 @@ export type EndpointInvocationContext = {
   readonly credentials: Readonly<Record<string, EndpointCredential>>;
   /** Explicit non-secret diagnostic output. The Provider owns its content, never its storage. */
   readonly reportDiagnostic?: (diagnostic: import("@hypit/runtime").ExecutionDiagnostic) => Promise<void>;
-  /** Report non-secret activity of a long local call without creating a remote Operation. */
+  /** Report non-secret activity while an immediate call or asynchronous action is still running. */
   readonly reportProgress?: (progress: OperationProgress) => Promise<void>;
 };
 

package/packages/generation/README.md

@@ -9,6 +9,16 @@ implementations. `sealGenerationPortTable` describes a model's inputs; `Generati
 `selectWireModelForRequest` applies the same route selection without resolving media bytes. During
 planning, a Provider may add the model-port names already attached as future graph inputs; the
 selector does not inspect graph structure or interpret media roles.
+Route selection here applies declared input-mode mappings for the already chosen exact capability;
+it does not search for an alternative model, service or account.
+
+`compileWireRequest` awaits its media URL resolver, so compilation can have external effects when
+that resolver uploads files. Use `selectWireModelForRequest` for request identity and known-port
+checks before those effects; pricing and execution can share the same mapping. A Provider can also
+describe its API operation from the authored ports. Service-specific support queries belong to that
+Provider and only use operations its API actually exposes. The generic helper neither queries a
+catalogue nor switches to another route after a failure. Actual URL resolution belongs to request
+execution, not to discovering a model name or making a planning placeholder.
 
 The package owns `GenerationRequest`, `GeneratedImageSet` and `GeneratedVideoSet` identities,
 schemas, validators and graph facets. Generated sets are atomic Products: a Provider persists the

package/packages/provider-hypihub/README.md

@@ -16,7 +16,7 @@ admits them into the current Build's working byte area. Image references use Hyp
 `reference_image_urls`, `reference_videos`, and `reference_audios` fields. A single reference video
 remains in `reference_videos`; `ref_video_url` is reserved for a model's source-video port. First/last-frame images use `first_frame` and `last_frame`.
 
-Seedance 2.5 (`@hypit/seedance` model `2.5`) maps to `bytedance/seedance-2-5` and supports
+Seedance 2.5 (`@hypit/seedance` model `2.5`) maps to `seedance-2.5` and supports
 `480p`, `720p` and `1080p`. The Provider passes the authored `resolution` to `POST /v1/videos`;
 omitting it in the Seedance Surface defaults to `720p`.
 
@@ -31,11 +31,44 @@ The current HypiHub GPT Image 2 route has these service-specific limits:
 HypiHub owns this support check independently: it leaves the GPT Image model package unchanged. When the service surface changes, this Provider can change without changing
 the model or another Provider.
 
-Model identity is preserved across input modes: Seedream 5 Lite references use the Lite image-edit
-route, and Grok 1.5 Preview remains the Preview model. A deployment's current catalogue may offer
+Model identity and input mode are separate. The mapping uses HypiHub's canonical model names:
+`gpt-image-2`, `seedream-5-lite`, `minimax-h3`, `grok-imagine-video` and the individual Seedance names.
+An image request without references uses `/images/generations`; image edits use `/images/edits`
+with the same model name. Video requests use `/videos`, preserving reference images, reference
+videos and first/last frames in their distinct fields. Old operation-specific names are not needed
+to express these modes; compatibility with previously released clients belongs to the service.
+
+Seedream 5 Lite remains Lite across input modes, and Grok 1.5 Preview remains Preview.
+A deployment's current catalogue may offer
 newer models or omit one implemented here. Availability and unsupported-input errors retain their
 service explanation; they do not imply expired credentials or authorize substituting another model.
 
+Before resolving or uploading references, the Provider prepares the exact model and operation from
+the authored ports and its mapping, then queries that model's authenticated directory entry. Image
+editing is determined from the mapped media inputs, without manufacturing placeholder URLs or
+uploading to discover the request mode. The same preparation serves images, videos and speech.
+The request is then translated with real reference URLs and submitted to the selected operation.
+These are internal Provider functions; Author Sources, CLI commands and Runtime scheduling are unchanged.
+
+Progress identifies the directory query, request preparation and submission. A directory failure
+retains the model, operation and service evidence, and states that this invocation uploaded no
+references and submitted no generation. A missing or malformed operation list leaves support unknown;
+an explicit list without the requested operation reports the actual list. No alternative model,
+operation or account is attempted. Directory support alone does not establish balance, every input
+combination or eventual generation success. Preparation failure also reports that generation was not
+submitted; an interrupted submission retains its actual evidence without claiming no remote work exists.
+
+The Provider interprets HypiHub's [HTTP errors](https://hypit.ai/api-reference/errors/) and
+[job errors](https://hypit.ai/api-reference/jobs/) locally. Failures retain the service code,
+HTTP method/route/status, requested model and `X-Request-Id` when available, plus the public reason.
+`Retry-After` remains evidence and does not start another generation attempt. Job failures retain
+`error_code`, `error` and their receipt even when the create response is already terminal.
+Known error messages are not cut to a fixed prefix; only an unstructured non-JSON response uses
+a marked excerpt. Unrelated response fields and signed asset URLs are not diagnostic content.
+Runtime and Result retain ordinary failure codes/messages without interpreting HypiHub fields.
+Immediate Endpoint exceptions keep the same evidence in their message. A `401` alone does not
+choose OAuth over API-key configuration or establish that another login will fix the account.
+
 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`).
@@ -122,8 +155,10 @@ catalog to verify configured capabilities; ordinary preflight never makes that r
 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.
+generation, alignment, Voice Design and Voice Clone through the same mechanism. The document's
+per-operation prices are retained alongside its default price, including when references are still
+pending. A model's default price is not a quote for every input mode. The Provider does not maintain
+a second list of billing formulas or calculate a request total.
 
 The Provider declares its implemented speech capabilities alongside image, video and alignment.
 Voice Design produces an accepted voice-reference Resource, and Voice Clone uses that
@@ -148,7 +183,7 @@ Execution policy remains local to this Provider:
 | `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 |
+| `operationTimeoutMs` | 20 minutes | how long this Provider observes one asynchronous operation; expiry does not cancel the remote job |
 | `uploadConcurrency` | 8 | whole file sessions per origin/credential within this process |
 | `uploadPartTimeoutMs` | 5 minutes | one upload part |
 | `uploadPartAttempts` | 3 | attempts for one upload part |

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

@@ -0,0 +1,61 @@
+/** HypiHub's public error envelope, kept at the service boundary. */
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// Responses may mention a signed asset URL. Keep the reason, not its access capability.
+export function safeHypiHubReason(value: string): string {
+  return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class HypiHubServiceError extends Error {
+  constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class HypiHubHttpError extends HypiHubServiceError {
+  readonly retryAfterMs?: number;
+  constructor(readonly status: number, response: { readonly headers: Headers }, bodyText: string,
+    request: { readonly method: string; readonly url: string; readonly model?: string }) {
+    let body: Record<string, unknown> | undefined;
+    try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }
+    const error = record(body?.error);
+    const flatError = text(body?.error);
+    const code = text(error?.code)
+      ?? (flatError !== undefined && /^[a-z][a-z0-9_]*$/iu.test(flatError) ? flatError : "HYPIHUB_HTTP_ERROR");
+    const reason = text(error?.message) ?? text(body?.error_description)
+      ?? (flatError !== code ? flatError : undefined)
+      ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+    const url = new URL(request.url);
+    const model = request.model ?? url.searchParams.get("model")
+      ?? (url.pathname.includes("/models/") ? decodeURIComponent(url.pathname.split("/models/")[1]!) : undefined);
+    const requestId = text(response.headers.get("x-request-id"));
+    const retryAfter = text(response.headers.get("retry-after"));
+    const facts = [
+      `HypiHub HTTP ${status}`, code, `${request.method} ${url.origin}${url.pathname}`,
+      ...(model == null ? [] : [`model=${model}`]),
+      ...(requestId === undefined ? [] : [`request=${requestId}`]),
+      ...(retryAfter === undefined ? [] : [`retry-after=${retryAfter}`]),
+    ];
+    super(code, `${facts.join("; ")}${reason === undefined ? "" : `: ${safeHypiHubReason(reason)}`}`
+      + (body === undefined && bodyText.length > 2000 ? " [response excerpt truncated]" : ""));
+    const delay = retryAfter === undefined ? NaN : /^\d+$/u.test(retryAfter)
+      ? Number(retryAfter) * 1000 : Date.parse(retryAfter) - Date.now();
+    if (Number.isFinite(delay)) this.retryAfterMs = Math.max(0, delay);
+  }
+}
+
+export function hypiHubJobFailure(job: Record<string, unknown>, id: string): HypiHubServiceError | undefined {
+  const status = job.status;
+  if (!["failed", "queue_expired", "canceled", "cancelled"].includes(String(status))) return undefined;
+  const error = record(job.error);
+  const code = text(job.error_code) ?? text(error?.code) ?? "HYPIHUB_JOB_FAILED";
+  const reason = text(job.error) ?? text(error?.message) ?? text(job.message) ?? text(job.reason) ?? text(job.detail);
+  const model = text(job.model);
+  return new HypiHubServiceError(code,
+    `HypiHub job ${id} ${status}; ${code}${model === undefined ? "" : `; model=${model}`}`
+    + (reason === undefined ? "" : `: ${safeHypiHubReason(reason)}`));
+}

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

@@ -12,8 +12,8 @@ const MIMO_SPEECH: ModuleRef = { name: "@hypit/mimo-speech", version: "1" };
 const FISHAUDIO_SPEECH: ModuleRef = { name: "@hypit/fishaudio-speech", version: "1" };
 const ELEVENLABS_SPEECH: ModuleRef = { name: "@hypit/elevenlabs-speech", version: "1" };
 
-const seedance = (name: string, model: string): GenerationWireMapping => ({
-  capability: { module: SEEDANCE, name }, result: "video", routes: [{ model }],
+const seedance = (name: string): GenerationWireMapping => ({
+  capability: { module: SEEDANCE, name }, result: "video", routes: [{ model: name }],
   fields: {
     prompt: { as: "value", field: "prompt" },
     referenceImage: { as: "urlArray", field: "reference_image_urls", resourceFields: ["personReference"] },
@@ -38,15 +38,12 @@ export const hypiHubMappings: readonly GenerationWireMapping[] = [
       format: { as: "value", field: "format", whenAbsent: "WEBM" },
     },
   },
-  seedance("seedance-2", "bytedance/seedance-2"),
-  seedance("seedance-2-fast", "bytedance/seedance-2-fast"),
-  seedance("seedance-2-mini", "bytedance/seedance-2-mini"),
-  seedance("seedance-2.5", "bytedance/seedance-2-5"),
+  seedance("seedance-2"),
+  seedance("seedance-2-fast"),
+  seedance("seedance-2-mini"),
+  seedance("seedance-2.5"),
   {
-    capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image", routes: [
-      { model: "gpt-image-2-image-to-image", whenPresent: ["images"] },
-      { model: "gpt-image-2-text-to-image" },
-    ],
+    capability: { module: GPT_IMAGE, name: "gpt-image-2" }, result: "image", routes: [{ model: "gpt-image-2" }],
     fields: {
       prompt: { as: "value", field: "prompt" },
       aspectRatio: { as: "value", field: "aspect_ratio" },
@@ -66,10 +63,7 @@ export const hypiHubMappings: readonly GenerationWireMapping[] = [
     },
   })),
   {
-    capability: { module: SEEDREAM, name: "seedream-5-lite" }, result: "image", routes: [
-      { model: "seedream/5-lite-image-to-image", whenPresent: ["images"] },
-      { model: "seedream/5-lite-text-to-image" },
-    ],
+    capability: { module: SEEDREAM, name: "seedream-5-lite" }, result: "image", routes: [{ model: "seedream-5-lite" }],
     fields: {
       prompt: { as: "value", field: "prompt" },
       aspectRatio: { as: "value", field: "aspect_ratio" },
@@ -80,13 +74,7 @@ export const hypiHubMappings: readonly GenerationWireMapping[] = [
     },
   },
   {
-    capability: { module: MINIMAX, name: "minimax-h3" }, result: "video", routes: [
-      { model: "minimax-h3/image-to-video", whenPresent: ["lastFrame"] },
-      { model: "minimax-h3/image-to-video", whenPresent: ["firstFrame"] },
-      { model: "minimax-h3/reference-to-video", whenPresent: ["referenceImage"] },
-      { model: "minimax-h3/reference-to-video", whenPresent: ["referenceVideo"] },
-      { model: "minimax-h3/text-to-video" },
-    ],
+    capability: { module: MINIMAX, name: "minimax-h3" }, result: "video", routes: [{ model: "minimax-h3" }],
     fields: {
       prompt: { as: "value", field: "prompt" }, duration: { as: "value", field: "seconds" },
       resolution: { as: "value", field: "resolution", whenAbsent: "2k" }, aspectRatio: { as: "value", field: "aspect_ratio" },
@@ -98,10 +86,7 @@ export const hypiHubMappings: readonly GenerationWireMapping[] = [
     },
   },
   {
-    capability: { module: GROK, name: "grok-imagine-video" }, result: "video", routes: [
-      { model: "grok-imagine/image-to-video", whenPresent: ["images"] },
-      { model: "grok-imagine/text-to-video" },
-    ],
+    capability: { module: GROK, name: "grok-imagine-video" }, result: "video", routes: [{ model: "grok-imagine-video" }],
     fields: {
       prompt: { as: "value", field: "prompt" }, duration: { as: "value", field: "seconds" },
       resolution: { as: "value", field: "resolution" }, aspectRatio: { as: "value", field: "aspect_ratio" },