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.

fix(environment): expose preparation evidence and guide practical service choices

kashorin2924ace5a7bc
diff --git a/packages/cli/src/commands/environment.ts b/packages/cli/src/commands/environment.ts
index df30adcb..b40c58d7 100644
--- a/packages/cli/src/commands/environment.ts
+++ b/packages/cli/src/commands/environment.ts
@@ -10,9 +10,27 @@ import { acquireOAuthCredential } from "../oauth.js";
import { writeCliOutput } from "../output.js";
import type { CliIo } from "../output.js";
import { hypitHostStateRoot, hypitProjectStateRoot } from "../paths.js";
-import type { CliRuntimeController } from "../runtime-port.js";
+import type { CliManagedProgramReport, CliRuntimeController } from "../runtime-port.js";
import type { OperationalWriter } from "./types.js";
+function programRecord(item: CliManagedProgramReport) {
+ return {
+ ...item,
+ state: item.state.state,
+ ...(item.state.state === "ready" ? {} : { stateDetail: item.state.detail }),
+ };
+}
+
+function programDescription(item: CliManagedProgramReport): string {
+ const details = [...new Set([
+ ...(item.state.state === "ready" ? [] : [item.state.detail]),
+ ...(item.detail === undefined ? [] : [item.detail]),
+ ])];
+ return `${item.id}: ${item.state.state}${details.length === 0 ? "" : ` — ${details.join("; ")}`}`
+ + (item.pid === undefined ? "" : ` · PID ${item.pid}`)
+ + (item.logPath === undefined ? "" : ` · log ${item.logPath}`);
+}
+
export function isEnvironmentCommand(args: CliCommand): args is EnvironmentCommand {
return args.command === "paths" || args.command === "packages" || args.command === "doctor"
|| args.command === "programs" || args.command === "auth"
@@ -36,7 +54,7 @@ export async function runEnvironmentCommand(input: {
} = input;
const reportProgramProgress = args.presentation.json
? undefined
- : (event: { readonly id: string; readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready" }): void => {
+ : (event: { readonly id: string; readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready"; readonly logPath?: string }): void => {
if (!args.presentation.verbose && event.phase !== "installing" && event.phase !== "starting") return;
const verb = {
checking: "Checking",
@@ -45,7 +63,7 @@ export async function runEnvironmentCommand(input: {
waiting: "Waiting for",
ready: "Ready",
}[event.phase];
- io.write(` · ${verb} ${event.id}\n`);
+ io.write(` · ${verb} ${event.id}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
};
const reportPackageProgress = args.presentation.json
? undefined
@@ -151,7 +169,7 @@ export async function runEnvironmentCommand(input: {
const ready = result.programs.every((item) => item.state.state === "ready");
const desiredState = args.action === "down" ? !result.programs.some((item) => item.state.state === "ready") : ready;
const lifecycleOk = args.action === "status" || desiredState;
- const shownPrograms = result.programs.filter((item) => item.state.state !== "ready").slice(0, args.limit);
+ const shownPrograms = result.programs.filter((item) => args.presentation.verbose || item.state.state !== "ready").slice(0, args.limit);
const title = args.action === "up"
? desiredState ? "External programs ready" : "External programs need attention"
: args.action === "down"
@@ -161,11 +179,7 @@ export async function runEnvironmentCommand(input: {
format: "hypit.cli-programs@1",
action: args.action,
ready,
- programs: result.programs.slice(0, args.limit).map((item) => ({
- id: item.id,
- state: item.state.state,
- ...(args.presentation.verbose && item.action !== undefined ? { action: item.action } : {}),
- })),
+ programs: result.programs.slice(0, args.limit).map(programRecord),
...(result.programs.length <= args.limit ? {} : { omittedPrograms: result.programs.length - args.limit }),
}, title,
args.action === "status" ? ready ? "success" : "info" : lifecycleOk ? "success" : "warning", [
@@ -173,7 +187,7 @@ export async function runEnvironmentCommand(input: {
["Programs", String(result.programs.length)] as const,
["Ready", String(result.programs.filter((item) => item.state.state === "ready").length)] as const,
]),
- ], shownPrograms.map((item) => `${item.id}: ${item.state.state}`));
+ ], shownPrograms.map(programDescription));
if (!lifecycleOk) io.setExitCode?.(1);
return;
}
@@ -207,6 +221,7 @@ export async function runEnvironmentCommand(input: {
programs: {
total: external.programs.length,
ready: external.programs.filter((item) => item.state.state === "ready").length,
+ items: external.programs.map(programRecord),
},
}, ok ? "Local Runtime ready" : "Local Runtime needs attention", ok ? "success" : "warning", [
...(!args.presentation.verbose && ok ? [] : [
@@ -214,7 +229,8 @@ export async function runEnvironmentCommand(input: {
["Worker", processState.state] as const,
["Managed programs", `${external.programs.filter((item) => item.state.state === "ready").length}/${external.programs.length} ready`] as const,
]),
- ]);
+ ], external.programs.filter((item) => args.presentation.verbose || item.state.state !== "ready")
+ .map(programDescription));
if (!ok) io.setExitCode?.(1);
return;
}
diff --git a/packages/cli/src/machine-view.ts b/packages/cli/src/machine-view.ts
index 35b06d95..81fd3637 100644
--- a/packages/cli/src/machine-view.ts
+++ b/packages/cli/src/machine-view.ts
@@ -1,6 +1,15 @@
import type { CliBuildResultView, CliBuildStatusView, CliOutputView } from "./view.js";
-type ProgramStateView = { readonly id: string; readonly state: string; readonly action?: string };
+type ProgramStateView = {
+ readonly id: string;
+ readonly state: string;
+ readonly action?: string;
+ readonly endpoint?: string;
+ readonly stateDetail?: string;
+ readonly detail?: string;
+ readonly pid?: number;
+ readonly logPath?: string;
+};
type AttentionView = { readonly message: string; readonly action?: string };
export type OperationalMachineView =
@@ -9,7 +18,7 @@ export type OperationalMachineView =
| { readonly format: "hypit.cli-paths@1"; readonly project: string; readonly projectState: 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 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 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 } }
diff --git a/packages/cli/test/programs-command.test.ts b/packages/cli/test/programs-command.test.ts
index 1fd1fcb0..f4a76892 100644
--- a/packages/cli/test/programs-command.test.ts
+++ b/packages/cli/test/programs-command.test.ts
@@ -40,6 +40,7 @@ function distribution(calls: string[], reports: readonly CliManagedProgramReport
openRuntimeHost: async (path: string) => ({
profile: path,
prepare: async () => [],
+ createRuntime: async () => ({ close: async () => {} }),
controller: async () => controller(path, calls, reports),
}),
} as unknown as CliDistribution;
@@ -99,9 +100,9 @@ test("program startup reports actions, not no-op checks", async () => {
controller: async () => ({
worker: {},
programs: {
- async up(options: { readonly onProgress?: (event: { readonly id: string; readonly phase: "checking" | "starting" | "waiting" | "ready" }) => void }) {
+ async up(options: { readonly onProgress?: (event: { readonly id: string; readonly phase: "checking" | "starting" | "waiting" | "ready"; readonly logPath?: string }) => void }) {
options.onProgress?.({ id: "example", phase: "checking" });
- options.onProgress?.({ id: "example", phase: "starting" });
+ options.onProgress?.({ id: "example", phase: "starting", logPath: "/tmp/example/program.log" });
options.onProgress?.({ id: "example", phase: "waiting" });
options.onProgress?.({ id: "example", phase: "ready" });
return { dataRoot: "/tmp", programs: [{ id: "example", endpoint: "example", state: { state: "ready" } }] };
@@ -116,10 +117,49 @@ test("program startup reports actions, not no-op checks", async () => {
}, selected);
assert.match(output, /· Starting example/u);
+ assert.match(output, /log \/tmp\/example\/program\.log/u);
assert.match(output, /External programs ready/u);
assert.doesNotMatch(output, /· (?:Checking|Waiting for|Ready) example/u);
});
+test("programs and runtime startup retain failure evidence in human and JSON output", async () => {
+ const report: CliManagedProgramReport = {
+ id: "local-service",
+ endpoint: "selected.local",
+ action: "unchanged",
+ state: { state: "down", detail: "health endpoint is not answering" },
+ detail: "service is still loading",
+ pid: 321,
+ logPath: "/tmp/local-service/program.log",
+ };
+ for (const command of ["programs", "runtime"]) {
+ for (const json of [false, true]) {
+ let output = "";
+ let exitCode: number | undefined;
+ await runCli([command, "up", "/project/hypit.runtime.json", ...(json ? ["--json"] : [])], {
+ write(text) { output += text; },
+ setExitCode(code) { exitCode = code; },
+ }, distribution([], [report]));
+ assert.equal(exitCode, 1);
+ if (json) {
+ const parsed = JSON.parse(output);
+ const item = command === "programs" ? parsed.programs[0] : parsed.programs.items[0];
+ assert.equal(item.state, "down");
+ assert.equal(item.stateDetail, report.state.state === "ready" ? undefined : report.state.detail);
+ assert.equal(item.endpoint, report.endpoint);
+ assert.equal(item.detail, report.detail);
+ assert.equal(item.logPath, report.logPath);
+ assert.equal(item.pid, report.pid);
+ } else {
+ assert.match(output, /health endpoint is not answering/u);
+ assert.match(output, /service is still loading/u);
+ assert.match(output, /PID 321/u);
+ assert.match(output, /\/tmp\/local-service\/program\.log/u);
+ }
+ }
+ }
+});
+
test("runtime up validates the Runtime before it starts Programs", async () => {
const calls: string[] = [];
const base = distribution(calls);
diff --git a/packages/provider-whisperx-local/README.md b/packages/provider-whisperx-local/README.md
index 6e6fc64e..d003e1ca 100644
--- a/packages/provider-whisperx-local/README.md
+++ b/packages/provider-whisperx-local/README.md
@@ -30,6 +30,41 @@ Provider; it is a different deployment package but must return the same
The configured model, device, compute mode and batch size are checked through `/health` before use.
This prevents a warm process with an incompatible inference configuration from accepting work.
+## Choose model and hardware
+
+The default `small` / `cpu` / `int8` is a modest-machine execution default, not a quality ranking.
+For multilingual transcription with quality as the priority and suitable hardware, consider
+`large-v3`. For example, an NVIDIA CUDA installation with sufficient memory can explicitly select:
+
+```json
+"whisperx.local": {
+ "use": "@hypit/provider-whisperx-local",
+ "config": {
+ "expectedModel": "large-v3",
+ "expectedDevice": "cuda",
+ "expectedCompute": "float16",
+ "expectedBatchSize": 4
+ }
+}
+```
+
+This is an example deployment, not a promise that every GPU has enough memory. Adjust batch size
+and compute mode for the actual device. On CPU, `int8` is the practical starting point; a larger
+model still takes more preparation and inference work. The packaged faster-whisper backend uses
+CTranslate2: Apple Silicon does not imply CUDA or support for a PyTorch `mps` setting here.
+An already ready smaller model can be useful for a short clear reference. Choose the local model
+or hosted service for the actual language, material and time available rather than installing
+successively larger models as a routine sequence.
+
+`expectedModel` selects speech recognition. WhisperX separately loads the language-specific
+alignment model when that language is first requested. A larger ASR model can improve the words
+fed into alignment, but does not select a larger aligner or guarantee better timing by itself.
+The health response identifies the loaded ASR configuration; it does not establish that every
+language's alignment weights are cached. See [WhisperX usage](https://github.com/m-bain/whisperX#usage-)
+and [faster-whisper deployment](https://github.com/SYSTRAN/faster-whisper#usage).
+
+## Preparation and downloads
+
The Runtime installs and starts the packaged service in the machine Program Home when this Endpoint
is selected. The environment is reused across projects and sessions. The current local package and
service are trusted code; this is not a community-plugin sandbox.
@@ -42,3 +77,25 @@ its configuration through `/health`. Inspect an existing Profile's address and e
when locating that service. A custom `serviceCommand` supplies its own installation and start command.
`hypit programs status` checks the Programs selected by the supplied Profile; `programs up` prepares
and starts them. The managed installation does not require a global `whisperx` shell command.
+
+Preparation and service processes inherit the environment of the command starting them. Set
+network and cache variables there before `programs up` or `runtime up`. A service already running
+retains its earlier environment. Inspect its reported log before deciding whether a selected
+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.
+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.
+
+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;
+`HF_ENDPOINT` and `HF_HOME` configure Hugging Face access/cache. Alignment models can also come
+from torchaudio's download hosts. These settings do not redirect NLTK's own downloader.
+
+Managed installation uses `uv sync --frozen` with the distributed lockfile, including its artifact
+URLs. `PIP_INDEX_URL` does not configure uv, and `UV_DEFAULT_INDEX` is an index-resolution setting,
+not a general rewrite of those frozen URLs. Inspect the actual transfer destination. For blocked
+locked downloads, use an appropriate network/proxy route or an already populated compatible cache;
+an operator-managed installation can instead provide `serviceCommand` with the expected service
+identity. Ordinary production keeps the distributed dependency selection intact.
diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.md
index 28708754..e59f0ba0 100644
--- a/packages/runtime-local/README.md
+++ b/packages/runtime-local/README.md
@@ -3,6 +3,16 @@
The default local Runtime for Hypit. It owns the Worker, scheduler and active SQLite execution
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.
+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.
+
A Runtime Profile selects only the environmental parts that genuinely vary:
```json
diff --git a/packages/runtime-local/src/programs.ts b/packages/runtime-local/src/programs.ts
index 49999a34..aa21af93 100644
--- a/packages/runtime-local/src/programs.ts
+++ b/packages/runtime-local/src/programs.ts
@@ -36,6 +36,7 @@ export type ManagedProgramReport = {
export type ManagedProgramProgress = {
readonly id: string;
readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
+ readonly logPath?: string;
};
export type ManagedProgramOptions = LoadRuntimeConfigOptions & {
@@ -97,24 +98,31 @@ async function readPid(root: string, program: ManagedProgram): Promise<number |
}
}
-function run(root: string, command: ManagedProgramCommand): Promise<{ ok: boolean; detail: string }> {
- return new Promise((resolve) => {
- const child = spawn(command.command, [...command.args], {
- cwd: command.cwd ?? root,
- env: { ...process.env, ...command.env },
- shell: false,
- windowsHide: true,
- stdio: ["ignore", "pipe", "pipe"],
+async function run(root: string, command: ManagedProgramCommand, logPath: string): Promise<{ ok: boolean; detail: string }> {
+ const log = await open(logPath, "a+");
+ try {
+ const offset = (await log.stat()).size;
+ const exit = await new Promise<{ code: number | null; error?: string }>((resolve) => {
+ const child = spawn(command.command, [...command.args], {
+ cwd: command.cwd ?? root,
+ env: { ...process.env, ...command.env },
+ shell: false,
+ windowsHide: true,
+ stdio: ["ignore", log.fd, log.fd],
+ });
+ child.on("error", (error) => resolve({ code: null, error: error.message }));
+ child.on("close", (code) => resolve({ code }));
});
- let output = "";
- child.stdout.on("data", (chunk: Buffer) => { output += chunk.toString(); });
- child.stderr.on("data", (chunk: Buffer) => { output += chunk.toString(); });
- child.on("error", (error) => resolve({ ok: false, detail: error.message }));
- child.on("close", (code) => resolve({
- ok: code === 0,
- detail: code === 0 ? "" : (output.trim().split("\n").at(-1) ?? `exited ${code}`),
- }));
- });
+ if (exit.code === 0) return { ok: true, detail: "" };
+ const end = (await log.stat()).size;
+ const start = Math.max(offset, end - 8192);
+ const tail = Buffer.alloc(end - start);
+ const { bytesRead } = await log.read(tail, 0, tail.length, start);
+ const line = tail.subarray(0, bytesRead).toString().trim().split(/\r?\n/u).at(-1);
+ return { ok: false, detail: exit.error ?? (line || `exited ${exit.code}`) };
+ } finally {
+ await log.close();
+ }
}
/**
@@ -254,20 +262,23 @@ async function bringUp(
}
let installed = false;
+ const logPath = join(directory(root, program), "program.log");
+ const installLogPath = join(directory(root, program), "install.log");
if (program.installation !== undefined) {
const installation = await program.installation.probe();
if (installation.state !== "ready") {
- onProgress?.({ id: program.id, phase: "installing" });
await mkdir(directory(root, program), { recursive: true });
+ await rotateLog(installLogPath);
+ onProgress?.({ id: program.id, phase: "installing", logPath: installLogPath });
for (const command of program.installation.commands) {
- const result = await run(root, command);
+ const result = await run(root, command, installLogPath);
if (!result.ok) {
- return { ...base, action: "unchanged", state: initial, detail: `${command.command} failed: ${result.detail}` };
+ return { ...base, action: "unchanged", state: initial, logPath: installLogPath, detail: `${command.command} failed: ${result.detail}` };
}
}
const after = await program.installation.probe();
if (after.state !== "ready") {
- return { ...base, action: "unchanged", state: initial, detail: `installation is ${after.state}: ${after.detail}` };
+ return { ...base, action: "unchanged", state: initial, logPath: installLogPath, detail: `installation is ${after.state}: ${after.detail}` };
}
installed = true;
}
@@ -276,12 +287,16 @@ async function bringUp(
// Nothing to keep running: installation was the whole job.
const state = await program.probe();
if (state.state === "ready") onProgress?.({ id: program.id, phase: "ready" });
- return { ...base, action: state.state === "ready" && installed ? "installed" : "unchanged", state };
+ return {
+ ...base,
+ action: state.state === "ready" && installed ? "installed" : "unchanged",
+ state,
+ ...(installed ? { logPath: installLogPath } : {}),
+ };
}
- onProgress?.({ id: program.id, phase: "starting" });
+ onProgress?.({ id: program.id, phase: "starting", logPath });
await mkdir(directory(root, program), { recursive: true });
- const logPath = join(directory(root, program), "program.log");
await rotateLog(logPath);
const log = await open(logPath, "a");
try {
diff --git a/packages/runtime-local/test/programs.test.ts b/packages/runtime-local/test/programs.test.ts
index fd759a5e..4f490bea 100644
--- a/packages/runtime-local/test/programs.test.ts
+++ b/packages/runtime-local/test/programs.test.ts
@@ -117,9 +117,26 @@ function fileBackedProgram(marker: string): ManagedProgram {
};
}
-test("up starts one Endpoint's program and down stops it", async () => {
+test("up preserves installation logs through service startup and down stops it", async () => {
const marker = join(await mkdtemp(join(tmpdir(), "hypit-marker-")), "ready");
- const { root, path, options } = await project(() => fileBackedProgram(marker));
+ const installed = `${marker}.installed`;
+ const { root, path, options } = await project(() => ({
+ ...fileBackedProgram(marker),
+ installation: {
+ commands: [nodeProgram(`
+ process.stdout.write('prepared dependency\\n');
+ require('node:fs').writeFileSync(process.argv[1], 'ready');
+ `, installed)],
+ async probe() {
+ try {
+ await readFile(installed, "utf8");
+ return { state: "ready" as const };
+ } catch {
+ return { state: "down" as const, detail: "not prepared" };
+ }
+ },
+ },
+ }));
const progress: string[] = [];
const started = await bringManagedProgramsUp(path, {
@@ -131,7 +148,8 @@ test("up starts one Endpoint's program and down stops it", async () => {
assert.equal(started.programs[0]!.endpoint, "one");
assert.equal(started.programs[0]!.action, "started");
assert.deepEqual(started.programs[0]!.state, { state: "ready" });
- assert.deepEqual(progress, ["example:checking", "example:starting", "example:waiting", "example:ready"]);
+ assert.deepEqual(progress, ["example:checking", "example:installing", "example:starting", "example:waiting", "example:ready"]);
+ assert.match(await readFile(join(root, "programs", "example", "install.log"), "utf8"), /prepared dependency/u);
const pid = started.programs[0]!.pid!;
assert.equal(await readFile(join(root, "programs", "example", "process.pid"), "utf8"), `${pid}\n`);
@@ -152,6 +170,7 @@ test("up starts one Endpoint's program and down stops it", async () => {
await sleep(100);
assert.throws(() => process.kill(pid, 0), "the detached program is gone");
await assert.rejects(async () => await readFile(join(root, "programs", "example", "process.pid"), "utf8"));
+ await rm(installed, { force: true });
await rm(root, { recursive: true, force: true });
});
@@ -274,7 +293,44 @@ test("a failing install stops before starting anything, and says which command f
const detail = result.programs[0]!.detail ?? "";
assert.ok(detail.startsWith(`${process.execPath} failed:`), detail);
assert.match(detail, /failed: no such project/u);
- assert.equal(result.programs[0]!.logPath, undefined, "nothing was started, so nothing logged");
+ assert.match(await readFile(result.programs[0]!.logPath!, "utf8"), /no such project/u);
+});
+
+test("installation output is readable while preparation is still running", async () => {
+ const { root, path, options } = await project((root) => ({
+ id: "downloader",
+ installation: {
+ commands: [nodeProgram(`
+ const fs = require('node:fs');
+ process.stdout.write('fetching dependency\\n');
+ const timer = setInterval(() => {
+ if (fs.existsSync(process.argv[1])) { clearInterval(timer); process.stderr.write('download complete\\n'); }
+ }, 10);
+ `, join(root, "release"))],
+ probe: async () => ({ state: "down", detail: "not installed" }),
+ },
+ probe: async () => ({ state: "down", detail: "not running" }),
+ }));
+ let logPath: string | undefined;
+ let done = false;
+ const pending = bringManagedProgramsUp(path, { ...options,
+ onProgress: (event) => { if (event.phase === "installing") logPath = event.logPath; },
+ }).finally(() => { done = true; });
+ try {
+ let output = "";
+ for (let attempt = 0; attempt < 100; attempt++) {
+ if (logPath) output = await readFile(logPath, "utf8").catch(() => "");
+ if (output.includes("fetching dependency")) break;
+ await sleep(20);
+ }
+ assert.match(output, /fetching dependency/u);
+ assert.equal(done, false);
+ } finally {
+ await writeFile(join(root, "release"), "continue");
+ await pending;
+ }
+ assert.match(await readFile(logPath!, "utf8"), /download complete/u);
+ await rm(root, { recursive: true, force: true });
});
test("up stops waiting when a started program exits", async () => {
diff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.md
index 5bb95fb3..17b6818f 100644
--- a/skills/hypit/SKILL.md
+++ b/skills/hypit/SKILL.md
@@ -77,11 +77,13 @@ crafts explain resolution and duration choices.
## Prepare for the work at hand
For a spoken reference, use WhisperX's transcript and word times to connect speech with picture
-changes. It can run through a local or hosted Endpoint. Check the relevant existing setup and local
-preparation. Use
+changes. Choose a practical local, hosted or mixed setup for the work, considering readiness,
+preparation time, hardware, network and account preferences. Use
[environment selection](references/environment/profile.md#choose-the-practical-capability-path-with-the-user)
-to explain the practical options, including HypiHub, and the effort, accounts and costs involved.
-Prepare the path the user chooses. Reference interpretation and component work can progress alongside
+to explain the options, including HypiHub's combined hosted transcription and generation, and the
+effort, accounts and costs involved. Carry working, chosen services forward; prepare the selected
+path and reconsider it when actual progress changes its usefulness. Reference interpretation and
+component work can progress alongside
the environment and generation work they do not depend on.
## Understand and direct
diff --git a/skills/hypit/references/environment/distribution.md b/skills/hypit/references/environment/distribution.md
index 2b0e818e..5164581d 100644
--- a/skills/hypit/references/environment/distribution.md
+++ b/skills/hypit/references/environment/distribution.md
@@ -58,6 +58,10 @@ supplied as a tarball can be installed directly, for example
`npm install --global /path/to/hypit-release.tgz`. Report the actual installation error when the
release cannot be obtained.
+If installation is slow or a registry mirror lacks the selected release, use
+[network preparation](local-tools.md#make-network-preparation-practical) to inspect the actual download
+source and choose a reachable route. Keep the requested version when changing registries.
+
## Let the installation channel own updates
Install, update, and remove the Distribution through the same package or release channel. Updating
@@ -67,8 +71,8 @@ executable Distribution. After installation or an update, use the selected launc
`profile.md` for the current project's capabilities and Runtime choices.
The installed Distribution is the authority for exact Surface syntax. If a package or Surface named
-by the Skill is absent from `hypit vocabulary`, report the version mismatch and update the selected
-installation instead of inventing a translation.
+by the Skill is absent from `hypit vocabulary`, check package selection and the installed release.
+Explain whether the work needs an available package, a supported alternative or a Distribution update.
A contributor checkout can execute its own Distribution after its documented workspace setup, but it
is a development arrangement, not an assumed location for ordinary production. Use one only when the
diff --git a/skills/hypit/references/environment/local-tools.md b/skills/hypit/references/environment/local-tools.md
index 52448068..364ca66e 100644
--- a/skills/hypit/references/environment/local-tools.md
+++ b/skills/hypit/references/environment/local-tools.md
@@ -14,18 +14,20 @@ README owns its preparation and service locations.
Establish what already works, what needs starting or repair, and what needs downloads. Use those
findings in [environment selection](profile.md#choose-the-practical-capability-path-with-the-user),
then prepare the chosen setup using its Provider instructions and the evidence from its logs.
+Consider hardware and actual network reachability alongside installed files. A cached environment
+can still need speech-model weights or a language's alignment model before its first useful request.
## Diagnose the selected local capability
-Begin with the current project and Profile:
+Choose the observation that answers the current question:
-```bash
-hypit paths
-hypit runtime status
-hypit runtime logs
-hypit programs status
-hypit doctor
-```
+| Question | Tool |
+| --- | --- |
+| Which Profile and machine locations apply? | `hypit paths` |
+| Is the Worker running, and is work active? | `hypit runtime status` |
+| What has the Worker reported? | `hypit runtime logs` |
+| Which selected local helpers answer, and where are their logs? | `hypit programs status --verbose` |
+| Does the selected Profile's broader configuration and service access work? | `hypit doctor` |
Read the failing Endpoint's message and package README before changing the machine. The Profile says
which local implementation was selected; another project's working service is not evidence that this
@@ -37,11 +39,14 @@ The installed Hypit Distribution requires its supported Node.js version. Local m
both `ffmpeg` and `ffprobe` on `PATH`, or explicit compatible paths accepted by its Provider. Local
Python Programs use `uv` to create their locked environments in Hypit's machine Program Home.
-Use the host's ordinary package manager, then verify the executables in a new shell:
+Prepare the missing executables needed by the chosen work using the host's ordinary package manager.
+For example, these commands install FFmpeg for media work and uv for managed Python tools; select
+the relevant command and verify its executable in the environment that will run Hypit:
```bash
# macOS
-brew install ffmpeg uv
+brew install ffmpeg
+brew install uv
ffmpeg -version
ffprobe -version
uv --version
@@ -72,13 +77,16 @@ hypit programs status
```
`runtime up` prepares selected adapter dependencies, brings declared Programs to their expected local
-state, and starts the Worker. The narrower commands operate only the Programs:
+state, and starts the Worker. It prepares all Endpoints declared in that Profile, including a local
+Endpoint whose capability is currently bound to a hosted one. Keep the active Profile representative
+of the chosen setup; bindings select request execution, not which declared Programs are prepared.
+Program commands leave the Worker lifecycle alone:
-```bash
-hypit programs up
-hypit programs status
-hypit programs down
-```
+| Intention | Command |
+| --- | --- |
+| Prepare and start the selected helpers | `hypit programs up` |
+| Inspect their current state | `hypit programs status` |
+| Stop helpers managed by Hypit | `hypit programs down` |
`runtime down` stops the Worker while leaving separately managed Programs available. This lets a later
Build reuse an already warm local model. Use `programs down` when those helpers themselves should stop.
@@ -89,8 +97,8 @@ packaged service, not for creating a second project-local installation.
## Select local WhisperX explicitly
-Local and hosted WhisperX implement the same alignment capability. Add the local Provider to the
-Profile:
+Local and hosted WhisperX implement the same alignment capability. When local execution is chosen,
+merge this fragment into the Profile, retaining the other services the production uses:
```json
{
@@ -110,13 +118,60 @@ Provider README owns optional model, device, compute, batch-size, timeout, and c
Its loopback service accepts canonical speech evidence and returns measured alignment; it does not
interpret Script, Caption Cues, or Semantic Segments.
-Run `hypit runtime up` after selecting it. The first preparation may install Python and download model
-weights, while later projects reuse the machine Program. Success means the configured service identity
-answers its health probe; `hypit doctor` then checks the selected Endpoint as part of the full Profile.
-
-If local installation is incompatible with the machine, blocked by the network, or making no useful
-progress within the user's available time, report the exact evidence and offer another Provider for
-the same capability. Continue independent reference or production work while that choice is resolved.
+Choose the ASR model deliberately for the language, hardware and work. For quality-oriented
+multilingual work, a multilingual large model is a useful starting preference when hardware and
+preparation are practical. A ready smaller model can serve straightforward reference understanding
+on a modest CPU machine; its availability is more informative than the ability to begin a larger
+download. Weigh accuracy needs against setup and inference time, including the hosted option.
+The Provider README owns exact settings, compute choices and the distinction between transcription
+and language-specific alignment. Configure the chosen model before preparing it.
+
+With the Endpoint and model selected, run `hypit runtime up`. The first preparation may install Python
+and download model weights, while later projects reuse the machine Program. Success means the configured
+service identity answers its health probe; `hypit doctor` then checks the selected Endpoint as part of
+the full Profile.
+
+## Make network preparation practical
+
+Treat preparation as part of delivering the video. Read the current command and its progress:
+which dependency or weight file, which download host, how much data has arrived, and whether the
+process is downloading, unpacking or loading a model. Managed Program preparation reports `install.log`;
+service startup reports `program.log`. On Windows, service stderr is in the adjacent `program.err.log`,
+where Python logging and download errors may appear. Read the relevant recent output while a long
+command runs. Logs expose the subprocess's output; some downloaders suppress progress outside a terminal.
+Use available transfer progress, cache growth and process activity to judge whether waiting remains
+reasonable for this commission; a quiet log alone does not establish a stalled download.
+A longer timeout helps a healthy slow transfer finish; it does not improve an unusable route.
+
+Mainland China and other restricted networks can make particular hosts slow or unreachable. Use the
+user's network context and actual transfer evidence to choose a reachable source, rather than
+inferring connectivity from the language they speak. Preserve useful downloads and caches while
+changing the part that is actually blocked. Explain the changed outlook promptly and recommend
+a practical alternative when local preparation would dominate the production time. HypiHub can
+remove local speech-model preparation and also supply later generation; the account choice remains
+with the user. Continue independent reference and component work meanwhile.
+
+Mirrors address particular download clients and hosts:
+
+| Download | Relevant controls and limits |
+| --- | --- |
+| npm packages | A command's `--registry` or `npm_config_registry`; a registry mirror may lag a newly published version. Check the requested package version. |
+| Python packages | pip uses `--index-url` / `PIP_INDEX_URL`; uv uses `--default-index` / `UV_DEFAULT_INDEX`. They are different clients. Hypit's managed service uses frozen uv dependencies; consult its Provider README before expecting an index change to redirect locked artifact URLs. |
+| Python runtime | uv's `UV_PYTHON_INSTALL_MIRROR` selects a compatible Python-distribution mirror. A PyPI mirror does not supply Python itself. An already compatible installed Python may avoid this download. |
+| Hugging Face weights | `HF_ENDPOINT` selects a compatible Hub endpoint; `HF_HOME` / `HF_HUB_CACHE` select reusable cache locations. A model's redirected weight host and its language-alignment download must also be reachable. |
+| FFmpeg, browser and other binaries | Use the selected package manager's binary-download settings or a compatible official prebuilt installation. An npm/PyPI mirror does not generally redirect these downloads. Homebrew bottles, browser archives and GitHub release assets have their own sources. |
+
+Use a mirror the user or organization trusts, with settings scoped to the preparing command or
+session. Explain persistent machine-wide changes when those are useful. Keep the selected package
+versions and record the effective preparation choices for the next session. Read the actual download
+host afterward to establish that the intended route was used.
+
+Useful source documentation includes [uv settings](https://docs.astral.sh/uv/reference/environment/),
+[TUNA's PyPI mirror](https://mirrors.tuna.tsinghua.edu.cn/help/pypi/),
+[TUNA's Homebrew guidance](https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/),
+[npmmirror](https://npmmirror.com/) and [HF-Mirror](https://hf-mirror.com/).
+These are available choices to assess, not automatic machine defaults. A mirror that returns model
+metadata successfully may still redirect large files to another host; diagnose the transfer itself.
## Repair from the narrowest evidence
diff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.md
index 7da901fc..5cdc5d90 100644
--- a/skills/hypit/references/environment/profile.md
+++ b/skills/hypit/references/environment/profile.md
@@ -25,29 +25,49 @@ production capabilities. Local media inspection prepares reference frames and cl
## Choose the practical capability path with the user
-Read the project's relevant choices and inspect its tools, Profile, credentials and local preparation.
-Keep a working setup the user has chosen. For a spoken reference, transcription may be the immediate
-need while image and video requests are still taking shape. Explain the capabilities the piece will
-need, and make the setup choice concrete through what is available, the preparation effort and cost.
+Help the user reach useful production with a setup that fits their time, machine and account
+preferences. Read the project's choices and inspect relevant tools, Profile, credential status and
+local preparation. Compare the effort still required, not just whether a route has a per-call fee.
+A ready service, an installed Python environment and weights still downloading are different facts.
+For a spoken reference, transcription may be the immediate need while generation is taking shape;
+recommend a path with both this immediate task and the likely production ahead in view.
`programs status` and `doctor` describe the selected Profile. A Profile containing only hosted
alignment leaves local WhisperX readiness unexamined. [Local tools](local-tools.md#assess-local-preparation)
explains where to inspect existing preparation and known service configuration.
-- Recommend local WhisperX when the machine and preparation time make it practical. Its calls have
- no hosted Provider charge; first preparation may install a runtime and download model weights.
+- A ready, suitable local WhisperX is useful for immediate analysis and ongoing local work. Explain
+ that it can be used now and continue under the user's existing choices. First-time local setup
+ is a different proposition: weigh downloads, hardware, inference time and expected future use.
+ Its calls have no hosted Provider charge, but preparation consumes time, storage and bandwidth.
[Local tools](local-tools.md#select-local-whisperx-explicitly) owns setup and repair guidance.
- Use a supported BYOK Provider when the user already has that account and wants to use it.
-- Offer HypiHub when the user prefers one hosted account or wants an alternative to local preparation.
- It hosts WhisperX and supported image, video and audio models, so the same account can serve
- reference understanding and later generation. Check access for the capabilities this work needs.
-
-When the path is undecided, share those findings, recommend a practical choice and ask which setup
-suits the user. Their decision can cover the preparation as a whole. Record it in
+- Introduce HypiHub as the integrated hosted option when explaining a new production's setup,
+ especially when several model services are missing, downloads are costly, or the user wants to
+ start without maintaining local inference. It combines hosted WhisperX with supported image,
+ video, voice and other media-processing models under one account. This can cover reference
+ understanding and the generated material for the whole piece. Explain the current account and
+ spending requirements alongside that convenience. Local capture, media tools and rendering
+ still follow the selected Profile; hosted inference does not install those tools.
+
+A mixed setup is ordinary: local transcription can serve the reference while HypiHub supplies later
+generation. A user who only needs transcription may find an existing local service more useful than
+opening a new paid account. Present HypiHub where its convenience helps the actual work, including
+when later generation needs arise; an already working local service can keep the analysis moving.
+
+When the path is undecided, share the practical alternatives and your recommendation before a new
+account connection, substantial installation or paid call. Ask for the choice that is actually
+unresolved. Once the route is agreed, carry out ordinary setup and work with progress updates.
+Their decision can cover preparation as a whole. Record it in
[Brief](../creation/brief.md#brief-preserves-user-authority); the Profile implements that choice.
[Paid scope](../production/builds.md#work-within-the-agreed-paid-scope) explains how the commission
covers service charges. Prepare further model credentials as the creative plan needs them.
+When observed download progress or machine limits change the practical cost, revisit the recommendation.
+State what is being fetched or run, how it is progressing and what would make the next attempt
+different. [Local tools](local-tools.md#make-network-preparation-practical) covers caches, mirrors and
+network diagnosis. Time already spent installing is not a reason to continue an unsuitable route.
+
Switching from BYOK or local execution to HypiHub changes the selected service and may change the
billing account. That remains a user choice when the earlier route encounters authentication, quota,
rate-limit or service errors. An OAuth page follows the decision to connect the selected account.
diff --git a/skills/hypit/references/production/browser-capture.md b/skills/hypit/references/production/browser-capture.md
index 2c9faa41..73d7d9dd 100644
--- a/skills/hypit/references/production/browser-capture.md
+++ b/skills/hypit/references/production/browser-capture.md
@@ -77,8 +77,11 @@ path and actual dimensions, plus recorded duration and frame rate. Output paths
## Browser and recording choices
-Prepare the package's tested browser once with `hypit capture install-browser`. It uses Puppeteer's
-browser cache and leaves existing browsers in place. `--channel chrome` selects an installed Chrome; `--browser <executable>` selects another explicit compatible path. `--headed` opens a visible
+Use an installed compatible browser or prepare the package's tested browser once with
+`hypit capture install-browser`. Installation uses Puppeteer's browser cache and leaves existing
+browsers in place. [Network preparation](../environment/local-tools.md#make-network-preparation-practical)
+explains diagnosing a slow download. `--channel chrome` selects an installed Chrome;
+`--browser <executable>` selects another explicit compatible path. `--headed` opens a visible
window. The script's `options.launch` accepts ordinary Puppeteer launch options, including a chosen
`userDataDir` when a dedicated persistent browser profile is useful. CLI browser options override
the script's choices. `--timeout-ms` sets page operation and navigation timeouts.