/byted-util-ark-cua

name: byted-util-ark-cua
description: Delegate broad computer-use tasks to ARK CUA for Volcengine AgentPlan users through an authenticated cloud desktop, and synchronize explicit credentials to a caller-owned CUA through Credential Agent. Use for web or desktop-app operation, file workflows, reusable task contexts, artifacts, temporary CUA App URLs, desktop shutdown/start/recovery, inspection, or exact browser, environment, secret, Credential Set, and managed-file credential setup/sync/status/reset. Do not use when local reasoning or a purpose-built local/API tool can complete the request more directly.
version: 1.0.7
license: Apache-2.0

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](references/commands.md) for non-core commands. For a credential intent, read [references/credentials.md](references/credentials.md) before acting. Read [references/auth.md](references/auth.md), [references/outcomes.md](references/outcomes.md), or [references/troubleshooting.md](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.

If task creation returns `ACTIVE_RUN_CONFLICT`, the new request did not start. Stop, tell the user the desktop is busy, and do not retry or inspect the existing task unless the user explicitly asks.

If an operation returns `VOLCENGINE_REAL_NAME_REQUIRED`, it did not allocate a new CUA. Show `verification_url`, ask the user to complete verification on the Volcengine platform, then rerun `auth status` before retrying. Never log out or replace a valid API key for this error. `VOLCENGINE_REAL_NAME_CHECK_UNAVAILABLE` is retryable, but a failed create operation must not be duplicated blindly.

Route special intents

• Specific desktop or reusable context: use `desktop list`, `task run`, `context`, and `task continue`.
• CUA App login URL: run `desktop access` after the requested work finishes. Return its new `data.full_interface_url`, falling back to `data.access_url`. Never reuse a URL from an earlier result. On `runtime_capability_required`, revoke the failed ticket and run `desktop access` once for a fresh URL; never rewrite the gateway-owned path. If the fresh URL also fails, report a gateway/runtime configuration failure. Use `desktop revoke-access` if a URL may have leaked or is no longer needed.
• Local file delivery: remove only local-delivery wording from the CUA objective, have CUA export a registered artifact, then use `artifact list` and `artifact save`.
• Health or configuration inspection: use `ping`, `diagnose`, or `model get`; do not create a task merely to test availability.
• Credential preparation, status, synchronization, or reset: use the `credentials` commands, not `delegate` or `task run`. The signed Agent installer and exact browser/resource sync orchestration are embedded in this Skill; do not download, install, or invoke another Skill. The CLI checks Gateway capability before installing or changing the local Agent. Initial Chrome extension installation is intentionally one cross-platform manual Load unpacked action: relay the exact `SOURCE_BROWSER_USER_ACTION_REQUIRED` message, then rerun the same request after the user fi