Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat(plan): name the Provider and price page behind each request

kashorin7a0a3253835d
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index 36b77fc2..bdae6104 100644
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@ -140,6 +140,12 @@ the Runtime has resolved that Endpoint's declared credential slots. It may make
request to the real service, such as reading the authenticated model catalog. It must not be called by
Build preflight and must never submit generation work.
+A Provider that charges declares where it publishes prices, and nothing more: `pricing: { kind: "page",
+url }` on `defineEndpointPackage`, pointing at the Provider's own public price page. A Provider that
+runs on this machine declares `pricing: { kind: "local" }`. Hypit never copies or interprets prices;
+`hypit plan --runtime <profile>` prints the Endpoint and price page behind each external request so the
+Agent reads the Provider's page before a paid Build. An undeclared price source is reported as unknown.
+
## 5. Declare a Managed Program when needed
If the Provider depends on a warm external program, export its declaration beside the Endpoint.
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index ad585b34..a073e95e 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -133,6 +133,8 @@ Activation 还可以返回 `diagnose(context)`。它只会在用户显式运行
Runtime 会先解析该 Endpoint 自己声明的凭据槽。它可以对真实服务做一次有界只读请求,例如读取
已认证账户的模型目录;Build 预检不能调用它,它也绝不能提交生成任务。
+收费的 Provider 只声明一件事:价格发布在哪里。在 `defineEndpointPackage` 上写 `pricing: { kind: "page", url }`,指向 Provider 自己的公开价格页;在本机运行的 Provider 声明 `pricing: { kind: "local" }`。Hypit 不复制也不解释价格;`hypit plan --runtime <profile>` 会在每个外部请求旁打印承接它的 Endpoint 和价格页,Agent 在付费 Build 之前去 Provider 自己的页面读价。未声明价格来源的会被报告为未知。
+
## 5. 按需声明 Managed Program
如果 Provider 依赖需要保持温热的外部程序,就在 Endpoint 旁边导出它的声明。这里没有第二个
diff --git a/packages/cli/src/build-planning.ts b/packages/cli/src/build-planning.ts
index 1fffbe53..d7362261 100644
--- a/packages/cli/src/build-planning.ts
+++ b/packages/cli/src/build-planning.ts
@@ -43,6 +43,28 @@ function demandedCapabilities(state: BuildState): readonly CapabilityRef[] {
return [...found.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, value]) => value);
}
+export type PlanProviderView = {
+ readonly capability: string;
+ readonly status: "resolved" | "unresolved" | "ambiguous";
+ readonly endpoint?: string;
+ readonly use?: string;
+ readonly pricing?: { readonly kind: "page"; readonly url: string } | { readonly kind: "local" };
+ readonly endpoints?: readonly string[];
+};
+
+/** Which Endpoint and price page stand behind each demanded capability; reads the Profile only. */
+export async function describePlanProviders(host: NodeRuntimeHost, state: BuildState): Promise<readonly PlanProviderView[]> {
+ const providers = await host.providers(demandedCapabilities(state));
+ return providers.map((item) => ({
+ capability: capabilityName(item.capability),
+ status: item.status,
+ ...(item.endpoint === undefined ? {} : { endpoint: item.endpoint }),
+ ...(item.use === undefined ? {} : { use: item.use }),
+ ...(item.pricing === undefined ? {} : { pricing: item.pricing }),
+ ...(item.endpoints === undefined ? {} : { endpoints: item.endpoints }),
+ }));
+}
+
export async function preflightPlan(host: NodeRuntimeHost, state: BuildState) {
const capabilities = demandedCapabilities(state);
const result = await host.preflight({ capabilities });
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index bc6d3a14..09d71950 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -18,7 +18,7 @@ import { writeCliHelp, writeCliOutput } from "./output.js";
import type { CliIo, CliMachineView } from "./output.js";
import { parseCommand } from "./arguments.js";
import type { CliCommand, RuntimeOption } from "./command.js";
-import { assertPreflight, createCatalogDescriptor, preflightPlan } from "./build-planning.js";
+import { assertPreflight, createCatalogDescriptor, describePlanProviders, preflightPlan } from "./build-planning.js";
import { buildProgressLines, observeBuild } from "./observation.js";
import { isProjectResultCommand, runProjectResultCommand } from "./commands/results.js";
import { isEnvironmentCommand, runEnvironmentCommand } from "./commands/environment.js";
@@ -568,9 +568,9 @@ export async function runCli(
results: planResults.repository,
});
const result = loaded.compiler.planCompilation(loaded);
- const preflight = runtimeProfile === undefined
- ? undefined
- : await preflightPlan(await runtimeHost(runtimeProfile), result.state);
+ const planHost = runtimeProfile === undefined ? undefined : await runtimeHost(runtimeProfile);
+ const preflight = planHost === undefined ? undefined : await preflightPlan(planHost, result.state);
+ const providers = planHost === undefined ? undefined : await describePlanProviders(planHost, result.state);
const outputNames = Object.fromEntries(result.compilation.author.exports.flatMap((item) =>
item.ref.kind === "logical-output" ? [[item.ref.id, item.name]] : []));
const externalRequests = new Map<string, number>();
@@ -607,6 +607,10 @@ export async function runCli(
...(allChoices.length <= args.limit ? {} : { omittedChoices: allChoices.length - args.limit }),
...(allUnreached.length === 0 ? {} : { unreached: allUnreached.slice(0, args.limit) }),
...(allUnreached.length <= args.limit ? {} : { omittedUnreached: allUnreached.length - args.limit }),
+ ...(providers === undefined ? {} : {
+ providers: providers.slice(0, args.limit),
+ ...(providers.length <= args.limit ? {} : { omittedProviders: providers.length - args.limit }),
+ }),
...(preflight === undefined ? {} : { preflight: {
ok: preflight.ok,
capabilityCount: preflight.capabilities.length,
diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.ts
index d2a4b495..564bdafd 100644
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -95,6 +95,15 @@ export type PlanPreflight = {
readonly omittedDiagnostics?: number;
};
+export type PlanProvider = {
+ readonly capability: string;
+ readonly status: "resolved" | "unresolved" | "ambiguous";
+ readonly endpoint?: string;
+ readonly use?: string;
+ readonly pricing?: { readonly kind: "page"; readonly url: string } | { readonly kind: "local" };
+ readonly endpoints?: readonly string[];
+};
+
export type PlanOutput = {
readonly format: "hypit.cli-plan@2";
readonly ok: boolean;
@@ -110,6 +119,9 @@ export type PlanOutput = {
readonly omittedChoices?: number;
readonly unreached?: readonly { readonly output: string; readonly operation: string }[];
readonly omittedUnreached?: number;
+ /** Present only when a Runtime Profile was selected; the Endpoint and price page behind each capability. */
+ readonly providers?: readonly PlanProvider[];
+ readonly omittedProviders?: number;
readonly preflight?: PlanPreflight;
};
@@ -305,6 +317,11 @@ function operationLabel(operation: string): string {
return name.replace(/^request-/u, "").replaceAll("-", " ");
}
+/** `@hypit/seedance@1#seedance-2-mini` → `@hypit/seedance#seedance-2-mini`; the module version is verbose detail. */
+function capabilityLabel(name: string): string {
+ return name.replace(/@[^@#]+#/u, "#");
+}
+
function renderPlan(
view: Extract<CliPresentation, { kind: "plan" }>,
io: CliIo,
@@ -338,6 +355,28 @@ function renderPlan(
lines.push(` ${colors.dim(`${view.machine.omittedExternalRequests} more Operations · use --limit <count>`)}`);
}
}
+ if (view.machine.providers !== undefined) {
+ if (view.machine.providers.length > 0) lines.push("", colors.strong("Providers and price pages"));
+ for (const item of view.machine.providers) {
+ const where = item.status === "resolved"
+ ? `${item.endpoint ?? ""} ${colors.dim(`(${item.use ?? "?"})`)}`
+ : item.status === "ambiguous"
+ ? colors.warning(`several selected Endpoints: ${(item.endpoints ?? []).join(", ")}`)
+ : colors.error("no selected Endpoint");
+ const price = item.pricing === undefined
+ ? (item.status === "resolved" ? colors.warning("price source unknown") : undefined)
+ : item.pricing.kind === "local"
+ ? colors.dim("local, no Provider charge")
+ : item.pricing.url;
+ lines.push(` ${colors.accent(verbose ? item.capability : capabilityLabel(item.capability))}`);
+ lines.push(` ${where}${price === undefined ? "" : ` · ${price}`}`);
+ }
+ if ((view.machine.omittedProviders ?? 0) > 0) {
+ lines.push(` ${colors.dim(`${view.machine.omittedProviders} more capabilities · use --limit <count>`)}`);
+ }
+ } else if (view.machine.externalRequestCount > 0) {
+ lines.push("", colors.dim("Pass --runtime <profile> to see the Provider and price page behind each external request."));
+ }
const unreached = view.machine.unreached ?? [];
if (verbose && unreached.length > 0) {
lines.push("", colors.strong("Declared but not reached"));
@@ -446,7 +485,8 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
"",
" hypit plan <run-source> [--runtime <profile>] [--workspace <workspace>] [--asset-root <directory>]",
"",
- "With --runtime, plan also preflights only the demanded deployment slice.",
+ "With --runtime, plan also preflights only the demanded deployment slice and names the Provider",
+ "and price page behind each external request.",
"Planning never starts external work.",
],
build: [
diff --git a/packages/cli/test/build-programs.test.ts b/packages/cli/test/build-programs.test.ts
index f373eb38..2ffc55b9 100644
--- a/packages/cli/test/build-programs.test.ts
+++ b/packages/cli/test/build-programs.test.ts
@@ -123,6 +123,7 @@ function distribution(
}),
preflight: async () => ({ dataRoot: "/tmp", diagnostics }),
doctor: async () => ({ dataRoot: "/tmp", diagnostics: [] }),
+ providers: async () => [],
createRuntime: async () => {
if (execution !== undefined) return execution;
throw new Error("createRuntime is unavailable");
diff --git a/packages/cli/test/output.test.ts b/packages/cli/test/output.test.ts
index 8cc715d3..411001d4 100644
--- a/packages/cli/test/output.test.ts
+++ b/packages/cli/test/output.test.ts
@@ -89,6 +89,49 @@ test("plan presents useful choices and readable requests without default graph i
assert.match(verbose, /unused\.image/u);
});
+test("plan names the Provider and price page behind each request, and points at --runtime when it cannot", () => {
+ const base = {
+ format: "hypit.cli-plan@2",
+ ok: true,
+ run: "/project/build.svrun",
+ targetCount: 1,
+ targets: ["take.video"],
+ steps: 3,
+ externalRequestCount: 2,
+ externalRequests: [{ operation: "@hypit/seedance@1/request-seedance-2-mini", count: 2 }],
+ choiceCount: 0,
+ choices: [],
+ } as const;
+ const without = capture(human, { kind: "plan", machine: base });
+ assert.match(without, /Pass --runtime <profile>/u);
+ assert.doesNotMatch(without, /Providers and price pages/u);
+
+ const output = capture(human, { kind: "plan", machine: { ...base, providers: [
+ {
+ capability: "@hypit/seedance@1#seedance-2-mini",
+ status: "resolved",
+ endpoint: "hypihub.default",
+ use: "@hypit/provider-hypihub",
+ pricing: { kind: "page", url: "https://hypit.ai/commercial/pricing/" },
+ },
+ { capability: "@hypit/media@1#inspect", status: "resolved", endpoint: "media.local", use: "@hypit/provider-media-local", pricing: { kind: "local" } },
+ { capability: "@hypit/whisperx@1#whisperx-alignment", status: "resolved", endpoint: "whisperx.remote", use: "@hypit/provider-example" },
+ { capability: "@hypit/gpt-image@1#gpt-image-2", status: "unresolved" },
+ ] } });
+ assert.match(output, /Providers and price pages/u);
+ assert.match(output, /@hypit\/seedance#seedance-2-mini\n\s+hypihub\.default \(@hypit\/provider-hypihub\)\s+·\s+https:\/\/hypit\.ai\/commercial\/pricing\//u);
+ assert.match(output, /media\.local .*·\s+local, no Provider charge/u);
+ assert.match(output, /whisperx\.remote .*·\s+price source unknown/u);
+ assert.match(output, /gpt-image#gpt-image-2\n\s+no selected Endpoint\n/u);
+ assert.doesNotMatch(output, /Pass --runtime/u);
+ assert.doesNotMatch(output, /seedance@1#/u);
+
+ const verbose = capture({ ...human, verbose: true }, { kind: "plan", machine: { ...base, providers: [
+ { capability: "@hypit/seedance@1#seedance-2-mini", status: "ambiguous", endpoints: ["hypihub.default", "kie.default"] },
+ ] } });
+ assert.match(verbose, /@hypit\/seedance@1#seedance-2-mini\n\s+several selected Endpoints: hypihub\.default, kie\.default/u);
+});
+
test("run check treats historical reuse as a normal summary", () => {
const output = capture(human, {
kind: "check-run",
diff --git a/packages/endpoint-kit/src/index.ts b/packages/endpoint-kit/src/index.ts
index 98dd1065..82706c56 100644
--- a/packages/endpoint-kit/src/index.ts
+++ b/packages/endpoint-kit/src/index.ts
@@ -109,6 +109,15 @@ export interface EndpointRegistrar {
): void;
}
+/**
+ * Where the Provider behind an Endpoint publishes its prices. Hypit never copies or interprets the
+ * prices themselves; it only tells the caller where the Provider's own page is, or that the work runs
+ * on this machine without a Provider charge.
+ */
+export type EndpointPricing =
+ | { readonly kind: "page"; readonly url: string }
+ | { readonly kind: "local" };
+
export type EndpointPackage = {
readonly instance: {
readonly id: string;
@@ -117,6 +126,7 @@ export type EndpointPackage = {
readonly offers: readonly EndpointOffer[];
/** Host-facing login material declared by this exact configured Endpoint instance. */
readonly credentials: readonly EndpointCredentialDescription[];
+ readonly pricing?: EndpointPricing;
install(registry: EndpointRegistrar): Awaitable<void>;
};
@@ -172,6 +182,8 @@ export type DefineEndpointPackageOptions = {
}>>;
/** Total capacity shared by every lane under this configured Provider pool. */
readonly defaultConcurrency?: number;
+ /** The Provider's own price page, or `local` for work that runs on this machine without a charge. */
+ readonly pricing?: EndpointPricing;
readonly capabilities: readonly EndpointCapability[];
};
@@ -200,6 +212,11 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
assert(new Set(keys).size === keys.length, "Endpoint package repeats a capability");
const lanes = options.capabilities.map((item) => item.lane ?? item.capability.name);
assert(lanes.every((lane) => lane.trim().length > 0), "Endpoint package lane is empty");
+ if (options.pricing?.kind === "page") {
+ let url: URL | undefined;
+ try { url = new URL(options.pricing.url); } catch { url = undefined; }
+ assert(url?.protocol === "https:", "Endpoint pricing page must be an HTTPS URL");
+ }
const laneConcurrency = new Map<string, number>();
for (const capability of options.capabilities) {
const lane = capability.lane ?? capability.capability.name;
@@ -255,6 +272,7 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
instance,
offers,
credentials: credentialDescriptions,
+ ...(options.pricing === undefined ? {} : { pricing: structuredClone(options.pricing) }),
install(registry) {
for (const capability of options.capabilities) {
const lane = capability.lane ?? capability.capability.name;
diff --git a/packages/provider-hyperframes-aws-lambda/src/provider.ts b/packages/provider-hyperframes-aws-lambda/src/provider.ts
index 7da9fc0d..35709461 100644
--- a/packages/provider-hyperframes-aws-lambda/src/provider.ts
+++ b/packages/provider-hyperframes-aws-lambda/src/provider.ts
@@ -501,6 +501,7 @@ export function createAwsLambdaHyperframesProvider(config: CreateAwsLambdaHyperf
facet: "render",
instance: config.instance ?? "hyperframes.aws-lambda",
pool: config.pool ?? config.instance ?? "hyperframes.aws-lambda",
+ pricing: { kind: "page", url: "https://aws.amazon.com/lambda/pricing/" },
defaultConcurrency: config.defaultConcurrency ?? 2,
capabilities: [{
lifecycle: "asynchronous" as const,
diff --git a/packages/provider-hyperframes-local/src/provider.ts b/packages/provider-hyperframes-local/src/provider.ts
index 15a0994b..9102ffd7 100644
--- a/packages/provider-hyperframes-local/src/provider.ts
+++ b/packages/provider-hyperframes-local/src/provider.ts
@@ -257,6 +257,7 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
facet: "render",
instance: config.instance ?? "hyperframes.local",
pool: config.pool ?? config.instance ?? "hyperframes.local",
+ pricing: { kind: "local" },
defaultConcurrency: config.defaultConcurrency ?? 1,
capabilities: [{
lifecycle: "immediate" as const,
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index cfa7d7f7..2d8491d6 100644
--- a/packages/provider-hypihub/README.md
+++ b/packages/provider-hypihub/README.md
@@ -45,7 +45,10 @@ Runtime operation. Embedded callers may override that transport with `publicAsse
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.
+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;
+`hypit plan --runtime <profile>` prints it beside each request this Endpoint would serve. Per-model
+credit costs are never copied into Hypit.
HypiHub exposes MiMo VoiceDesign by default. Set `audio: false` only when the user explicitly selects
another VoiceDesign Provider. Hypit does not expose MiMo preset-voice or voice-cloning models.
diff --git a/packages/provider-hypihub/src/provider.ts b/packages/provider-hypihub/src/provider.ts
index 655a042d..6ceee90c 100644
--- a/packages/provider-hypihub/src/provider.ts
+++ b/packages/provider-hypihub/src/provider.ts
@@ -356,6 +356,7 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
};
return defineEndpointPackage({
module: hypiHubProviderModuleRef, facet: "gateway", instance: options.instance ?? "hypihub.default", pool: options.pool ?? options.instance ?? "hypihub.default",
+ pricing: { kind: "page", url: "https://hypit.ai/commercial/pricing/" },
credentials: { apiKey: options.apiKey ?? credentialRef("os", "hypihub.oauth") },
credentialInputs: { apiKey: {
label: "HypiHub login",
diff --git a/packages/provider-image-opencv-local/src/provider.ts b/packages/provider-image-opencv-local/src/provider.ts
index a59c573a..6e2344dc 100644
--- a/packages/provider-image-opencv-local/src/provider.ts
+++ b/packages/provider-image-opencv-local/src/provider.ts
@@ -98,6 +98,7 @@ export function createLocalOpenCvImageProvider(config: CreateLocalOpenCvImagePro
facet: "raster",
instance: config.instance ?? "image.opencv.local",
pool: config.pool ?? config.instance ?? "image.opencv.local",
+ pricing: { kind: "local" },
defaultConcurrency: config.defaultConcurrency ?? 1,
capabilities: [{
lifecycle: "immediate" as const,
diff --git a/packages/provider-kie/src/provider.ts b/packages/provider-kie/src/provider.ts
index 91c821b6..6bdb743d 100644
--- a/packages/provider-kie/src/provider.ts
+++ b/packages/provider-kie/src/provider.ts
@@ -567,6 +567,7 @@ export function createKieProvider(config: CreateKieProviderOptions) {
facet: "market",
instance: config.instance ?? "kie.default",
pool: config.pool ?? config.instance ?? "kie.default",
+ pricing: { kind: "page", url: "https://kie.ai/pricing" },
credentials: { apiKey: config.apiKey ?? credentialRef("env", "KIE_API_KEY") },
credentialInputs: { apiKey: { label: "KIE API key" } },
defaultConcurrency: config.defaultConcurrency ?? 10,
diff --git a/packages/provider-media-local/src/provider.ts b/packages/provider-media-local/src/provider.ts
index 029b7db7..2d18de0a 100644
--- a/packages/provider-media-local/src/provider.ts
+++ b/packages/provider-media-local/src/provider.ts
@@ -84,6 +84,7 @@ export function createLocalMediaProvider(config: CreateLocalMediaProviderOptions
facet: "media",
instance: config.instance ?? "media.local",
pool: config.pool ?? config.instance ?? "media.local",
+ pricing: { kind: "local" },
defaultConcurrency: config.defaultConcurrency ?? 1,
capabilities: [
{
diff --git a/packages/provider-vertex/src/provider.ts b/packages/provider-vertex/src/provider.ts
index b094443f..585ed50d 100644
--- a/packages/provider-vertex/src/provider.ts
+++ b/packages/provider-vertex/src/provider.ts
@@ -53,6 +53,7 @@ export function createVertexProvider(options: CreateVertexProviderOptions) {
facet: "gemini",
instance: options.instance ?? "vertex.default",
pool: options.pool ?? options.instance ?? "vertex.default",
+ pricing: { kind: "page", url: "https://cloud.google.com/vertex-ai/generative-ai/pricing" },
credentials: {
project: options.project ?? credentialRef("env", "GOOGLE_CLOUD_PROJECT"),
credentials: options.credentials ?? credentialRef("env", "GOOGLE_APPLICATION_CREDENTIALS_JSON"),
diff --git a/packages/provider-whisperx-local/src/provider.ts b/packages/provider-whisperx-local/src/provider.ts
index 0e160a5f..c5b32f24 100644
--- a/packages/provider-whisperx-local/src/provider.ts
+++ b/packages/provider-whisperx-local/src/provider.ts
@@ -116,6 +116,7 @@ export function createLocalWhisperXProvider(config: CreateLocalWhisperXProviderO
facet: "alignment",
instance: config.instance ?? "whisperx.local",
pool: config.pool ?? config.instance ?? "whisperx.local",
+ pricing: { kind: "local" },
defaultConcurrency: config.defaultConcurrency ?? 1,
capabilities: [{
lifecycle: "immediate" as const,
diff --git a/packages/provider-xiaomi-mimo/src/provider.ts b/packages/provider-xiaomi-mimo/src/provider.ts
index 5e98c1ca..20c18e13 100644
--- a/packages/provider-xiaomi-mimo/src/provider.ts
+++ b/packages/provider-xiaomi-mimo/src/provider.ts
@@ -168,6 +168,7 @@ export function createXiaomiMimoProvider(options: CreateXiaomiMimoProviderOption
facet: "tts",
instance: options.instance ?? "xiaomi-mimo.default",
pool: options.pool ?? options.instance ?? "xiaomi-mimo.default",
+ pricing: { kind: "page", url: "https://mimo.mi.com/docs/en-US/pricing" },
credentials: { apiKey: options.apiKey ?? credentialRef("env", "MIMO_API_KEY") },
credentialInputs: { apiKey: { label: "Xiaomi MiMo API key" } },
defaultConcurrency: options.defaultConcurrency ?? 2,
diff --git a/packages/runtime-host-node/src/index.ts b/packages/runtime-host-node/src/index.ts
index 5ac5e9bd..32c016df 100644
--- a/packages/runtime-host-node/src/index.ts
+++ b/packages/runtime-host-node/src/index.ts
@@ -127,6 +127,20 @@ export type RuntimeHostDoctorResult = {
readonly diagnostics: readonly RuntimeDoctorDiagnostic[];
};
+/** The selected Endpoint behind one demanded capability, read from the Profile alone. */
+export type RuntimeHostCapabilityProvider = {
+ readonly capability: CapabilityRef;
+ readonly status: "resolved" | "unresolved" | "ambiguous";
+ /** Configured Endpoint instance that would serve the capability, when exactly one does. */
+ readonly endpoint?: string;
+ /** Provider package the Runtime Profile selected for that Endpoint. */
+ readonly use?: string;
+ /** Where that Provider publishes its prices, as the Provider package declares it. */
+ readonly pricing?: { readonly kind: "page"; readonly url: string } | { readonly kind: "local" };
+ /** Every matching Endpoint instance when the selection is ambiguous. */
+ readonly endpoints?: readonly string[];
+};
+
export type ManagedProgramProgress = {
readonly id: string;
readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
@@ -209,6 +223,11 @@ export type NodeRuntimeHost = {
doctor(options?: {
readonly capabilities?: readonly CapabilityRef[];
}): Promise<RuntimeHostDoctorResult>;
+ /**
+ * Which selected Endpoint would serve each capability and where its Provider publishes prices.
+ * Reads the Profile and Endpoint declarations only; never resolves a credential or contacts a service.
+ */
+ providers(capabilities: readonly CapabilityRef[]): Promise<readonly RuntimeHostCapabilityProvider[]>;
runWorker(readyFile: string, owner: string): Promise<void>;
};
diff --git a/packages/runtime-local/src/config.ts b/packages/runtime-local/src/config.ts
index a4c3d090..6b0509c2 100644
--- a/packages/runtime-local/src/config.ts
+++ b/packages/runtime-local/src/config.ts
@@ -44,7 +44,7 @@ import {
hypitHostStateRoot,
prepareHostPackages,
} from "@hypit/runtime-host-node";
-import type { HostPackageProgress, HostPackageReport } from "@hypit/runtime-host-node";
+import type { HostPackageProgress, HostPackageReport, RuntimeHostCapabilityProvider } from "@hypit/runtime-host-node";
import { SqliteRuntimeState } from "@hypit/store-sqlite";
import { createLocalRuntime } from "./runtime.js";
@@ -440,6 +440,38 @@ export async function declaredManagedPrograms(
return { dataRoot: root, programs };
}
+/** Static Endpoint selection per capability. Reads the Profile and activations only; never a credential or a service. */
+export async function describeRuntimeConfigProviders(
+ path: string,
+ capabilities: readonly CapabilityRef[],
+ options: LoadRuntimeConfigOptions = {},
+): Promise<readonly RuntimeHostCapabilityProvider[]> {
+ if (capabilities.length === 0) return [];
+ const { document, root, packageRoot } = await openRuntimeConfig(path, options.packageRoot);
+ const hostStateRoot = resolve(options.hostStateRoot ?? hypitHostStateRoot());
+ const registry = options.registry ?? new RuntimeAdapterRegistry();
+ await installRuntimeAdapters(registry, packageRoot, endpointPackageSelection(document), options.distributionPackageRoot);
+ const endpoints = await activatedEndpoints(document, root, hostStateRoot, registry);
+ return capabilities.map((capability): RuntimeHostCapabilityProvider => {
+ const matches = endpoints.filter(({ activation }) =>
+ activation.endpoint.offers.some((offer) => sameRef(offer.capability, capability)));
+ const base = { capability: structuredClone(capability) };
+ if (matches.length === 0) return { ...base, status: "unresolved" };
+ if (matches.length > 1) {
+ return { ...base, status: "ambiguous", endpoints: matches.map((item) => item.entry.instance).sort() };
+ }
+ const match = matches[0]!;
+ const pricing = match.activation.endpoint.pricing;
+ return {
+ ...base,
+ status: "resolved",
+ endpoint: match.entry.instance,
+ use: match.entry.use,
+ ...(pricing === undefined ? {} : { pricing: structuredClone(pricing) }),
+ };
+ });
+}
+
function diagnostic(error: unknown, code: string, subject?: string): RuntimeDoctorDiagnostic {
return {
severity: "error",
diff --git a/packages/runtime-local/src/host.ts b/packages/runtime-local/src/host.ts
index 2b3f62b6..df3e10e9 100644
--- a/packages/runtime-local/src/host.ts
+++ b/packages/runtime-local/src/host.ts
@@ -12,6 +12,7 @@ import {
createRuntimeResultControlFromConfig,
createRuntimeCredentialsFromConfig,
createRuntimeFromConfig,
+ describeRuntimeConfigProviders,
doctorRuntimeConfig,
prepareRuntimeConfigPackages,
preflightRuntimeConfig,
@@ -130,6 +131,10 @@ export async function openLocalRuntimeHost(
...distribution,
...(options?.capabilities === undefined ? {} : { capabilities: options.capabilities }),
}),
+ providers: async (capabilities) => await describeRuntimeConfigProviders(profile, capabilities, {
+ packageRoot: basePackageRoot,
+ ...distribution,
+ }),
runWorker: async (readyFile, owner) => {
const selected = await resolveRuntimeConfigPaths(profile, { packageRoot: basePackageRoot, ...distribution });
const leaseState = new SqliteRuntimeState(join(selected.dataRoot, "runtime.sqlite"));
diff --git a/packages/runtime-local/src/index.ts b/packages/runtime-local/src/index.ts
index b7256ea2..77b50ed5 100644
--- a/packages/runtime-local/src/index.ts
+++ b/packages/runtime-local/src/index.ts
@@ -16,6 +16,7 @@ export {
openProjectBuildResultRepository,
openBuildResultRepositoryLocation,
declaredManagedPrograms,
+ describeRuntimeConfigProviders,
doctorRuntimeConfig,
prepareRuntimeConfigPackages,
preflightRuntimeConfig,
diff --git a/packages/runtime-local/test/config.test.ts b/packages/runtime-local/test/config.test.ts
index 3a68685f..728c2aa3 100644
--- a/packages/runtime-local/test/config.test.ts
+++ b/packages/runtime-local/test/config.test.ts
@@ -21,6 +21,7 @@ import {
createRuntimeControlFromConfig,
createRuntimeFromConfig,
createRuntimeResultControlFromConfig,
+ describeRuntimeConfigProviders,
doctorProjectBuildResultRepository,
doctorRuntimeConfig,
openProjectBuildResultRepository,
@@ -259,3 +260,59 @@ test("preflight never runs an Endpoint's active doctor", async () => {
}
});
+test("Runtime providers name the selected Endpoint and its declared price source without contacting a service", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-runtime-providers-"));
+ const path = join(root, "hypit.runtime.json");
+ await writeFile(path, JSON.stringify(profile({
+ dataRoot: ".",
+ endpoints: { paid: { use: "example.paid" }, local: { use: "example.local" } },
+ })));
+ const generate = { module: { name: "example.model", version: "1" }, name: "generate" } as const;
+ const render = { module: { name: "example.render", version: "1" }, name: "render" } as const;
+ const missing = { module: { name: "example.model", version: "1" }, name: "transcribe" } as const;
+ const returns = { module: { name: "example.value", version: "1" }, name: "Output" } as const;
+ const handler = () => ({ value: { kind: "inline" as const, value: null } });
+ const registry = new RuntimeAdapterRegistry();
+ registry.registerFacet(createRuntimeEndpointAdapterFacet({
+ use: "example.paid",
+ activate: (context) => ({
+ endpoint: defineEndpointPackage({
+ module: { name: "example.provider", version: "1" },
+ facet: "paid",
+ instance: context.instance,
+ pool: context.pool ?? context.instance,
+ pricing: { kind: "page", url: "https://prices.example/models" },
+ capabilities: [{ capability: generate, returns, lifecycle: "immediate", handler }],
+ }),
+ }),
+ }));
+ registry.registerFacet(createRuntimeEndpointAdapterFacet({
+ use: "example.local",
+ activate: (context) => ({
+ endpoint: defineEndpointPackage({
+ module: { name: "example.local-provider", version: "1" },
+ facet: "local",
+ instance: context.instance,
+ pool: context.pool ?? context.instance,
+ pricing: { kind: "local" },
+ capabilities: [{ capability: render, returns, lifecycle: "immediate", handler }],
+ }),
+ }),
+ }));
+ try {
+ assert.deepEqual(await describeRuntimeConfigProviders(path, [generate, render, missing], { registry }), [
+ {
+ capability: generate,
+ status: "resolved",
+ endpoint: "paid",
+ use: "example.paid",
+ pricing: { kind: "page", url: "https://prices.example/models" },
+ },
+ { capability: render, status: "resolved", endpoint: "local", use: "example.local", pricing: { kind: "local" } },
+ { capability: missing, status: "unresolved" },
+ ]);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+