jackwener / jackwener/OpenCLI

[Bug]: TIMEOUT hint tells users to pass --timeout, which adapter commands do not accept

Open Beginner friendly
#2,415 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
29.3k
Forks
2.9k
Avg merge
15h 36m
Merged PRs (30d)
70

Description

### Description

The default hint on `TimeoutError` tells the user to retry with `--timeout `, but adapter commands do not accept that flag. Following the advice produces a second, unrelated error.

`src/errors.ts:117-126`:

```js
export class TimeoutError extends CliError {
constructor(label: string, seconds: number, hint?: string) {
super(
'TIMEOUT',
`${label} timed out after ${seconds}s`,
hint ?? 'Try again, or increase timeout with --timeout (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)',
EXIT_CODES.TEMPFAIL,
);
}
}
```

Only two commands in the repo declare `--timeout`, and neither is an adapter command:

- `src/cli.ts:2412` — `browser wait`, as `--timeout ` (milliseconds, not seconds)
- `src/cli.ts:3612` — `antigravity serve`, as `--timeout `

The `OPENCLI_BROWSER_COMMAND_TIMEOUT` half of the hint is correct and does work.

### Steps to Reproduce

```bash
# 1. Force a timeout on any adapter command
$ OPENCLI_BROWSER_COMMAND_TIMEOUT=1 opencli xiaohongshu search "opencli" --limit 3
ok: false
error:
code: TIMEOUT
message: xiaohongshu/search timed out after 1s
help: Try again, or increase timeout with --timeout (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)
exitCode: 75

# 2. Follow the advice verbatim
$ opencli xiaohongshu search "opencli" --limit 3 --timeout 90
error: unknown option '--timeout'
$ echo $?
1
```

### Expected Behavior

The hint should only mention mechanisms that exist for the command that timed out. Since `OPENCLI_BROWSER_COMMAND_TIMEOUT` is the actual knob for adapter commands, the simplest correct fix is to drop the `--timeout` clause from the default hint:

```js
hint ?? 'Try again, or raise the global default with OPENCLI_BROWSER_COMMAND_TIMEOUT='
```

Alternatively, if per-command override is intended to be user-facing, adding `--timeout ` to adapter commands would also resolve it — but that is a feature change, whereas the hint is wrong today either way.

Worth noting the unit inconsistency while this is being touched: `browser wait` uses `--timeout ` and `antigravity serve` uses `--timeout `, so a user who does find a working `--timeout` may still pass the wrong magnitude.

### Impact

Cosmetic but squarely in the failure path, where the user is already stuck and most likely to trust the tool's own suggestion. It also misleads agents driving OpenCLI programmatically: the natural recovery is to retry with the flag the error text named, which fails with a different error and a different exit code (1 instead of 75), turning one retryable timeout into an opaque usage error.

Scope: 49 of the `new TimeoutError(...)` call sites pass an explicit `hint` and are unaffected. The default hint is reached from the generic wrapper `runWithTimeout()` at `src/runtime.ts:24-31` (used by adapter command execution) plus a handful of adapters that omit the third argument, e.g. `clis/grok/ask.js:71`, `clis/youtube/search.js:347`, `clis/bilibili/creator-stats.js:84`, `clis/trae-cn/ask.js:89`.

### Environment

- OpenCLI: 1.8.7 (source verified at `90d5070`)
- Extension: 1.0.23 (Browser Bridge connected)
- OS: macOS 26.5 (Darwin 25.5.0, arm64)

Contributor guide

Open the contributing guide

Research direction

Start in src/errors.ts:117-126 and inspect how the default TimeoutError hint is reached through runWithTimeout() in src/runtime.ts:24-31. Reproduce an adapter timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT and verify the resulting guidance names only a valid mechanism, while the 49 call sites with explicit hints remain unaffected.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Bug
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.