feat(cli): accept host-managed HeyGen access tokens

[miguel-heygen]

What

Accept host-managed OAuth access tokens in the CLI, and report the right account after a browser sign-in while one is set.

Why

An embedding application can own sign-in and token refresh without writing its credentials into the shared CLI store. Previously the CLI ignored that token.

Related work

#5181 already lets media-use send a host-injected HEYGEN_ACCESS_TOKEN and move its requests with HEYGEN_API_BASE, behind its project-.env and destination guards. This PR leaves media-use exactly as main has it; a host that needs a non-production API sets HEYGEN_API_BASE for media-use. The embedding application owns whether to supply the token alongside existing shared credentials.

How

• Resolve HEYGEN_ACCESS_TOKEN after the API-key environment variables and before the shared store. It is never refreshed or persisted, and auth status reports its environment source.
• auth login now identifies the account from the tokens the login just issued, in both the browser and device flows. Before, the browser flow resolved credentials again, so an environment token or API key for account A outranked the new account B login: A's identity was saved next to B's tokens and reported in telemetry. That lookup could no longer come back empty, so its no_credential failure reason is removed.
• publish names a rejected HEYGEN_ACCESS_TOKEN instead of asking for a login it would not use, and auth logout warns that the token still signs commands. One map of environment credential variables in the resolver feeds both.
• The auth help, docs/packages/cli.mdx and the CLI skill's cloud reference list the token in the resolution order. docs/guides/authentication.mdx now shows the media workflows' real order from main, which checks the host token before the API keys, and says that media-use resolve searches through the separate heygen CLI.

Release note: someone who already exports HEYGEN_ACCESS_TOKEN in their shell will now have it used ahead of ~/.heygen/credentials.

Test plan

On Linux, at this head:

• A new login test sets an environment token for account A and completes a browser login as B. It fails without the fix (expected b@example.com, got a@example.com) and passes with it.
• The login test file passed 3 runs in a row (25 tests each), and the auth, auth-command and telemetry tests passed (522).
• A new publish test with a rejected host token fails without the fix and passes with it; the publish file passed 3 runs in a row (53 tests) and the publish command tests pass (20).
• A new logout test fails without the fix and passed 3 runs in a row; the auth and auth-command tests pass (206).
• CLI typecheck, formatting, lint, the comment ratchet, the comment-citation check, the skill lint, the skill mirror check and the skills-manifest freshness check passed.

Earlier on this branch: the resolver and auth-status tests passed three consecutive runs, and deliberate mutations of the resolver order, refresh flag and header check each failed their tests. No real service or published package was exercised.

[github-actions]

Edit accuracy: accurate 2059 (base branch 2059), smooth 1570 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

[somanshreddy]

Review at 1d557064. COMMENT, not an approval. This head can't merge: GitHub reports mergeable: CONFLICTING. Main took #5181 (21d14b25b, "reach HeyGen through a host app's gateway (HEYGEN_API_BASE)") about an hour ago, and it rewrites the same media-use host/credential code. git merge-tree shows conflicts in skills/media-use/audio/scripts/lib/heygen.mjs, heygen.test.mjs and skills-manifest.json. The rebase will produce a new head, and the media-use half needs a real reconciliation rather than a mechanical one.

