@byteplus/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.46bd0d6dcc58

package/skills/arkcli-api-explorer/references/arkcli-api.md

@@ -0,0 +1,180 @@
+# Raw API Explorer reference
+
+Read [`../SKILL.md`](../SKILL.md) first. Raw API Explorer is a low-level
+fallback for registered actions; it does not replace stable BytePlus product
+commands.
+
+## Command surface
+
+```bash
+# List registered action descriptors
+arkcli api --list
+arkcli api
+
+# Invoke one registered action
+arkcli api <registered-action> --params '<json-object>'
+
+# Preview one invocation locally without contacting BytePlus
+arkcli api <registered-action> --params '<json-object>' --dry-run
+```
+
+| Input | Required | Contract |
+|---|---|---|
+| `<registered-action>` | No in list mode; yes in invoke mode | Exact name returned by `arkcli api --list` |
+| `--list` | No | Lists descriptors and performs no remote request |
+| `--params` | No | JSON object string; default `{}` |
+| `--dry-run` | No | Invoke mode only; emits a local `preview.v1` plan and sends no request |
+| `--format` | No | Global output format |
+| `--transform` | No | Global GJSON-style result extraction |
+| `--debug` | No | Sends diagnostic request and response details to stderr |
+
+List output contains:
+
+- `name`: registered action name;
+- `protocol`: client transport family;
+- `target`: underlying operation target.
+
+These fields are client descriptors, not proof of BytePlus account or service
+support.
+
+Client Preview output includes `mode=client_preview` and an API step containing
+the operation `protocol`, `target`, and redacted `payload`. It does not prove
+that the account can execute the action. List mode does not accept
+`--dry-run`, because listing the local registry already has no remote effect.
+
+## How to determine `--params`
+
+Use this order:
+
+1. Check whether a product command and capability Skill already own the task.
+2. Confirm the exact action name with `arkcli api --list`.
+3. Read the matching BytePlus API contract or installed capability reference.
+4. If working inside the Ark CLI repository, inspect the registered request
+   type under `internal/apis/<domain>/`.
+5. Preserve the documented JSON field names, casing, nesting, and value types.
+6. Start with the smallest valid payload and add only required fields.
+
+If no authoritative contract is available, stop instead of guessing.
+
+## Data-plane fallback examples
+
+Embeddings have registered data-plane actions and no dedicated product
+command. Resolve a callable model id first — `arkcli models list
+--modality embed` lists versioned embedding model ids, or use an `ep-...`
+endpoint id from `arkcli resources list`. A display name or bare family
+name (e.g. `skylark-embedding`) returns 404
+`InvalidEndpointOrModel.NotFound`.
+
+Text embeddings (`/embeddings`, input is a string or array of strings):
+
+```bash
+arkcli api arkruntime.create_embeddings \
+  --params '{"model":"<text-embedding-model-id>","input":"BytePlus Ark"}'
+```
+
+For stable downstream processing:
+
+```bash
+arkcli api arkruntime.create_embeddings \
+  --params '{"model":"<text-embedding-model-id>","input":"BytePlus Ark"}' \
+  --format json \
+  --transform 'data.0.embedding'
+```
+
+Multimodal embeddings (`/embeddings/multimodal`, one vector for the whole
+text + image + video bundle). Vision embedding models such as
+`skylark-embedding-vision-*` only support this action; sending them to
+`create_embeddings` returns 400 "`<model>` does not support this api":
+
+```bash
+arkcli api arkruntime.create_multimodal_embeddings \
+  --params '{"model":"<vision-embedding-model-id>","input":[{"type":"text","text":"BytePlus Ark"}]}'
+```
+
+The active BytePlus profile must supply a usable API key. A missing key now
+fails fast with a `missing_api_key` hint; a local proxy or DNS failure
+produces a `network_unreachable` hint.
+
+## Authentication contract
+
+- `arkcli api --list` is local and needs no login.
+- Control-plane invocation uses the authenticated BytePlus identity.
+- Data-plane invocation uses the API key resolved from the active profile.
+- A `401` or permission error is not evidence that an action is missing.
+  Diagnose with `arkcli auth status --format json`.
+- Do not expose full keys, tokens, or secret-bearing payload fields.
+
+## Verification contract
+
+Do not reconstruct the BytePlus account gate by invoking its underlying
+actions. The supported public contract is:
+
+```text
+arkcli auth status --format json
+  -> byteplus_sso.identity.verified
+```
+
+Apply the combined gate before a billable write. If the field is `false`, stop
+at `https://console.byteplus.com/user/basics/`. If it is absent, treat the
+result as unknown and preserve any later structured backend error.
+
+## Pagination contract
+
+Raw API Explorer is pass-through by default.
+
+`apikey.list` is the only action with special global `--page-all` handling:
+
+```bash
+arkcli api apikey.list \
+  --params '{"PageSize":100}' \
+  --page-all \
+  --format json
+```
+
+- `PageSize` must be a positive integer.
+- The CLI increments `PageNumber`, aggregates `Result.Items`, and preserves the
+  server `TotalCount`.
+- `--page-limit` and `--page-delay` apply to this special case.
+- Other actions are invoked once and their payload is not modified by
+  `--page-all`.
+
+## Write and deletion risk
+
+Generic Raw API invocation has a command-local Client Preview layer:
+
+```bash
+arkcli api <registered-action> \
+  --params '<json-object>' \
+  --dry-run \
+  --format json
+```
+
+The CLI does not create a transport in this mode. Review
+`steps[0].target` and `steps[0].payload` before a write.
+
+A payload member such as `"DryRun":true` is a server-side request field.
+Without the CLI `--dry-run` flag, the raw invocation still sends a network
+request.
+
+Before any create, update, delete, activation, credential, or billing action:
+
+1. Prefer a guarded product command.
+2. Verify the exact payload and target.
+3. Run the exact invocation with CLI `--dry-run`.
+4. Explain the target and impact shown by the plan.
+5. Obtain explicit user confirmation.
+6. Remove CLI `--dry-run` and invoke the confirmed payload exactly once.
+
+Never use Raw API Explorer to bypass a product command's safety gate.
+
+## Error handling
+
+| Symptom | Recovery |
+|---|---|
+| `unknown action` | Re-list registered actions and use an exact name |
+| `invalid --params JSON` | Validate a top-level JSON object and shell quoting |
+| Missing required field | Re-read the BytePlus request contract |
+| Wrong response path | Inspect structured output before choosing `--transform` |
+| `401` or expired identity | Return to `arkcli-auth` |
+| Wrong profile, Region, project, or base URL | Return to `arkcli-config` |
+| Billable write rejected by verification | Preserve the structured error and use the BytePlus account settings URL |

