feat(cli): doc wait command (multi-target wait-all)

weknora doc wait <doc-id> [<doc-id>...] blocks until every given document
reaches a terminal parse_status (completed / failed), --timeout expires,
or the user interrupts (SIGINT).

* --timeout DURATION (default 10m; exit 124 on timeout, matches GNU
  timeout(1) convention)
* --interval DURATION (default 2s; exponential backoff to 15s + jitter)
* Multi-id polled concurrently (max 5 parallel)
* Exit code priority 1 > 124 > 0 (failed > timeout > completed)

New typed errors:
* operation.timeout → exit 124
* operation.failed → exit 1
* operation.cancelled → exit 1 (main raises to 130 on signal)

server.session_create_failed gets a special case in ExitCode to map to
exit 1 (workflow failure, not transient retry).

doc view and doc download positional id namespaced to <doc-id>.
This commit is contained in:
nullkey
2026-05-18 01:38:01 +08:00
committed by lyingbug
parent 567d7ac74e
commit 7eeb3bec5d
11 changed files with 654 additions and 49 deletions
+24 -4
View File
@@ -32,10 +32,10 @@ const (
CodeInputInvalidArgument ErrorCode = "input.invalid_argument"
CodeInputMissingFlag ErrorCode = "input.missing_flag"
// CodeInputConfirmationRequired marks a high-risk write that has no
// interactive UI (non-TTY or --json) and was invoked without -y/--yes.
// Mapped to exit code 10 (see cli/README.md). Agents must surface the
// error to the user and only retry with -y after explicit human
// approval; never auto-retry.
// interactive UI (non-TTY or JSON-output mode) and was invoked without
// -y/--yes. Mapped to exit code 10 (see cli/README.md). Agents must
// surface the error to the user and only retry with -y after explicit
// human approval; never auto-retry.
CodeInputConfirmationRequired ErrorCode = "input.confirmation_required"
// server.* / network.*
@@ -49,6 +49,24 @@ const (
// server.error so agents can retry with their own --session.
CodeSessionCreateFailed ErrorCode = "server.session_create_failed"
// operation.* - CLI-level wait/poll results
// CodeOperationTimeout marks a CLI-level wait/poll operation that exhausted
// its --timeout window. Distinct from CodeServerTimeout (HTTP 504). Mapped
// to exit 124 (matches the convention from GNU `timeout`).
CodeOperationTimeout ErrorCode = "operation.timeout"
// CodeOperationFailed marks a CLI-level wait/poll operation where one or
// more targets reached a terminal failure (e.g. doc wait found a doc with
// parse_status=failed). Distinct from server.* / network.* because the
// failure is the target's own terminal state, not a transient transport
// issue. Maps to exit 1 via the fall-through bucket.
CodeOperationFailed ErrorCode = "operation.failed"
// CodeOperationCancelled marks a long-running command interrupted by a
// caught signal (SIGINT / SIGTERM after main.go's signal.NotifyContext
// fires). Distinct from CodeUserAborted (declined confirm prompt) — the
// hints differ. main.go overrides the exit code to 130 for cancelled
// contexts so the user-visible exit follows Unix signal convention.
CodeOperationCancelled ErrorCode = "operation.cancelled"
// local.* - config / file / keychain on the user's machine
CodeLocalConfigCorrupt ErrorCode = "local.config_corrupt"
CodeLocalKeychainDenied ErrorCode = "local.keychain_denied"
@@ -265,6 +283,8 @@ func AllCodes() []ErrorCode {
CodeProjectLinkCorrupt,
CodeUserAborted, CodeUploadFileNotFound,
CodeSSEStreamAborted, CodeSessionCreateFailed,
// operation
CodeOperationTimeout, CodeOperationFailed, CodeOperationCancelled,
// mcp
CodeMCPReadonlyMode, CodeMCPToolNotAllowed, CodeMCPSchemaUnknown,
}
+20 -6
View File
@@ -8,11 +8,10 @@ import (
// ExitCode maps an error to the documented CLI exit code.
// - 0 success
// - 1 generic / unknown typed error - fallback for: resource.already_exists,
// resource.locked, local.* (config_corrupt / keychain_denied / file_io /
// context_not_found / kb_id_required / kb_not_found / projectlink_corrupt /
// user_aborted / upload_file_not_found), mcp.*, server.session_create_failed,
// sse.stream_aborted, and any code outside the named buckets below
// - 1 generic / unknown typed error - fallback bucket: resource.already_exists,
// resource.locked, local.*, mcp.*, operation.failed, server.session_create_failed
// (workflow-level, see special case below), and any code outside the named
// buckets below
// - 2 flag / argument problem (cobra parse / unknown subcommand)
// - 3 auth.*
// - 4 resource.not_found
@@ -21,6 +20,8 @@ import (
// - 7 server.* (other than rate_limited/session_create_failed) / network.*
// - 10 input.confirmation_required - high-risk write needs explicit -y
// (see cli/README.md)
// - 124 operation.timeout - CLI-level wait/poll exhausted its --timeout window
// (matches the convention from GNU `timeout`)
// - 130 SIGINT (handled by Go runtime, not this function)
func ExitCode(err error) int {
if err == nil {
@@ -48,9 +49,18 @@ func ExitCode(err error) int {
if matchCode(err, CodeServerRateLimited) {
return 6
}
// server.session_create_failed is a workflow-level failure (the hint
// asks the caller to pass --session, not to retry with backoff), so it
// falls through to exit 1 rather than the server.* transient bucket.
if matchCode(err, CodeSessionCreateFailed) {
return 1
}
if matchPrefix(err, "server.") || matchPrefix(err, "network.") {
return 7
}
if matchCode(err, CodeOperationTimeout) {
return 124
}
return 1
}
@@ -122,9 +132,13 @@ func defaultHint(code ErrorCode) string {
case CodeUploadFileNotFound:
return "verify the path is correct and readable"
case CodeSSEStreamAborted:
return "the streaming answer was cut off mid-flight; retry, or pass --no-stream to buffer the full response"
return "the streaming answer was cut off mid-flight; retry, or pass --format json to buffer the full response"
case CodeSessionCreateFailed:
return "could not create a chat session; pass --session to reuse an existing session"
case CodeOperationTimeout:
return "wait timed out; raise --timeout or check the underlying job"
case CodeOperationCancelled:
return "operation cancelled by signal (Ctrl-C / SIGTERM)"
}
return ""
}
+4
View File
@@ -28,6 +28,10 @@ func TestExitCode(t *testing.T) {
{"network.* prefix", NewError(CodeNetworkError, "x"), 7},
{"unknown error", errors.New("plain"), 1},
{"local.* prefix", NewError(CodeLocalConfigCorrupt, "x"), 1},
{"operation.timeout", NewError(CodeOperationTimeout, "timed out"), 124},
{"operation.failed → 1 (fall-through bucket)", NewError(CodeOperationFailed, "failed"), 1},
{"operation.cancelled → 1 (main overrides to 130 on signal-cancelled ctx)", NewError(CodeOperationCancelled, "cancelled"), 1},
{"server.session_create_failed → 1 (workflow, not transient)", NewError(CodeSessionCreateFailed, "x"), 1},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {