fix: guide agents to yield during auth device flow

[LawyerLyu]

Summary

Fixes the device-flow guidance for AI agents so non-streaming harnesses do not block the same turn that is supposed to deliver the verification URL to the user.

Changes

• Update auth login --help and no-flags guidance to recommend the --no-wait --json split-flow for non-streaming agent harnesses.
• Change the auth login --no-wait JSON hint to tell agents to present the URL as the final message of the turn and poll --device-code later after the user confirms authorization.
• Update the synchronous login agent hint and lark-shared skill guidance with the same yield pattern.
• Add regression tests for help text, no-wait JSON hints, and localized agent hints.

Test Plan

• Unit tests pass: go test ./cmd/auth
• Manual local verification confirms the lark xxx command works as expected: auth help/no-wait guidance is covered by tests and produces the updated split-flow wording

Related Issues

• Fixes Device-flow auth login guidance makes AI agents block the turn, causing silent hangs on non-streaming harnesses #928

Summary by CodeRabbit

• Improvements

  • Clarified auth login help text and interactive hints to guide non-streaming AI agents through a split, non-blocking device-code flow (e.g., use --no-wait/--json, return the verification URL as the final message, run --device-code later).
  • Updated English and Chinese user-facing hints for consistent wording.

• Tests

  • Added and updated tests to verify the new help text and agent timeout hints.

• Documentation

  • Updated agent authentication guide to document the split-flow device-code pattern.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 18700e32-1553-49d0-84ed-5b8a4ffd4c3c

📥 Commits

Reviewing files that changed from the base of the PR and between e6a7435 and 984a5ab.

📒 Files selected for processing (6)

• cmd/auth/auth_test.go
• cmd/auth/login.go
• cmd/auth/login_messages.go
• cmd/auth/login_messages_test.go
• cmd/auth/login_test.go
• skills/lark-shared/SKILL.md

✅ Files skipped from review due to trivial changes (3)

• skills/lark-shared/SKILL.md
• cmd/auth/login_messages.go
• cmd/auth/login_messages_test.go

🚧 Files skipped from review as they are similar to previous changes (3)

• cmd/auth/login.go
• cmd/auth/auth_test.go
• cmd/auth/login_test.go

---

📝 Walkthrough

Walkthrough

Updated device-flow authentication guidance and tests to recommend a non-blocking split-flow for AI agents: obtain the verification URL with --no-wait --json, present it as the final turn message, then resume polling later with --device-code.

Changes

Device-flow split-flow guidance refactor

Layer / File(s)	Summary
Auth guidance strings for split-flow pattern cmd/auth/login.go, cmd/auth/login_messages.go	Long description, interactive-mode log, --no-wait --json hint, and Chinese/English AgentTimeoutHint updated to instruct agents to present the verification URL as the final turn message, end the turn, and run --device-code later.
Guidance validation and contract tests cmd/auth/login_messages_test.go, cmd/auth/login_test.go, cmd/auth/auth_test.go	Tests added/updated to assert split-flow guidance substrings (--no-wait --json, final-turn/“本轮”, --device-code) appear in help, hint, and error messages.
Agent skill documentation example skills/lark-shared/SKILL.md	Skill docs rewritten to show two-step flow: call lark-cli auth login --no-wait --json, forward verification_url verbatim as the final message, then later run lark-cli auth login --device-code <device_code>.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• larksuite/cli#856: Updates auth hint/help text generation and raw-URL-forwarding clarifications in the same areas.

Suggested labels

domain/base

Suggested reviewers

• liangshuo-1
• albertnusouo

Poem

🐰 I found a URL and held it tight,
It must be shown before the night.
Yield the turn, let messages flow,
Come back later to finish the show. 🔐

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix: guide agents to yield during auth device flow' accurately and concisely summarizes the main change: updating guidance for AI agents to use a yield pattern rather than blocking during device-flow authentication.
Description check	✅ Passed	The PR description follows the template with all required sections completed: Summary clearly explains the fix, Changes lists the main modifications with specifics, Test Plan confirms testing was done, and Related Issues links to #928.
Linked Issues check	✅ Passed	The PR fully addresses issue #928's objectives: guidance is updated to recommend the --no-wait --json split-flow pattern, agents are instructed to present the URL as the final turn message and poll --device-code later, and tests are added to verify the changes.
Out of Scope Changes check	✅ Passed	All changes directly support the yield-pattern guidance fix: help text updates, hint modifications, test additions, and skill documentation changes are all scoped to the device-flow authentication guidance improvements.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 65.92%. Comparing base (898e0ee) to head (984a5ab).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #933   +/-   ##
=======================================
  Coverage   65.92%   65.92%           
=======================================
  Files         523      523           
  Lines       49692    49694    +2     
=======================================
+ Hits        32758    32760    +2     
  Misses      14134    14134           
  Partials     2800     2800           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@984a5ab165b36bfea2370b75dbd61b2b4b7918d5

🧩 Skill update

npx skills add LawyerLyu/cli#fix/auth-device-flow-agent-guidance -y -g