Skip to content

Write HTML. Render video. Built for agents.

fix(cli): catalog search never waits on installing the on-device runtime (#5731)

Miguel Ángel7e3908f21b66
diff --git a/packages/cli/src/commands/catalog.test.ts b/packages/cli/src/commands/catalog.test.ts
index 2b4d1708ca..aefa921289 100644
--- a/packages/cli/src/commands/catalog.test.ts
+++ b/packages/cli/src/commands/catalog.test.ts
@@ -1,5 +1,6 @@
// fallow-ignore-file code-duplication
import { beforeEach, describe, expect, it, vi } from "vitest";
+import { runCommand, type CommandDef } from "citty";
import type { RegistryItem } from "@hyperframes/core";
import { catalogRow, countUnindexed, pickByName, searchMissCommand } from "./catalog.js";
@@ -171,6 +172,7 @@ vi.mock("../registry/localEmbedder.js", () => ({
vi.mock("../registry/localSemantic.js", () => ({
mediaSemanticRanking: async () => null,
localSemanticRanking: async () => {
+ if (!state.runtimeOnDisk) throw new Error("the on-device runtime is not installed yet");
if (state.rankingError) throw state.rankingError;
return state.ranking;
},
@@ -736,6 +738,37 @@ describe("the on-device download offer", () => {
expect(err).toContain("declined, but could not save the answer in settings");
});
+ // Runs the exact command a guidance line names, so an instruction that cannot set anything up fails here.
+ const runAdvertised = async (text: string) => {
+ const named = /`hyperframes catalog ([^`]*)`/.exec(text);
+ expect(named).not.toBeNull();
+ const command = (await import("./catalog.js")).default as CommandDef;
+ const log = vi.spyOn(console, "log").mockImplementation(() => {});
+ try {
+ await runCommand(command, { rawArgs: [...named![1]!.split(" "), "--json"] });
+ } finally {
+ log.mockRestore();
+ }
+ };
+
+ it("after a first-time yes, names the one command that sets the tier up", async () => {
+ state.modelStatus = "not-asked";
+ state.confirmAnswer = true;
+ state.runtimeOnDisk = false;
+
+ const first = await asATerminal(() => runForExit({ query: "count up" }));
+ expect(first.err).toContain("Run `hyperframes catalog --on-device` once");
+
+ // Consent saved, no model, no runtime: what the plain re-run actually meets.
+ state.consentRecorded = [];
+ state.modelStatus = "unavailable";
+ const rerun = await runEnvelope({ query: "count up" });
+ expect([state.runtimeInstalls, state.downloads, rerun.tier]).toEqual([0, 0, "words"]);
+
+ await runAdvertised(first.err);
+ expect([state.runtimeInstalls, state.downloads]).toEqual([1, 1]);
+ });
+
it("says so when a no given to the thin-results offer could not be saved", async () => {
state.modelStatus = "not-asked";
state.confirmAnswer = false;
@@ -867,12 +900,28 @@ describe("the on-device download offer", () => {
state.runtimeOnDisk = false;
if (!savedYes) state.consentSavedMeanwhile = false;
- await runEnvelope({ query: "count up" });
+ await runEnvelope({ query: "count up", "on-device": true });
expect(state.runtimeInstalls).toBe(installs);
},
);
+ it("searches without installing a runtime missing beside a ready model", async () => {
+ state.runtimeOnDisk = false;
+
+ const envelope = await runEnvelope({ query: "count up" });
+
+ expect([state.runtimeInstalls, state.downloads, state.vectorFetches]).toEqual([0, 0, 0]);
+ expect(envelope.tier).toBe("words");
+ expect(envelope.shown).toBeGreaterThan(0);
+ expect(envelope.warnings).toEqual([
+ "on-device search is off until its runtime is installed: run `hyperframes catalog --on-device` once.",
+ ]);
+
+ await runAdvertised(envelope.warnings![0]!);
+ expect(state.runtimeInstalls).toBe(1);
+ });
+
it("installs nothing when a person's yes cannot be saved", async () => {
state.consentRecorded = [false];
state.consentWriteFails = true;
diff --git a/packages/cli/src/commands/catalog.ts b/packages/cli/src/commands/catalog.ts
index 7e5ff21652..3b4bf71363 100644
--- a/packages/cli/src/commands/catalog.ts
+++ b/packages/cli/src/commands/catalog.ts
@@ -40,6 +40,8 @@ import {
localVectorNames,
} from "../registry/localSemantic.js";
+const ON_DEVICE_SETUP_COMMAND = "hyperframes catalog --on-device";
+
/**
* Get the offline tier ready, and report every reason it could not be.
*
@@ -55,6 +57,8 @@ async function prepareOnDeviceTier(opts: {
assumedYes: boolean;
artifactRevision?: string;
canPrompt: boolean;
+ /** Only an explicit --on-device installs the runtime; a plain search never waits on it. */
+ installRuntime: boolean;
registry: string;
registryNames: ReadonlySet<string>;
status: LocalModelStatus;
@@ -117,6 +121,12 @@ async function prepareOnDeviceTier(opts: {
return warnings;
}
+ if (!opts.installRuntime && !hasLocalRuntime()) {
+ warn(
+ `on-device search is off until its runtime is installed: run \`${ON_DEVICE_SETUP_COMMAND}\` once.`,
+ );
+ return warnings;
+ }
// Before the model download: fetching 32 MB and then finding the runtime missing wastes it.
const runtime = await ensureLocalRuntime();
if (!runtime.ok) {
@@ -201,7 +211,7 @@ export default defineCommand({
// prompt that fires on a TTY, which leaves every agent and CI run unable
// to opt in at all.
description:
- "Use on-device meaning search; pass --yes to approve a first non-interactive download",
+ "Use on-device meaning search, or set it up when given without a query; pass --yes to approve a first non-interactive download",
},
},
// one flag-parsing entry point feeding three output paths (json, interactive, table); splitting those is its own change
@@ -247,7 +257,8 @@ export default defineCommand({
// Collected rather than only printed, so --json can carry the same reasons
// the terminal shows. A machine that asked for a tier deserves to be told
// it did not run.
- const searchContext = query ? { status: localModelStatus() } : null;
+ const searchContext =
+ query || args["on-device"] === true ? { status: localModelStatus() } : null;
const routineUpdate =
searchContext?.status.status === "unavailable" ||
(searchContext?.status.status === "ready" &&
@@ -261,6 +272,7 @@ export default defineCommand({
assumedYes: args.yes === true,
artifactRevision,
canPrompt: isAttendedTerminal() && !json,
+ installRuntime: args["on-device"] === true,
registry: config.registry,
registryNames,
status: searchContext.status,
@@ -269,9 +281,10 @@ export default defineCommand({
// the state owner again rather than carrying the pre-download snapshot.
effectiveStatus = localModelStatus();
}
- const searched = effectiveStatus
- ? await applySearch(tagged, query, registryNames, effectiveStatus)
- : null;
+ const searched =
+ query && effectiveStatus
+ ? await applySearch(tagged, query, registryNames, effectiveStatus)
+ : null;
if (searched) warnings.push(...searched.warnings);
const matching = searched ? searched.items : tagged;
@@ -613,7 +626,7 @@ async function applySearch<
const warnings: string[] = [];
// On-device meaning search, when the user opted into the model. Free and
// offline, and it answers phrasings word matching cannot reach.
- if (status.status === "ready") {
+ if (status.status === "ready" && hasLocalRuntime()) {
try {
const ranking = await localSemanticRanking(query);
if (ranking) {
@@ -757,7 +770,7 @@ async function offerLocalModel(
console.log(
c.dim(
vectors
- ? " Run the search again to download the model and rank by meaning."
+ ? ` Run \`${ON_DEVICE_SETUP_COMMAND}\` once to download the model and rank by meaning.`
: " Could not fetch the catalog vectors; offline ranking stays off until they are available.",
),
);