byted-util-ark-cua

ARK CUA

Operate ARK CUA through the bundled Python CLI. Keep all gateway access inside the CLI and never request an AgentPlan API key in chat.

Command surface

python3 <skill-dir>/scripts/cua.py <command> [options]

Parse the single JSON object printed by each invocation:

• Success: ok: true, with data and sometimes next.
• Failure: ok: false, with error.code and sometimes next.setup_command.

Read references/commands.md for non-core commands. For a credential intent, read references/credentials.md before acting. Read references/auth.md, references/outcomes.md, or references/troubleshooting.md only when the corresponding state occurs.

Core workflow

1. Run auth status. When no credential is configured, the CLI first probes arkcli through a private temporary HOME snapshot so read-only discovery also works in restricted sandboxes. It selects the first profile with type=agent-plan and plan_tier=max, then reads its key in memory. It never assumes the active arkcli profile is eligible or writes to the real arkcli state.
2. On AUTH_REQUIRED, inspect error.arkcli_status / error.arkcli_hint. Follow a recoverable arkcli hint first (for example, select or refresh its key), then retry auth status. If arkcli is missing or that path cannot complete, relay setup_command and ask the user to run it in their own local terminal; the existing hidden API-key prompt is the fallback. Never accept the key in chat. On TOKEN_EXPIRED or REFRESH_FAILED, follow the same recovery path.
3. When the user explicitly wants to use a different API key even though arkcli is available, ask them to run auth login --manual in their own local terminal. This mode bypasses arkcli only for that login, validates the hidden input, and stores it in the protected cache that business commands already prefer. A rejected manual credential fails back to the same manual setup path instead of silently switching to arkcli, which prevents operations from targeting the wrong desktop. auth logout removes the manual override and restores normal arkcli discovery. Never accept the key in chat or as a command argument.
4. After the user confirms login completed, run auth status again. If data.real_name_verification.status is unverified, explain that a new CUA cannot be allocated until Volcengine real-name verification is complete, and provide its verification_url. Do not describe the API key as invalid. An existing allocated CUA remains usable and its invocations are not stopped.
5. Run delegate --objective "<user request>" once. Preserve the user's objective without planning or decomposing it.
6. Record data.invocation_id; never submit the same request again.
7. Drive data.outcome until terminal:
   • in_progress: run next.command and continue watching.
   • needs_input: relay data.input_request.question verbatim, then submit the user's reply with answer.
   • completed: use data.result.text as the authoritative result.
   • failed: report the failure; retry only when requested and safe.
   • cancelled: report cancellation.