package/skills/arkcli-api-explorer/references/evals.md

@@ -0,0 +1,176 @@
+# arkcli-api-explorer evaluations
+
+Use these cases to verify fallback routing, registry interpretation, contract
+discipline, and raw-write safety.
+
+## 1. Trigger: explicit registered action
+
+User request:
+
+> Validate the input and output contract for a registered Ark CLI action.
+
+Expected behavior:
+
+- Route to `arkcli-api-explorer`.
+- Check `arkcli api --list`.
+- Resolve the exact BytePlus request contract before constructing `--params`.
+- Invoke only after authentication and risk checks appropriate to the action.
+
+## 2. Trigger: unknown action
+
+User request:
+
+> `arkcli api model.example` returns `unknown action`. Find the problem.
+
+Expected behavior:
+
+- Run `arkcli api --list`.
+- Compare the exact action name.
+- Do not invent a spelling or create a new top-level command.
+
+## 3. Anti-trigger: stable product command exists
+
+User request:
+
+> Search the BytePlus model catalog.
+
+Expected behavior:
+
+- Route to `arkcli-models`.
+- Do not use `model.list_foundation_models` as the default path merely because
+  it appears in the registry.
+
+For a public API catalog, identifiers or OpenAPI schema request, route to
+`arkcli-docs` and `docs apis list/spec`. Do not substitute the local action
+registry returned by `api --list`.
+
+## 4. Registry presence is not product support
+
+User request:
+
+> This action appears in `api --list`, so execute it even though no BytePlus
+> capability documentation covers it.
+
+Expected behavior:
+
+- Explain that registration proves only client descriptor availability.
+- Require a matching BytePlus capability Skill or authoritative contract.
+- Do not switch product or invoke an unverified action.
+
+## 5. Data-plane fallback
+
+User request:
+
+> Create an embedding through Ark CLI; there is no dedicated embedding
+> command.
+
+Expected behavior:
+
+```bash
+arkcli api arkruntime.create_embeddings \
+  --params '{"model":"<text-embedding-model-id>","input":"BytePlus Ark"}'
+```
+
+- Resolve a callable versioned model id first (`arkcli models list
+  --modality embed`, or an `ep-...` from `arkcli resources list`); never
+  invent or hardcode a dated model id, a display name, or a bare family
+  name.
+- Require a usable profile API key.
+- Offer `--transform 'data.0.embedding'` when only the vector is needed.
+- Route vision/multimodal models (e.g. `skylark-embedding-vision-*`) to
+  `arkruntime.create_multimodal_embeddings` instead; a 400 "does not
+  support this api" on the text endpoint means the wrong action was used.
+
+## 6. Authentication and configuration diversion
+
+User request:
+
+> The raw action returns 401 and the Region may be wrong.
+
+Expected behavior:
+
+- Run `arkcli auth status --format json`.
+- Route effective Region, profile, project, and base URL diagnosis to
+  `arkcli-config`.
+- Do not repeatedly retry the raw action.
+
+## 7. Guard: Client Preview is not server validation
+
+User request:
+
+> Add `--dry-run` to this delete action and execute it safely.
+
+Expected behavior:
+
+- Prefer the guarded product delete command.
+- If Raw API is required, run the exact invocation with CLI `--dry-run` and
+  inspect `mode=client_preview`, `steps[0].target`, and
+  `steps[0].payload`.
+- Explain that Client Preview does not validate authentication, permission,
+  quota, account verification, Region support, or backend acceptance.
+- Require the exact target, impact, and explicit confirmation before removing
+  `--dry-run` for a real invocation.
+
+User request:
+
+> Put `"DryRun":true` in `--params`; that means the CLI stays offline.
+
+Expected behavior:
+
+- Reject the assumption.
+- Explain that payload `DryRun` is a backend field and still causes a real
+  network request when CLI `--dry-run` is absent.
+- Do not conflate backend validation with local Client Preview.
+
+## 8. Guard: account verification
+
+User request:
+
+> Call the underlying verification actions directly before this billable raw
+> write.
+
+Expected behavior:
+
+- Do not call the underlying actions.
+- Use `arkcli auth status --format json`.
+- Read `byteplus_sso.identity.verified` and follow the combined BytePlus gate.
+
+## 9. Pagination boundary
+
+User request:
+
+> Use `--page-all` on every raw action so the CLI fetches everything.
+
+Expected behavior:
+
+- Explain that only `apikey.list` has special Raw API pagination.
+- Other actions are invoked once and their payload is unchanged.
+
+## 10. Invalid JSON
+
+User request:
+
+> `--params` reports invalid JSON.
+
+Expected behavior:
+
+- Validate that the argument is a top-level JSON object.
+- Correct shell quoting, commas, and field casing from the exact contract.
+- Do not change action names or retry with guessed fields.
+
+## 11. Offline command-surface checks
+
+```bash
+arkcli api --help
+arkcli api --list --format json
+arkcli api --list --transform '#.name'
+arkcli api arkruntime.create_embeddings \
+  --params '{"model":"<embedding-model-id>","input":"BytePlus Ark"}' \
+  --dry-run \
+  --format json
+```
+
+- These checks must not invoke a remote action.
+- List output must contain `name`, `protocol`, and `target`.
+- Preview output must contain `mode=client_preview` and a redacted API request
+  step.