Correction (after tai's CR 5448413550): I first called the CLI half clean, and I missed one finding. tai's item 1 is real; I confirmed it in the code. After a browser login, runOAuthLogin → reportIdentity() (commands/auth/login.ts:231) re-resolves through tryResolveCredential(). With HEYGEN_ACCESS_TOKEN for account A still in the environment, it identifies A, then persistUserInfo writes A's user block next to the account-B tokens that were just saved, and both the login-completed telemetry event and the user identity it attributes record A. Nothing in auth login checks for an env credential first.

• The same pitfall already existed with HEYGEN_API_KEY, but this PR makes it reachable from inside Desktop, where the agent's environment carries the token.
• Fix: identify the account from the tokens the flow just returned, or refuse or warn in auth login while an env credential is set. Add a dual-account test.

tai's item 2 does not reproduce on Linux. packages/cli/src/audio/scripts is a tracked symlink (mode 120000) to ../../../../skills/media-use/audio/scripts, and a fresh worktree at this head passes heygen.test.mjs 11/11. But it does mean the "both distributed helpers" loop imports the same source file twice, so it doesn't prove a second, distributed copy. A checkout without symlinks (Windows core.symlinks=false) would fail that import.

CLI half (packages/cli): resolver and refresh are correct; see the correction above for login.

• HEYGEN_ACCESS_TOKEN resolves after the two API-key env vars and before the store. It is refreshable: false, so refreshIfNeeded and forceRefreshCredentials both leave it alone: there's no refresh_token, and nothing writes it to the store.
• auth status labels it env (HEYGEN_ACCESS_TOKEN), and isFileSource keeps it out of the file-only rows.
• headerSafeEnv keeps the control-character refusal for all three env vars.
• Tests: vitest resolver.test.ts and status-user.test.ts pass, 22 tests.
• Mutants, all caught (4/4):
  • refreshable: true;
  • the token moved ahead of the API keys;
  • the token ignored;
  • the header-safety check dropped.

Media-use half: must be redone on top of #5181.

• On main, heygenBase() is evaluated per request from HEYGEN_API_BASE, and #5181 added two guards around it:
  • HOST_ONLY stops a project .env from setting the base;
  • a base outside heygen.com gets no stored or host OAuth credential.
• This PR's HEYGEN_API_URL path has neither guard. At this head it's safe only by accident: HEYGEN_BASE is computed at import, before loadEnvFromDir runs. I probed it: a .env with HEYGEN_API_URL=https://attacker.example leaves the base at api.heygen.com.
• If the rebase folds HEYGEN_API_URL into main's lazy heygenBase(), a cloned project's .env could point the person's ~/.heygen OAuth token or shell key at any host. That is the exact hole #5181's last commit closed for HEYGEN_API_BASE.
• So either:
  • (a) drop the media-use host change and have Desktop #3056 set HEYGEN_API_BASE, the variable main already honors; or
  • (b) route HEYGEN_API_URL through the same rules: add it to HOST_ONLY, apply the heygen.com-only credential check and the HEYGEN_ALLOW_HTTP rule, and add a test that a .env value is ignored.
• Option (a) also avoids two env vars that mean "media host".
• At this head, the media-use tests pass (11/11), and mutants hard-coding the host or dropping the trailing-slash strip are caught (2/2).

Nits

• Precedence differs between the two halves. With both HEYGEN_API_KEY and HEYGEN_ACCESS_TOKEN set, the CLI uses the key while media-use uses the token, so the two halves of one Desktop agent run can bill different accounts. The body says this is deliberate. If Desktop can inherit a shell HEYGEN_API_KEY, the signed-in user's token loses in the CLI.
• Docs. skills/hyperframes-cli/references/cloud.md:33 and the hyperframes auth help's ENV VARS list don't mention HEYGEN_ACCESS_TOKEN.

CI: 92 passing, 2 skipped, none red, at this head. The required checks will need to re-run after the rebase.

Verdict: I can't approve. The login identity mismatch above needs a fix, the head conflicts with main, and the media-use half has to be reconciled with #5181's host guards. Re-ping me with the rebased head and I'll check the conflict resolution.

— Somu

[jrusso1020]

Not approving 1d5570646f. GitHub reports this head as conflicting with main, so it can't merge as it stands, and the rebase will need a new head. This adds to somanshreddy's review and agrees with it.

The media-use change should be dropped, not reconciled

main already covers this half. Since #5181 (21d14b25b), skills/media-use/audio/scripts/lib/heygen.mjs sends a host-injected HEYGEN_ACCESS_TOKEN as Bearer and moves every request to $HEYGEN_API_BASE. That host override comes with the guards this PR's HEYGEN_API_URL lacks:

• HOST_ONLY stops a project .env from setting the base.
• heygenOwnBase() keeps ~/.heygen credentials on heygen.com hosts.
• Plain HTTP is refused unless HEYGEN_ALLOW_HTTP=1.

If HEYGEN_API_URL is folded into main's per-request heygenBase(), it becomes a second, unguarded way to point the shared credentials somewhere else. Dropping the heygen.mjs hunk and its manifest hash, and having the host set HEYGEN_API_BASE, gets the same result with no new surface. It also fixes the header comment, which this PR changes from "matches the hyperframes CLI auth" because the two orders differ: media-use tries the access token before the API-key variables, and the CLI tries it after them.

CLI half: fine as written

• HEYGEN_ACCESS_TOKEN resolves after both API-key variables and before the store. It is header-checked through the new headerSafeEnv, and an empty value falls through as before.
• Callers of resolveCredential are cloud/auth.ts, commands/cloud.ts, commands/publish.ts and utils/publishProject.ts. refreshIfNeeded returns early without a refresh_token, and the forced refreshable: true on a 401 in publishProject.ts:193 also has no refresh token, so an env token is never refreshed or written to the store.
• Behavior only changes for someone who already exports HEYGEN_ACCESS_TOKEN in their shell. That token will now win over a valid ~/.heygen/credentials. That fits the documented order, but the release note should mention it.
• Nothing here is on the render path. No file under packages/core or packages/producer changes, and neither package imports the resolver.

A question for the host app

The CLI already works through a host gateway as it stands. auth/client.ts honours HEYGEN_API_URL, and an API-key credential goes out as x-api-key, which a gateway can check against its own per-run token. If the embedding app gives the agent its gateway base and a gateway token instead of the account's access token, this PR isn't needed for that app, and the access token never reaches the agent's environment. Please confirm the host-managed token is the intended design before this ships in a release.

CI. 85 checks passed and 2 were skipped at this head. Those results predate the conflict, so they need a fresh run after the rebase. I didn't run the CLI suites locally; somanshreddy's review covers them.

— Rames

[terencecho]

UPDATE: This initial COMMENT is superseded by my changes-requested review for the CLI login identity mismatch. I retracted the later test-path claim after verifying a tracked symlink. The earlier host/conflict analysis remains applicable.

Review at 1d5570646f74b2a487c4fc140b836d7ed90a63ee — not approving this head.

I checked the live PR and the credential/host patch. GitHub reports mergeable: CONFLICTING against current main, which includes #5181. This head cannot merge; the reconciliation will change the reviewed code. The CLI resolver adds HEYGEN_ACCESS_TOKEN after the two API-key environment sources and before the credential store, with refreshable: false. That changes existing caller precedence if the environment already supplies this token; it is not a blanket compatibility guarantee from green tests.

The media-use hunk adds HEYGEN_API_URL as a module-time host without main's #5181 HEYGEN_API_BASE guards for project .env provenance, credential destination, and HTTP opt-in. I did not establish that a project .env can redirect credentials at this head: the direct entrypoints import the helper before loading their project .env. But folding this extra host variable into main's per-request host selection during conflict resolution without those guards would weaken its credential boundary. The safer resolution is to drop the media-use host hunk and have Desktop use main's existing HEYGEN_API_BASE; otherwise apply the same guards and test them. Somu and Rames have detailed at-head reviews of the overlapping issue.

All 11 required checks pass at this head, but they predate the necessary conflict resolution. I did not run the local suites or inspect production request traffic; this is a client-side environment/credential path, and those checks cannot establish how a future conflict resolution treats a project .env. Please re-ping with the rebased head for a fresh verdict.

— tai

[terencecho]

CORRECTION: I retract the earlier test-path finding in this review. packages/cli/src/audio/scripts is a tracked symlink to skills/media-use/audio/scripts, so the import resolves in a checkout that preserves symlinks. Somu reports the 11 media-use tests pass. My ERR_MODULE_NOT_FOUND reproduction used a checkout without that symlink; treating the unexpanded Git tree path as proof of absence was wrong. The login identity mismatch below remains a changes-requested issue.

Review at 1d5570646f74b2a487c4fc140b836d7ed90a63ee — requesting changes after a follow-up source audit. This supersedes my earlier COMMENT review and adds a CLI login defect beyond the already reported merge conflict and host-guard reconciliation.

packages/cli/src/auth/resolver.ts:62-65 introduces an environment OAuth credential ahead of the file credential. Browser auth login persists its newly issued OAuth token to the file (auth/oauth.ts:208-209), then commands/auth/login.ts:228-253 calls tryResolveCredential() to report the identity. With HEYGEN_ACCESS_TOKEN for account A still set while someone completes browser login for account B, the resolver selects A, /v3/users/me returns A, and saveUserInfo writes A's user block alongside B's newly saved OAuth token (auth/user.ts:73-81). The command and telemetry report A as the completed login; after the environment token is removed, the credential and cached identity disagree. A pre-existing API-key environment source had a similar precedence pitfall, but this PR makes the host-managed token a new way to trigger it. Identify the credential from the just-completed login rather than re-resolving the global priority list, and cover the dual-account case.

As detailed in my earlier review and by Somu and Rames, GitHub still reports this head CONFLICTING with main/#5181. A rebased media-use host selection must retain main's project-.env provenance and credential-destination restrictions; I have not found a project-.env redirect through the current direct entrypoints at this unreconciled head. The CLI's API-key precedence and non-refreshable host token are otherwise as intended. All 11 required checks report green on this old head, but they do not validate the rebased resolution. I did not run the full local suites or inspect production request traffic.

— tai

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 8, 2026, 1:18 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[jrusso1020]

Re-review at af4eaae4. Approving. Both findings from the 1d557064 round are fixed. I read 0d31f991 in full and the five commits after it as deltas.

Prior findings

• Media-use host hunk: dropped. The PR no longer changes anything under skills/media-use. Media-use stays on main's HEYGEN_API_BASE path, with its HOST_ONLY, heygenOwnBase() and HTTP opt-in guards, so there's no second, unguarded host variable. GitHub reports the head as mergeable, and git merge-tree against current main is clean.
• Login identity mismatch: fixed.
  • runOAuthLogin now keeps the tokens that startAuthorizationCodeFlow() returns (oauth.ts:210) and identifies the account from issuedCredential(tokens). It no longer re-resolves, so an env HEYGEN_ACCESS_TOKEN (or HEYGEN_API_KEY) can't outrank the tokens this login just issued.
  • The device path uses the same helper.
  • The 401 refresh hook still works because AuthClient gates refresh on refresh_token (client.ts:139), not on refreshable, and the issued credential carries the refresh token.
• Docs: updated. auth help, cli.mdx and skills/hyperframes-cli/references/cloud.md all list HEYGEN_ACCESS_TOKEN in the resolution order.

Since 0d31f991

• auth logout now names whichever env credential is still active, including HEYGEN_ACCESS_TOKEN. To do that, ENV_CREDENTIAL_VAR moved into resolver.ts and is shared by logout, publish and the 401 message, so the three can't drift apart. There's a new test, and dropping the env_oauth entry fails it.

• af4eaae4 is a pure refactor. The resolver, auth status labels, logout, publish and the 401 message now all read the variable names from ENV_CREDENTIAL_VAR, which is typed Record<EnvSource, string>, through envCredentialVar(source). No user-facing string changes.

• The auth guide now says the media order applies to the bundled audio scripts, and that media-use resolve goes through the separate heygen CLI.

• When publish gets a 401 with a host token, it now says HEYGEN_ACCESS_TOKEN was rejected. Fix or unset it instead of asking for a login that would never be used. ENV_CREDENTIAL_VAR covers all three env sources, and there's a test for it. In publish.ts, the --update/--space branch runs only for non-OAuth credentials, so the env_oauth entry there is never used and does no harm.

• docs/guides/authentication.mdx now gives media-use's real order: HEYGEN_API_BASE + key, then the access token, then the API keys, then the store. That matches main's heygen.mjs header. It also says a project .env never sets HEYGEN_API_BASE, and that the CLI checks the keys first.

Verification

• Ran locally at af4eaae4: resolver.test.ts, login.test.ts and logout.test.ts pass, 43 tests in total.
• I couldn't run status-user.test.ts or publishProject.test.ts with the dependencies on hand: they failed to import @hyperframes/engine/system-memory and ignore, and in status-user.test.ts that includes the tests that predate this PR. CI covers both files.
• Mutants, all caught (3/3):
  • reverting login.ts to re-resolve the credential fails the dual-account test;
  • reading HEYGEN_ACCESS_TOKEN without headerSafeEnv fails the control-character test;
  • moving the token ahead of the API keys fails both precedence tests.
• CI: all 11 required checks are green at af4eaae4. They were also all green at 55b48e58 and 4fc98c03. At 0d31f991, the Test aggregator was red only because the newer push cancelled its studio shard (studio=cancelled).

Non-blocking

• Dropping no_credential from AuthLoginFailureReason is correct, because the login no longer re-reads the store. Any dashboard that groups auth_login_failed by reason will just stop seeing that value.
• The precedence difference is now documented, but it still exists, and it lives in main's media-use code rather than in this PR. If a host sets both a key and the token, the CLI and media-use can bill different accounts. Worth a line in the release note alongside "an exported HEYGEN_ACCESS_TOKEN now wins over ~/.heygen/credentials".
• My earlier question still applies to the embedding app's design rather than to this PR: should it hand the agent a gateway base and a per-run token, or the account's access token? The CLI change is sound either way.

terencecho's CHANGES_REQUESTED at 1d557064 is still live, so this approval does not open the merge gate on its own.

— Rames

[miguel-heygen]

New head af4eaae addresses the reviews at 1d557064.

Conflict with main / #5181 (tai, Somu, Rames). I merged main in without a force-push (6e2f8f48d). For media-use I took Rames's and Somu's option (a): this PR's HEYGEN_API_URL host change to heygen.mjs is dropped, and skills/media-use/** matches main exactly. #5181's HOST_ONLY project-.env guard, the heygen.com-only credential check and the HEYGEN_ALLOW_HTTP rule are untouched, and there is only one variable for the media host. The test that imported the helper through both paths went with it. A host that needs a non-production API sets HEYGEN_API_BASE, which main already honors. The title and body now describe a CLI-only change.

Login reports the wrong account (tai; confirmed by Somu). Fixed at the root in c50dd8fad. auth login no longer resolves credentials again after a browser sign-in. Both the browser and device flows now verify the account using the tokens the login just issued (issuedCredential in commands/auth/login.ts), so an environment HEYGEN_ACCESS_TOKEN or HEYGEN_API_KEY can no longer outrank them. That lookup could no longer come back empty, so the no_credential failure reason is gone too. The new test in login.test.ts sets an environment token for account A and completes a browser login as B. It checks that B's user block is saved next to B's token and that telemetry records B. Without the fix it fails with expected 'a@example.com' to be 'b@example.com'. With the fix the file passed 3 runs in a row, and the auth, auth-command and telemetry tests pass (522).

Test import path (tai, retracted). Agreed it resolves through the tracked symlink. The test is removed along with the media-use change.

Nits (Somu).

• Precedence differs between the halves: still true, and it comes from main's media-use order, which this PR no longer touches. For the Desktop case it can't split billing: HyperFrames Desktop only injects the token when the agent's environment has no HEYGEN_API_KEY/HYPERFRAMES_API_KEY and there is no ~/.heygen/credentials, so both halves see only the token. A follow-up PR after this one makes media-use check the API keys first too, so there is one order.
• Docs: HEYGEN_ACCESS_TOKEN is now in the hyperframes auth help, the order list and table in docs/packages/cli.mdx, and skills/hyperframes-cli/references/cloud.md (0d31f9918). The skills manifest is in sync.

Three more fixes from my own review of the new head.

• publish answered a rejected HEYGEN_ACCESS_TOKEN with "Your login expired. Run hyperframes auth login", which can't help while the token outranks any login. It now names the variable, as it already did for the API-key variables, using one map shared with publish --update/--space (c2875769c, with a test that fails without it).
• docs/guides/authentication.mdx listed a media-workflow credential order that main no longer has. It now shows what heygen.mjs resolves (gateway, host token, API keys, store), the .env rule, and the CLI's different order (4fc98c035). It also says that media-use resolve searches through the separate heygen CLI, which resolves its own credential (55b48e582).
• auth logout warned about the API-key variables but not HEYGEN_ACCESS_TOKEN, so it said "Signed out" while the token kept signing every command. One map of environment credential variables, owned by the resolver, now feeds the logout warning and both publish messages (482d56a4f, with a test that fails without it). The resolver's own reads and the auth status labels use the same map, so the variable names are written in one place (af4eaae4a).

Release note (Rames). Added to the body: a shell that already exports HEYGEN_ACCESS_TOKEN will now have it used ahead of ~/.heygen/credentials.

Whether the host-managed token is the intended design (Rames). Yes. Miguel confirmed on 2026-10-08: keep the host-managed access token as built, with no gateway token.

[somanshreddy]

Re-review at af4eaae4, covering the merge of main (6e2f8f48) plus the 6 commits after it. Every point from my review 5447470999 at 1d557064 is resolved.

• Conflict / media-use HEYGEN_API_URL: media-use is now exactly main's. git diff against current main is empty for media-use, and git merge-tree against current main is clean, even though main is 4 commits ahead. That means #5181's HOST_ONLY .env skip and its heygen.com-only credential guard are the only path, so the lazy-rebase concern is gone.
• tai's reportIdentity bug (which I confirmed): fixed. Both browser and device login now verify issuedCredential(tokens), the tokens that login just received, so an env HEYGEN_ACCESS_TOKEN can't be cached as the new account's identity.
  • The refresh hook still works. AuthClient refreshes on 401 whenever the credential has a refresh_token, regardless of refreshable.
• Host token is named, not "login expired": envCredentialVar now covers env_oauth, so publish --update/--space and the publish rejection message name HEYGEN_ACCESS_TOKEN. Logout's warning lists every active env name from the resolver's single map.

Tests: CLI resolver, login, logout, status-user and publishProject pass 101/101 locally.

Mutants, 3/3 caught:

• reportIdentity re-resolving instead of using the issued tokens;
• logout's warning missing HEYGEN_ACCESS_TOKEN;
• the publish rejection naming only API-key env vars.

CI: still running at the time of review (24 checks pending, 117 green so far). tai's CHANGES_REQUESTED at 1d557064 is still open; it's tai's to clear.

— Somu

Requested on an older commit; later commits answer it (see the thread). Current head is af4eaae.