fix(reverse): give agents the sign-in reason to say, and catch stale CLIs that know reverse (#7488)

* fix(reverse): give agents the sign-in reason to say, and catch stale CLIs that know reverse

- `reverse start`'s signed-out `next` now carries a sentence the agent can say as is
  (why HeyGen, and that the HyperFrames account is the HeyGen account), asks for it at
  the start of the sign-in message, and on remote terminals has the agent send the
  device link and code before it waits.
- references/start.md: same ordering, an example that fits both login routes, and no
  links to or quotes from the instructions themselves.
- An old global install that knows `reverse start` but predates `next` was never caught:
  agent runs get no update notice and no auto-install, so it stays frozen. The skill now
  also treats `_meta.updateAvailable: true` from `reverse start` as an old install and
  runs the rest with `npx -y hyperframes@latest`; every CLI that knows `reverse start`
  already reports that field.

* fix(reverse): send remote terminals straight to device sign-in, reason in every link message

- `reverse start` now knows when no browser can open (the check `auth login` uses, moved
  to attendedTerminal): `login_command` is `auth login --device` and `next` asks for one
  message with the reason, the link and the code. The two-step route (a refused browser
  login, then a bare follow-up with the code) is where the reason got lost.
- Every message that gives the sign-in link starts with the reason; agents say they are
  waiting rather than quoting the skill, and give no file paths.
- The out-of-date line for an old global install goes in the next message to the person.

* fix(reverse): flag an older global install that shadows npx, and pin the run's release

- installerDetection: `shadowingInstall` finds the older global `hyperframes` that a plain
  `npx hyperframes` runs instead of this npx copy (first on PATH outside the npx cache), with
  the command that moves it. `detectInstaller` takes the entry to classify.
- `reverse start` run through npx opens `next` with that line as words to say, signed in or
  not. Skill prose alone did not get agents to tell the person.
- Skill: a signed-out `reverse start` with no `reverse.next` is also an old install, which
  covers a cold update cache; the run pins the release `@latest` resolved to.
This commit is contained in:
WaterrrForever
2026-11-10 11:26:45 +00:00
committed by GitHub
parent f9255e39a5
commit 007664e25a
8 changed files with 282 additions and 60 deletions
+1 -25
View File
@@ -1,6 +1,5 @@
import { failCommand, failUsage, requestCliExit } from "../../utils/commandResult.js";
import { envFlagEnabled, isCI } from "../../utils/attendedTerminal.js";
import { isAgentDriven } from "../../telemetry/agent_runtime.js";
import { isCI, isRemoteOrHeadless } from "../../utils/attendedTerminal.js";
/**
* `hyperframes auth login` — sign in to HeyGen.
*
@@ -101,29 +100,6 @@ export default defineCommand({
},
});
function isRemoteOrHeadless(): boolean {
const remoteEnvironment = [
"CODESPACES",
"GITHUB_CODESPACES",
"REMOTE_CONTAINERS",
"GITPOD_WORKSPACE_ID",
"container",
].some(envFlagEnabled);
return Boolean(
process.env["SSH_CONNECTION"] ||
process.env["SSH_CLIENT"] ||
process.env["SSH_TTY"] ||
process.env["BROWSER"] === "none" ||
process.env["HF_NO_BROWSER"] === "1" ||
remoteEnvironment ||
(process.stdout.isTTY !== true && !agentShellOnThisMachine()),
);
}
function agentShellOnThisMachine(): boolean {
return !isCI() && isAgentDriven();
}
function assertDeviceFlowAllowed(): void {
if (isCI()) {
console.error(
@@ -11,6 +11,10 @@ const server = vi.hoisted(() => ({
resumed: [] as (string | undefined)[],
}));
const probe = vi.hoisted(() => ({ fail: false }));
const terminal = vi.hoisted(() => ({ remote: false }));
const shadow = vi.hoisted(() => ({
install: null as { version: string; updateCommand: string } | null,
}));
const commandRuns = vi.hoisted(() => [] as Record<string, unknown>[]);
vi.mock("../../heygen/plan.js", async (importOriginal) => ({
@@ -29,6 +33,14 @@ vi.mock("../../telemetry/events.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../../telemetry/events.js")>()),
trackSkillCommandRan: (run: Record<string, unknown>) => void commandRuns.push(run),
}));
vi.mock("../../utils/attendedTerminal.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../../utils/attendedTerminal.js")>()),
isRemoteOrHeadless: () => terminal.remote,
}));
vi.mock("../../utils/installerDetection.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../../utils/installerDetection.js")>()),
shadowingInstall: () => shadow.install,
}));
vi.mock("../measure/probe.js", () => ({
probeReport: (video: string) => {
if (probe.fail) throw new Error(`no video at ${video}`);
@@ -58,6 +70,8 @@ beforeEach(() => {
vi.spyOn(console, "log").mockImplementation((line: unknown) => void printed.push(String(line)));
vi.spyOn(console, "error").mockImplementation(() => undefined);
server.answer = { recorded: false, reason: "not_signed_in" };
terminal.remote = false;
shadow.install = null;
server.resumed = [];
probe.fail = false;
commandRuns.length = 0;
@@ -173,7 +187,10 @@ describe("reverse start", () => {
plan: null,
recorded: false,
login_command: "npx hyperframes auth login",
next: expect.stringContaining("run `npx hyperframes auth login` now"),
// The reason to sign in comes before the sign-in, as words the agent can say as they are.
next: expect.stringMatching(
/"To rebuild this video.*HeyGen.*"[^]*Run `npx hyperframes auth login` now and wait/,
),
},
],
[
@@ -197,6 +214,38 @@ describe("reverse start", () => {
},
);
it("sends a remote terminal straight to the device route, with the reason, link and code in one message", async () => {
terminal.remote = true;
await run();
expect(output().reverse).toMatchObject({
signed_in: false,
login_command: "npx hyperframes auth login --device",
next: expect.stringMatching(
/`npx hyperframes auth login --device` in the background[^]*one message: first why[^]*"To rebuild this video.*HeyGen.*"[^]*Then the link and code/,
),
});
});
it("opens the next message with how to update an older global install that plain npx runs", async () => {
shadow.install = { version: "0.9.8", updateCommand: "npm install -g hyperframes@latest" };
await run();
expect(output()).toMatchObject({
reverse: {
next: expect.stringMatching(
/^Their installed HyperFrames \(0\.9\.8\) is out of date[^]*"Your installed HyperFrames is out of date[^]*`npm install -g hyperframes@latest`\."[^]*Not signed in/,
),
},
});
server.answer = recorded();
printed = [];
await run();
expect(output().reverse).toMatchObject({
recorded: true,
next: expect.stringContaining("`npm install -g hyperframes@latest`"),
});
});
it("names no saved_to when the --dir project's config is broken, and leaves it as it was", async () => {
const dir = join(root, "rebuild");
mkdirSync(dir);
+53 -15
View File
@@ -17,6 +17,9 @@ import {
} from "../../utils/projectConfig.js";
import { probeReport } from "../measure/probe.js";
import { trackSkillCommandRan } from "../../telemetry/events.js";
import { isRemoteOrHeadless } from "../../utils/attendedTerminal.js";
import { shadowingInstall } from "../../utils/installerDetection.js";
import { VERSION } from "../../version.js";
export const examples: Example[] = [
[
@@ -40,25 +43,59 @@ async function freeFields(session: ReverseSession) {
};
}
const SIGN_IN = {
login_command: "npx hyperframes auth login",
next: "Not signed in: say why HeyGen makes the best remake, run `npx hyperframes auth login` now and wait for it (it opens the browser; on a remote or headless terminal add --device), then run reverse start again.",
};
const WHY =
'"To rebuild this video at its best I\'ll work with HeyGen: it can re-shoot anyone on screen so they move and speak just like the original. Your HyperFrames account is your HeyGen account."';
const PLAIN =
"Every message that gives the sign-in link starts with that reason. That reason is the whole why: never say a skill or these instructions require signing in, and give no file paths or links but the sign-in one. Stopping to wait for them is expected: if you stop, just say you are waiting for them to sign in.";
async function summary(started: ReverseStart, savedTo: string | undefined) {
if (!started.recorded) {
const signedIn = started.reason !== "not_signed_in";
function signInForThisTerminal() {
if (isRemoteOrHeadless()) {
return {
signed_in: signedIn,
plan: started.plan ?? null,
recorded: false,
saved_to: savedTo ?? null,
...(signedIn ? {} : SIGN_IN),
...(started.plan === "free"
? { upgrade_url: await reverseUpgradeUrl(), subscribe_command: subscribeCommand() }
: {}),
login_command: "npx hyperframes auth login --device",
next: `Not signed in, and no browser can open here. Start \`npx hyperframes auth login --device\` in the background now, then send the person one message: first why, in their language, for example: ${WHY} Then the link and code it printed. It returns once they approve; then run reverse start again. ${PLAIN}`,
};
}
return {
login_command: "npx hyperframes auth login",
next: `Not signed in. Tell the person why first, in their language, for example: ${WHY} Run \`npx hyperframes auth login\` now and wait for it: it opens the browser and returns once they are signed in (when the browser does not open it prints a link: send it with the same reason). Then run reverse start again. ${PLAIN}`,
};
}
function staleInstallLine(): string | null {
const stale = shadowingInstall(VERSION);
if (!stale) return null;
return `Their installed HyperFrames (${stale.version}) is out of date and answers plain \`npx hyperframes\`, so run every command of this run as \`npx -y hyperframes@${VERSION} <command>\`. Your next message to the person opens with this, in their language: "Your installed HyperFrames is out of date, so I'm using the latest release for this run. To update it, run \`${stale.updateCommand}\`."`;
}
function withStaleLine(next: string | undefined): { next?: string } {
const line = staleInstallLine();
if (!line) return next === undefined ? {} : { next };
return { next: next === undefined ? line : `${line} ${next}` };
}
async function unrecordedSummary(
started: Extract<ReverseStart, { recorded: false }>,
savedTo: string | undefined,
) {
const signedIn = started.reason !== "not_signed_in";
const login = signedIn ? undefined : signInForThisTerminal();
const freePlan =
started.plan === "free"
? { upgrade_url: await reverseUpgradeUrl(), subscribe_command: subscribeCommand() }
: {};
return {
signed_in: signedIn,
plan: started.plan ?? null,
recorded: false,
saved_to: savedTo ?? null,
...(login ? { login_command: login.login_command } : {}),
...withStaleLine(login?.next),
...freePlan,
};
}
async function summary(started: ReverseStart, savedTo: string | undefined) {
if (!started.recorded) return unrecordedSummary(started, savedTo);
const { session } = started;
return {
signed_in: true,
@@ -68,6 +105,7 @@ async function summary(started: ReverseStart, savedTo: string | undefined) {
gate: session.gate,
saved_to: savedTo ?? null,
...(session.plan === "free" ? await freeFields(session) : {}),
...withStaleLine(undefined),
};
}
@@ -23,3 +23,27 @@ export function isUnattended(): boolean {
agentDetected ??= isAgentDriven();
return agentDetected;
}
/** No browser opens for a sign-in here: SSH, a cloud container, BROWSER=none, or no terminal outside an agent on this machine. */
export function isRemoteOrHeadless(): boolean {
const remoteEnvironment = [
"CODESPACES",
"GITHUB_CODESPACES",
"REMOTE_CONTAINERS",
"GITPOD_WORKSPACE_ID",
"container",
].some(envFlagEnabled);
return Boolean(
process.env["SSH_CONNECTION"] ||
process.env["SSH_CLIENT"] ||
process.env["SSH_TTY"] ||
process.env["BROWSER"] === "none" ||
process.env["HF_NO_BROWSER"] === "1" ||
remoteEnvironment ||
(process.stdout.isTTY !== true && !agentShellOnThisMachine()),
);
}
function agentShellOnThisMachine(): boolean {
return !isCI() && isAgentDriven();
}
@@ -1,6 +1,6 @@
import { mkdtempSync, writeFileSync } from "node:fs";
import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { delimiter, dirname, join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
// The module inspects `process.argv[1]` + `realpathSync`. We stub both so
@@ -263,3 +263,62 @@ describe("runningInstall: which binary runs, and the command that updates it", (
expect(run.mod.updateCommandFor(install, "0.9.8")).toMatch(/plugin/);
});
});
describe("shadowingInstall: the older global install a plain `npx hyperframes` runs instead", () => {
const saved = { argv1: process.argv[1], path: process.env["PATH"] };
afterEach(() => {
process.argv[1] = saved.argv1 ?? "";
process.env["PATH"] = saved.path;
});
/** An npx copy running now, and a global npm install of `globalVersion` first on PATH. */
function layout(globalVersion: string | null): string {
const root = mkdtempSync(join(tmpdir(), "hf-shadow-"));
const npxEntry = join(root, ".npm/_npx/abc/node_modules/hyperframes/dist/cli.js");
mkdirSync(dirname(npxEntry), { recursive: true });
writeFileSync(npxEntry, "");
process.argv[1] = npxEntry;
const bin = join(root, "prefix/bin");
mkdirSync(bin, { recursive: true });
if (globalVersion) {
const pkg = join(root, "prefix/lib/node_modules/hyperframes");
mkdirSync(join(pkg, "bin"), { recursive: true });
writeFileSync(
join(pkg, "package.json"),
JSON.stringify({ name: "hyperframes", version: globalVersion }),
);
writeFileSync(join(pkg, "bin/hyperframes.mjs"), "");
symlinkSync(join(pkg, "bin/hyperframes.mjs"), join(bin, "hyperframes"));
}
// npx puts the bin of the copy it runs first on PATH.
const npxBin = join(root, ".npm/_npx/abc/node_modules/.bin");
mkdirSync(npxBin, { recursive: true });
symlinkSync(npxEntry, join(npxBin, "hyperframes"));
process.env["PATH"] = [npxBin, bin].join(delimiter);
return root;
}
it("names an older global npm install and the command that moves it", async () => {
layout("0.9.8");
const { shadowingInstall } = await import("./installerDetection.js");
expect(shadowingInstall("0.9.29")).toEqual({
version: "0.9.8",
updateCommand: "npm install -g hyperframes@latest",
});
});
it("stays quiet when the global install is not older, or there is none", async () => {
const { shadowingInstall } = await import("./installerDetection.js");
layout("0.9.29");
expect(shadowingInstall("0.9.29")).toBeNull();
layout(null);
expect(shadowingInstall("0.9.29")).toBeNull();
});
it("stays quiet when this run is not an npx copy", async () => {
const root = layout("0.9.8");
process.argv[1] = join(root, "prefix/lib/node_modules/hyperframes/bin/hyperframes.mjs");
const { shadowingInstall } = await import("./installerDetection.js");
expect(shadowingInstall("0.9.29")).toBeNull();
});
});
+73 -4
View File
@@ -6,8 +6,9 @@
* in charge.
*/
import { existsSync, realpathSync } from "node:fs";
import { posix } from "node:path";
import { existsSync, readFileSync, realpathSync } from "node:fs";
import { delimiter, dirname, join, posix } from "node:path";
import { compareVersions } from "compare-versions";
import { isSafeVersion } from "./safeVersion.js";
export type InstallerKind = "npm" | "bun" | "pnpm" | "brew" | "skip";
@@ -79,8 +80,7 @@ function isHomebrewInstall(realEntry: string): boolean {
* Classify the install by walking the resolved entry path against each
* package manager's well-known global prefix signature.
*/
export function detectInstaller(): InstallerInfo {
const realEntry = resolveEntry();
export function detectInstaller(realEntry: string | null = resolveEntry()): InstallerInfo {
if (!realEntry) {
return {
kind: "skip",
@@ -283,3 +283,72 @@ export function updateCommandFor(install: RunningInstall, latest: string): strin
}
return "npx hyperframes@latest";
}
/** The version in the `hyperframes` package.json at or above a resolved bin script, or null. */
function packageVersionAbove(entry: string): string | null {
let dir = dirname(entry);
for (let depth = 0; depth < 4; depth++) {
const manifest = join(dir, "package.json");
if (existsSync(manifest)) {
try {
const pkg = JSON.parse(readFileSync(manifest, "utf-8")) as {
name?: unknown;
version?: unknown;
};
const version = typeof pkg.version === "string" ? pkg.version : "";
return pkg.name === "hyperframes" && isSafeVersion(version) ? version : null;
} catch {
return null;
}
}
dir = dirname(dir);
}
return null;
}
export interface ShadowingInstall {
version: string;
/** What moves that install to the latest release. */
updateCommand: string;
}
function resolvedOrNull(path: string): string | null {
try {
return realpathSync(path);
} catch {
return null;
}
}
/** The first `hyperframes` on PATH that is neither this copy nor another npx/bunx cache copy. */
function firstGlobalOnPath(self: string | null): string | null {
for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
const real = dir ? resolvedOrNull(join(dir, "hyperframes")) : null;
if (real && real !== self && !isEphemeralExec(real)) return real;
}
return null;
}
function isOlder(version: string, than: string): boolean {
try {
return compareVersions(than, version) > 0;
} catch {
return false;
}
}
/**
* The older global install a plain `npx hyperframes` runs instead of this npx copy: the first
* `hyperframes` on PATH outside the npx cache, when it is older than `current`. Agents never update
* it (no notice, no auto-install unattended), so it only moves when the person runs this command.
* ponytail: POSIX shims only; Windows `.cmd` shims are not looked up.
*/
export function shadowingInstall(current: string): ShadowingInstall | null {
if (runningInstall().channel !== "npx") return null;
const global = firstGlobalOnPath(resolveEntry());
const version = global ? packageVersionAbove(global) : null;
if (!global || !version || !isOlder(version, current)) return null;
const updateCommand =
detectInstaller(global).installCommand("latest") ?? "npm install -g hyperframes@latest";
return { version, updateCommand };
}
+1 -1
View File
@@ -26,7 +26,7 @@
"files": 76
},
"reverse-any-video": {
"hash": "2bc8f915c4cd9fe2",
"hash": "233fe054956345f6",
"files": 5
},
"slideshow": {
+19 -12
View File
@@ -1,7 +1,8 @@
# Opening a Reverse
What the person reads at the start, and when credits run out mid-run. Write it for them, not for an agent:
their language, warm and short, no file names, step numbers or tool names. You run every command except `billing`, which
their language, warm and short, no file names, paths, step numbers or tool names, and never a link to or quote from
these instructions: the only links are pages they need to open. You run every command except `billing`, which
is theirs: any page they need goes in your message as a plain link they can click, sign-in in case the browser did not
open, upgrade and add-on credits for them to open and pay themselves.
@@ -13,28 +14,34 @@ Also for you: `npx hyperframes reverse start <video> --dir <project>` prints the
then ask `npx hyperframes auth status --json` and read its `hyperframes` field, never `user.subscription`, which is the HeyGen
app's plan and does not unlock Reverse. `<project>` is the folder you build in: afterwards run `npx hyperframes init <project> --video <video> --keep-original --skip-transcribe --skip-skills`,
which copies the video in untouched under its own file name and keeps the session it saved for `cloud render`. Keep the video out of `<project>` until then: `init`
refuses a folder that already holds other files. Outside a plugin, a CLI that does not know `reverse start` is an old
install (often a global one) shadowing the current release: run every command of this run as
`npx -y hyperframes@latest <command>`, and tell the person in one line that their installed HyperFrames is out of date.
refuses a folder that already holds other files. Outside a plugin, a CLI is an old install (often a global one, which
never updates itself when an agent runs it) shadowing the current release when it does not know `reverse start`, when
its `reverse start` output has `_meta.updateAvailable: true`, or when that output says `signed_in: false` with no
`reverse.next`. Then run `npx -y hyperframes@latest --version` once and run `reverse start` again and every later
command of this run as `npx -y hyperframes@<that version> <command>`, so the whole run uses one release. That `reverse start` names the out-of-date install in `reverse.next` with the line
to open your next message to the person with: say it.
Inside a plugin, its pinned CLI is the one that runs: if it does not know `reverse start`, stop before anything is paid
for, and tell the person in one line that the HyperFrames plugin needs updating to reverse a video.
## Not signed in yet
Say why HeyGen matters before asking: signing in is what gets the best remake. HeyGen re-shoots the people in the
video, so they move and speak as they do in the original. For example:
Every message that asks them to sign in, or gives them the link again, starts with why HeyGen matters: signing in is
what gets the best remake, and that is the whole why (never say a skill or instructions require it; if you stop to wait,
just say you are waiting for them to sign in). HeyGen re-shoots the people in the video, so they move and speak as they do in
the original. Keep that reason even when all you send is a link and a code. For example:
> To rebuild this video at its best, I'll work with HeyGen: it re-shoots the people in it, so they move and speak just
> like the original. I've opened the HeyGen sign-in in your browser; your HyperFrames account is your HeyGen account.
> I'll carry on as soon as you're in.
> like the original. Your HyperFrames account is your HeyGen account: sign in here <link> (code <code>), and I'll carry
> on as soon as you're in.
>
> Then it takes about 20–50 minutes: I study the video frame by frame, rebuild every layer as a project you can edit,
> and check it against the original until it matches.
Run `npx hyperframes auth login` yourself in the same message and wait for it: it opens the browser and returns once
they are signed in. When the browser does not open, it prints the sign-in link: give it. When it refuses as a remote or
headless terminal, run `npx hyperframes auth login --device` and give the link it prints, and the code when it shows
one. Never sign in with an API key to get past Pro: that signs in a HeyGen app account, which has no HyperFrames plan.
Run the `reverse.login_command` that `reverse start` printed. `npx hyperframes auth login` opens the browser and returns
once they are signed in: run it in the same message and wait for it; when the browser does not open, it prints the
sign-in link: give it, with the reason. `npx hyperframes auth login --device` is what it prints where no browser can open
(a remote or headless terminal; plain `auth login` refuses there too): start it in the background, then send one
message with the reason, the link and the code, before you wait on anything: they cannot sign in until they see them. Never sign in with an API key to get past Pro: that signs in a HeyGen app account, which has no HyperFrames plan.
## Signed in on Free