From 007664e25a587c35da0ea104d7fc6a8550389446 Mon Sep 17 00:00:00 2001 From: WaterrrForever Date: Tue, 10 Nov 2026 11:26:45 +0000 Subject: [PATCH] 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. --- packages/cli/src/commands/auth/login.ts | 26 +------ .../cli/src/commands/reverse/start.test.ts | 51 +++++++++++- packages/cli/src/commands/reverse/start.ts | 68 ++++++++++++---- packages/cli/src/utils/attendedTerminal.ts | 24 ++++++ .../cli/src/utils/installerDetection.test.ts | 63 ++++++++++++++- packages/cli/src/utils/installerDetection.ts | 77 ++++++++++++++++++- skills-manifest.json | 2 +- skills/reverse-any-video/references/start.md | 31 +++++--- 8 files changed, 282 insertions(+), 60 deletions(-) diff --git a/packages/cli/src/commands/auth/login.ts b/packages/cli/src/commands/auth/login.ts index 8c8bff365a..36f0edb2aa 100644 --- a/packages/cli/src/commands/auth/login.ts +++ b/packages/cli/src/commands/auth/login.ts @@ -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( diff --git a/packages/cli/src/commands/reverse/start.test.ts b/packages/cli/src/commands/reverse/start.test.ts index 7c65b7611b..d2140a9897 100644 --- a/packages/cli/src/commands/reverse/start.test.ts +++ b/packages/cli/src/commands/reverse/start.test.ts @@ -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[]); vi.mock("../../heygen/plan.js", async (importOriginal) => ({ @@ -29,6 +33,14 @@ vi.mock("../../telemetry/events.js", async (importOriginal) => ({ ...(await importOriginal()), trackSkillCommandRan: (run: Record) => void commandRuns.push(run), })); +vi.mock("../../utils/attendedTerminal.js", async (importOriginal) => ({ + ...(await importOriginal()), + isRemoteOrHeadless: () => terminal.remote, +})); +vi.mock("../../utils/installerDetection.js", async (importOriginal) => ({ + ...(await importOriginal()), + 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); diff --git a/packages/cli/src/commands/reverse/start.ts b/packages/cli/src/commands/reverse/start.ts index 8a277d561d..1305b87e08 100644 --- a/packages/cli/src/commands/reverse/start.ts +++ b/packages/cli/src/commands/reverse/start.ts @@ -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} \`. 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, + 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), }; } diff --git a/packages/cli/src/utils/attendedTerminal.ts b/packages/cli/src/utils/attendedTerminal.ts index 0e532bf22b..beb3d44ee9 100644 --- a/packages/cli/src/utils/attendedTerminal.ts +++ b/packages/cli/src/utils/attendedTerminal.ts @@ -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(); +} diff --git a/packages/cli/src/utils/installerDetection.test.ts b/packages/cli/src/utils/installerDetection.test.ts index 8161f02e64..b857c762bd 100644 --- a/packages/cli/src/utils/installerDetection.test.ts +++ b/packages/cli/src/utils/installerDetection.test.ts @@ -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(); + }); +}); diff --git a/packages/cli/src/utils/installerDetection.ts b/packages/cli/src/utils/installerDetection.ts index eb113b7e7e..b34009feba 100644 --- a/packages/cli/src/utils/installerDetection.ts +++ b/packages/cli/src/utils/installerDetection.ts @@ -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 }; +} diff --git a/skills-manifest.json b/skills-manifest.json index 5d2e6d901b..296da3d862 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -26,7 +26,7 @@ "files": 76 }, "reverse-any-video": { - "hash": "2bc8f915c4cd9fe2", + "hash": "233fe054956345f6", "files": 5 }, "slideshow": { diff --git a/skills/reverse-any-video/references/start.md b/skills/reverse-any-video/references/start.md index 980acebc4c..d5ea957e6e 100644 --- a/skills/reverse-any-video/references/start.md +++ b/skills/reverse-any-video/references/start.md @@ -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