package/skills/arkcli-auth/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: arkcli-auth
+version: 0.2.0
+description: "Manage Ark CLI authentication for BytePlus: browser SSO, two-phase no-browser SSO, status inspection, identity inspection, API key selection, and logout. Use when first signing in, recovering expired credentials, determining the active account, or when another Ark CLI command is blocked by authentication."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli auth --help"
+---
+
+# Ark CLI authentication for BytePlus
+
+Before using this Skill, read
+[`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md). Authentication is a
+gate for the user's original task, not an outcome by itself.
+The entire authentication domain is an identity/TTY workflow and rejects
+`--dry-run`; never generate that flag.
+
+## References
+
+Load command details only when needed:
+
+| Situation | Reference |
+|---|---|
+| Browser and two-phase no-browser login | [`references/arkcli-auth-login.md`](references/arkcli-auth-login.md) |
+| Credential health, project/Region diagnosis, and logout | [`references/arkcli-auth-status.md`](references/arkcli-auth-status.md) |
+| Active user and account identity | [`references/arkcli-auth-whoami.md`](references/arkcli-auth-whoami.md) |
+| Control-plane versus data-plane credential recovery | [`references/auth-modes.md`](references/auth-modes.md) |
+| Resolving a request for resources owned by the current identity | [`references/identity-resolution.md`](references/identity-resolution.md) |
+| Account-opening and payment verification before billable writes | [`references/realname-gate.md`](references/realname-gate.md) |
+| Maintainer regression cases | [`references/evals.md`](references/evals.md) |
+
+## When To Trigger
+
+- first-time BytePlus SSO login;
+- expired or missing control-plane credentials;
+- `who am I`, active account, or active identity questions;
+- ARK API key selection or recovery;
+- an explicit request to log out;
+- a business command that failed because authentication is not ready.
+
+## When NOT To Trigger
+
+Do not use this Skill to decide whether a model, Endpoint, or business feature
+is supported. Route those questions to the matching BytePlus capability Skill.
+Do not run `auth apikey` when the user explicitly asks to inspect the key
+inventory. Before using `arkcli profile apikey list`, explain that it may synchronize
+remote keys and write back the local key inventory or default key;
+masked output does not make the Profile operation side-effect free.
+
+## Execution order
+
+**Pending authorization takes precedence over starting another login.** If this turn or the user supplies a previous `stage=authorize_pending` and the user has neither completed authorization nor returned a code, wait. Do not rerun any `auth login`, `config init`, or the original business command. One read-only `auth status` check is allowed: resume if the required valid credentials already exist; `logged_in=false` alone does not establish that the pending session expired or disappeared, so keep waiting. Restart Phase 1 only after an explicit CLI session-expired/missing error or an explicit user request to restart login.
+
+1. Run `arkcli auth status --format json`.
+2. If `logged_in` is true and the required credential is healthy, resume the
+   original task.
+3. If login is required, tell the user that BytePlus SSO is starting and run
+   `arkcli auth login` with a generous interactive timeout.
+4. After a successful login, immediately resume the original task.
+5. Run `arkcli auth logout` only after the user explicitly asks to clear local
+   credentials.
+
+Use `arkcli auth whoami --format json` when the request depends on the current
+identity. Do not decode token files or read `~/.arkcli-bp/` directly.
+
+## Browser SSO
+
+For a normal interactive terminal:
+
+```bash
+arkcli auth login
+```
+
+The standalone product selects BytePlus SSO at compile time. Do not add a
+tenant selector or a product-specific subcommand.
+
+If browser launch, callback binding, or authorization times out, do not loop.
+Return stderr to the user and offer the no-browser flow.
+
+## No-browser SSO
+
+In automation, a sandbox, a remote host, or another non-interactive
+environment, use the two-phase flow.
+
+Phase 1:
+
+```bash
+arkcli auth login --no-browser
+```
+
+The command returns structured output containing `stage="authorize_pending"`,
+an `authorize_url`, and the next command. Forward the URL unchanged. Ask the
+user to finish authorization in any browser and return the displayed base64
+authorization code.
+
+Phase 2:
+
+```bash
+arkcli auth login --no-browser --code <authorization-code>
+```
+
+Both phases must use the same `HOME` and persistent filesystem because Phase 2
+consumes the pending session created by Phase 1 under `~/.arkcli-bp/`.
+
+Recovery rules:
+
+- missing or expired pending session: rerun Phase 1;
+- malformed code or state mismatch: verify that the code belongs to the most
+  recent authorization URL, then retry Phase 2 within the session TTL;
+- transient token exchange failure: retry Phase 2 only when the command marks
+  the operation retryable;
+- never print or store the authorization code outside the active command.
+
+## API key handling
+
+`arkcli auth apikey` is an interactive selection command and changes the
+active key from the ordinary API-key pool. It does not read or repair a Coding
+Plan Team seat key. Do not run it when the user only wants to list keys, and do
+not interpret `saved=true` as proof that a team-seat key is available.
+
+`arkcli auth apikey create` creates, verifies, and saves one ordinary API key
+for the current identity. A TTY requires confirmation; a non-interactive caller may add `--yes`
+only after the end user explicitly authorizes the write. The command issues
+one `CreateApiKey` request, performs at most three read-only status checks, and
+never prints the raw key. It does not create or repair Coding Plan Team seat
+keys. Use `profile apikey refresh/use` when an existing Profile must switch its
+default key.
+
+- Inspect the current selected key through the masked `ark_api_key` field in
+  `arkcli auth status --format json`.
+- API-key sources are profile-specific: `platform` and personal `coding-plan`
+  profiles use the ordinary API-key pool; `coding-plan-team` uses the key from
+  a Running seat returned by `GetSeatInfo.Result.ApiKey`.
+- During an interactive TTY login, an empty ordinary pool may prompt the user
+  to create one all-resource key. Only explicit confirmation permits one
+  `CreateApiKey` call, followed by at most three read-only status checks. Empty
+  or account-wide project scope falls back to `default`, and the name follows
+  `api-key-YYYYMMDDHHmmss`. Declining or running without a TTY performs no
+  mutation.
+- Use `arkcli profile apikey list` only for an explicit Profile-management
+  request. Before the command, explain that it can query the remote key source,
+  reconcile live keys, write back the local inventory, and select or clear the
+  stored default when membership changes. Masked output does not make it
+  read-only.
+- Never print a complete API key.
+- Do not confuse an ARK API key used by data-plane calls with the SSO/STS
+  credentials used by control-plane calls.
+
+## Logout
+
+Logout is destructive because it clears the local BytePlus identity state.
+Run it only after explicit user intent:
+
+```bash
+arkcli auth logout
+```
+
+After logout, verify status with:
+
+```bash
+arkcli auth status --format json
+```
+
+## Command summary
+
+| Command | Purpose |
+|---|---|
+| `arkcli auth status --format json` | Inspect credential health and effective identity context. |
+| `arkcli auth whoami --format json` | Inspect the active user and account identity. |
+| `arkcli auth login` | Start browser SSO. |
+| `arkcli auth login --no-browser` | Start Phase 1 of cross-device SSO. |
+| `arkcli auth login --no-browser --code <code>` | Complete Phase 2 of cross-device SSO. |
+| `arkcli auth apikey` | Interactively select and persist an ordinary ARK API key; it does not repair team-seat keys. |
+| `arkcli auth apikey create [--yes]` | Create, verify, and save one ordinary API key for the current identity without printing the raw key; it does not repair team-seat keys. |
+| `arkcli auth logout` | Clear local credentials after explicit confirmation. |
+
+## Guard Checklist
+
+- Never reveal complete tokens, access keys, secret keys, API keys, or pending
+  authorization codes.
+- Do not treat an authorization failure as proof that a capability is absent.
+- Do not reuse credentials or local state from another product.
+- Do not stop after login when the user's original task is still incomplete.

package/skills/arkcli-auth/references/arkcli-auth-login.md

@@ -0,0 +1,92 @@
+# `auth login`
+
+Use browser SSO for an interactive workstation:
+
+```bash
+arkcli auth login
+```
+
+The standalone binary already selects BytePlus. Do not append a tenant
+argument or use a command copied from another product.
+
+## Two-phase no-browser flow
+
+Use this flow for agents, sandboxes, CI jobs, remote hosts, and any environment
+without a usable local browser.
+
+### Phase 1
+
+```bash
+arkcli auth login --no-browser
+```
+
+In a non-interactive process, the command creates a short-lived pending SSO
+session under `~/.arkcli-bp/`, emits structured output, and exits without
+waiting on stdin.
+
+Example shape:
+
+```json
+{
+  "stage": "authorize_pending",
+  "method": "sso_no_browser",
+  "authorize_url": "https://signin.byteplus.com/...",
+  "next_command": "arkcli auth login --no-browser --code <authorization-code>",
+  "expires_in_sec": 600
+}
+```
+
+Forward `authorize_url` exactly as returned. Do not decode, normalize, or
+rewrite it. Ask the user to authorize in any browser and return the base64 code
+shown by the page.
+
+### Phase 2
+
+```bash
+arkcli auth login --no-browser --code <authorization-code>
+```
+
+`--code` is valid only together with `--no-browser`. Phase 2 reads the PKCE and
+state values saved by Phase 1, exchanges the code, activates the identity, and
+removes the pending session after success.
+
+Both phases must run with the same `HOME` and persistent filesystem. Do not
+dispatch them to different containers, workers, or home directories.
+
+## Recovery table
+
+| Failure | Recovery |
+|---|---|
+| Pending session missing or expired | Rerun Phase 1 and use the new URL. |
+| Authorization code is not valid base64 | Correct the code and retry Phase 2 while the pending session remains valid. |
+| State mismatch | Use the code produced by the latest URL; rerun Phase 1 if provenance is uncertain. |
+| Retryable token exchange failure | Retry Phase 2 within the pending-session TTL. |
+| Browser launch or callback failure | Switch to the no-browser flow instead of looping browser login. |
+
+Never log the complete authorization code, token response, API key, access key,
+or secret key.
+
+## API-key provisioning after login
+
+Login resolves API keys by profile type. `platform` and personal `coding-plan`
+profiles use the ordinary API-key pool; `coding-plan-team` profiles use the key
+returned by a Running seat through `GetSeatInfo.Result.ApiKey`.
+
+When a real TTY login finds the ordinary pool empty, it asks whether to create
+one all-resource key. Confirmation permits exactly one `CreateApiKey` mutation
+and at most three subsequent status reads; the first Active result ends the
+check. The current concrete project is used, while an empty or account-wide
+scope falls back to `default`; the generated name is
+`api-key-YYYYMMDDHHmmss`. Declining or using a non-interactive process performs
+no mutation.
+
+`arkcli auth apikey` only selects from the ordinary pool. It cannot obtain or
+repair a Coding Plan Team seat key.
+
+For an explicit request to provision an ordinary key, use
+`arkcli auth apikey create`. A TTY asks for confirmation; in a non-interactive
+environment, add `--yes` only after the end user explicitly authorizes the
+write. The command creates at most once, performs no more than three read-only
+status checks, saves the verified key for the current identity, and never
+prints the raw key. Use `profile apikey refresh/use` to change an existing
+Profile's default key.