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

[areslp]

Summary

lark-cli's device-flow authorization guidance for AI agents steers the agent into running the blocking auth login --device-code poll inside the same agent turn that produced the verification URL. On agent harnesses that deliver only the agent's final turn message (i.e. they don't stream intermediate output), the verification URL is never delivered — it stays buffered in a turn that never completes while the poll blocks. The user sees nothing and the agent appears to hang silently, usually until the device code expires, after which it often retries, producing an effectively silent infinite loop.

Environment

• lark-cli (@larksuite/cli) 1.0.30
• Harness: a headless claude agent (Claude Code -p / print mode) embedded in a chat gateway that posts the agent's reply to chat only when the turn completes; intermediate assistant messages are not streamed.

What happens

1. lark-cli docs +fetch … → Error: need_user_authorization (user: ou_…)
2. lark-cli auth login --domain docs --no-wait --json → returns device_code, verification_url, and a hint.
3. The hint says, verbatim: "Show verification_url to the user … Then immediately execute: lark-cli auth login --device-code <code> (blocks until authorized or timeout). Do not instruct the user to run this command themselves." — and auth login --help says "this command blocks until the user completes authorization in the browser. Run it in the background…".
4. Following that guidance, the agent emits the URL as an assistant message and then runs the blocking --device-code poll within the same turn.
5. The turn never completes (the poll blocks for the device code's full lifetime). Because the harness delivers only the final turn message, the URL the agent emitted is never sent to the user.
6. The user sees nothing; the device code expires; the agent commonly retries from step 2.

Observed in practice: the agent produced a correct "please authorize: <url>" message six times over ~30 minutes — the user received none of them, because the turn never ended.

Why the current guidance is fragile

It implicitly assumes the harness surfaces output produced mid-turn (streaming). Interactive Claude Code in a terminal does. But many chat-gateway / async agent integrations deliver only the agent's final turn output — for those, "show the URL, then block in-turn" guarantees the URL is never seen.

Suggested fix

Change the device-flow guidance — the auth login --help "For AI agents" text, the hint field in auth login --no-wait --json output, and the bundled lark-* agent skills — to recommend a yield pattern instead of a block pattern:

On need_user_authorization: run auth login --no-wait to obtain the verification URL, present the URL to the user as the final message of the turn, then end the turn / return control. Do not block on --device-code within the same turn. Complete authorization by polling --device-code in a separate, later step (e.g. after the user replies that they have authorized).

The --no-wait / --device-code split already supports this cleanly — only the guidance steers agents the wrong way. At minimum, the hint should drop "immediately execute … (blocks …)" and make clear that, for harnesses without mid-turn streaming, the agent should end its turn after presenting the URL.

---

(Likely distinct from #747, which concerns the poll's timeout duration rather than the turn-blocking guidance.)

[jshaofa-ui]

larksuite/cli #928 — Device-Flow Auth Login AI Agent Hang

Issue

URL: #928
Title: Device-flow auth login guidance makes AI agents block the turn, causing silent hangs on non-streaming harnesses
Severity: Critical — breaks AI agent workflows using lark-cli
Labels: domain/doc, domain/core, domain/auth
Affects: All AI agents/bots using lark-cli in non-streaming harnesses

Root Cause Analysis

The problem is a guidance + UX design conflict between lark-cli's device-flow auth flow and AI agent execution models:

1. lark-cli outputs a hint: "Show verification_url to the user … Then immediately execute: lark-cli auth login --device-code <code>"
2. AI agents follow instructions literally — they run the blocking --device-code poll in the same turn
3. Non-streaming harnesses (like Claude Code -p in chat gateways) only deliver the final turn output
4. The verification URL is never delivered to the user because the turn never completes (blocked on polling)
5. Result: silent infinite loop until device code expires, then retry
   The auth login --help says "this command blocks until the user completes authorization in the browser. Run this in the background…" — but the hint from --no-wait contradicts this by telling the agent to run it immediately (blocking the turn).

Proposed Fix

Replace the current hint with agent-safe guidance:

Device flow initiated.

1. Open this URL in a browser to authorize: <verification_url>
2. After authorizing, run this command SEPARATELY (not in the same turn):
   lark-cli auth login --device-code <code>

IMPORTANT: Do NOT run the device-code command in the same agent turn.
The verification URL must be delivered to the user first.

Add a dedicated mode for AI agent workflows:

lark-cli auth login --device-code <code> --agent-mode

In --agent-mode:

1. Output the device code and verification URL as structured JSON (machine-parseable)
2. Exit immediately with exit code 2 (special: "waiting for user authorization")
3. Provide a separate --check-device-code <code> command for polling
4. The agent can: deliver URL → exit → user authorizes → agent polls separately

// src/commands/auth/login/device-flow.ts
if (options.agentMode) {
  // Output structured JSON
  console.log(JSON.stringify({
    status: 'pending_user_authorization',
    device_code: code,
    verification_url: url,
    expires_in: interval,
    check_command: `lark-cli auth login --device-code ${code} --check-only`
  }));
  process.exit(2); // Special exit code for "waiting"
}

Change the default behavior of auth login --device-code:

• Default: Start polling in background, output status JSON, exit immediately
• --wait flag: Block until authorized (current behavior, for scripts that need it)

# New default behavior (agent-safe)
$ lark-cli auth login --device-code <code>
{"status":"polling","device_code":"...","message":"Polling in background. Use --wait to block."}

# Explicit blocking (for existing scripts)
$ lark-cli auth login --device-code <code> --wait
Waiting for authorization...
Authorized! Token stored.

Recommended Implementation (Option C)

// src/commands/auth/login/index.ts
const deviceCodeLogin = async (code: string, options: DeviceCodeOptions) => {
  const polling = startDeviceCodePoll(code);
  
  if (options.wait) {
    // Current behavior: block until done
    await polling.complete();
    console.log('Authorized!');
  } else {
    // New default: start background polling, exit immediately
    console.log(JSON.stringify({
      status: 'background_polling',
      device_code: code,
      message: 'Polling for authorization. Use `lark-cli auth status` to check.',
    }));
    
    // Keep process alive briefly to ensure polling starts
    await new Promise(r => setTimeout(r, 500));
  }
};

Impact

• AI agents using lark-cli will no longer hang silently
• Existing scripts using --device-code will need --wait flag (breaking change, but fixable)
• Documentation should be updated to reflect new behavior
• Backward compatibility: Add deprecation warning for non---wait usage in v1.x, require --wait in v2.x