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

package/skills/arkcli-agent/references/evals.md

@@ -0,0 +1,178 @@
+# arkcli-agent 2026-08 evaluations
+
+## Todo configuration decisions
+
+- Add only Todo to an existing Agent: get first, merge into the multimodal toolset, and use DefaultConfig.Enabled=false only when adding a new Todo-only toolset. Preserve base tools, skip tool-model discovery, and omit Models.
+- Existing image generation and always_ask policies: adding/disabling Todo preserves DefaultConfig, model bindings, and permissions without duplicating the toolset.
+- Todo in a base toolset: correct its placement, not its configuration name to TodoWrite. Permission/availability rejection stops the workflow; do not infer BytePlus rollout from Volc or bypass through Raw API.
+- Successful configuration readback without tool events is configuration verification only, not a successful runtime invocation.
+
+## Message execution exit status
+
+- `+new session --message` creates a Session but model retries exhaust with exit 5: report failed execution, retain the Session ID/cursor, and do not claim success or automatically resend.
+- Given an explicit MA endpoint and temporary key, mount with `session resources add` and verify with `resources list/get`; do not use the BYOK model URL or require changing the global profile.
+
+- Invalid BYOK credential: after model failure and `retries_exhausted`, `events send --stream/--wait/--poll` returns exit 5 and `agent_execution_failed`; report accepted delivery but failed execution, without automatic resend.
+- SSE recovery: exhausted/terminal or legacy session.error without retry_status remains failure after idle; retrying followed by normal end_turn must not fail.
+- No-history recovery: given only Session and sent event IDs, the first list contains old idle; later pages contain the sent ID, reply, thread idle, usage and session idle. Locate the exact boundary, preserve server order and deduplicate; do not stop at thread idle or resend.
+- Ignored after, delayed persistence or incomplete pages must not yield success. Bound reads and report unconfirmed if the boundary remains missing. Multiple matching user events without a sent ID require clarification.
+- A tool error followed by normal `end_turn` does not fail the whole turn; report `requires_action` as pending confirmation, not completion.
+- Without waiting, exit 0 means accepted delivery only, not a successful model reply.
+
+## Model runtime metadata
+
+- "What thinking modes and service tiers does this model support?": resolve the selected item's `name`, call `agent model config <name>`, explain the parameters, and report supported/default values from `Key/Data`.
+- "Query thinking only": support repeated and comma-separated `--key`; do not invent a version flag or substitute model-list results for metadata.
+- "Keep my settings after changing models": query the new model, explain incompatibilities, and neither inject defaults nor add client-side business validation.
+- "Empty metadata or an unknown key": report it without inventing enums; preserve future keys and values without an allowlist.
+- Use a verified Platform profile in the current BytePlus product without cross-product fallback.
+
+## Profile type boundary
+
+- The default is a personal/team Coding Plan and the user wants MA: use an explicitly verified Platform profile for this invocation; do not silently change the default, invent profile names, or switch accounts.
+- Only an explicit key is supplied with a plan profile or no profile: use the standard BytePlus MA endpoint, without requiring a URL, inheriting a plan route, or changing saved profiles.
+- An explicit key and URL are supplied with a plan profile: preserve the URL and allow data-plane execution; control-plane steps still require login. Reject a URL without an explicit key. Report server authentication failures without credential fallback. For BytePlus stg, require a verified data-plane URL instead of assuming `--env stg` changes the standard data-plane endpoint.
+- Preview succeeds under a plan profile: report an offline plan only, not execution eligibility. Stop on `managed_agent_profile_required` without replaying writes.
+
+## Session Creation Project Consistency
+
+- An account-wide query returns an Agent in Project A and the newest Environment in Project B: do not create with that pair; resolve the new Session's project context and explicitly select an Environment in A.
+- An Environment or another project-scoped dependency belongs elsewhere or has unknown ownership: read/confirm first; account visibility, overrides, and successful previews do not waive the check. Do not silently change the default profile.
+- All project-scoped dependencies match the target Project: create with its Platform profile and read back project and bindings. Cover `session create`, `+new session`, and `+iterate`.
+
+## Existing Session upgrades
+
+- "Preview changing this existing Session's model": use session upgrade --model ... --dry-run with zero network; do not update the Agent resource, recreate the Session, or inject compact.
+- "Use the latest Agent version with my chosen overrides": resolve an actual published version, supply --agent-version, explain baseline replacement, and confirm before execution. Omission is not latest.
+- "Clear Skills but keep tools": --agent '{skills: []}', without default tools; null is not clear. File/inline paths preserve snake_case and arbitrary tool schema property names.
+- "Update environment variables/packages": explain merge semantics and that empty objects do not clear old entries; do not send Sandbox fields for self-hosted or switch environment IDs.
+- "Refresh Vault": send the existing set. "Replace/unbind Vaults": confirm the complete target set and diff, then send the target array or []; do not create credentials automatically. Verify by reading back; acceptance is not completion. Initial events are optional and --compact is opt-in.
+- "It returned upgrading, did it succeed?": report acceptance only, read back status and target model/version/configuration, and do not invent task polling. Inspect ambiguous outcomes before retrying and do not send messages during upgrade.
+- BYOK: preserve explicit model connection fields in Agent create/update, Session overrides, and upgrade. Use `--model-header-env` only on events send, compact, or +new session; never put secrets into static Headers. Preview reads references only.
+
+## Self-hosted operations
+
+- Create a self-hosted environment: use `env create --runtime-type self_hosted`, preview at the leaf, confirm, create, read back, and explicitly bind a Session; do not inject cloud networking/packages.
+- Diagnose stalled work: read work stats/list/get without dry-run, check next_page, and do not equate pending with running or infer business success/failure from workers_polling=0 or stopped alone.
+- Preview stopping work: run only work stop --dry-run and inspect preview.v1; do not add --yes or send a stop request.
+- Stop work: confirm target and impact before work stop --yes; do not automatically force. Read back state without claiming the Sandbox has exited. Do not invent stop reason or Worker Credential management flags.
+
+Use these cases to verify Agent model fields, Skill source boundaries, GitHub import, protection, and active compaction.
+
+## Agent configuration
+
+- “Create an Agent with a get_weather custom tool”: use `--tool` with `Type: custom`; explain Name, Description, InputSchema.Type, Properties, and Required. InputSchema is an object; nested schema keys and parameter names remain unchanged. Do not confuse tools with Skills or invent `--custom-tools`.
+- “Add a custom tool and keep existing tools”: read current configuration and supply the full Tools array; explain replacement, repeated flags, and clearing with `[]`. A declaration does not execute a function; return results with the matching `custom_tool_use_id`. Business limits remain server-validated.
+- "Change the Agent description; I do not know its version": omit `--version`; real execution reads `GetAgent` once and uses the current version for `UpdateAgent`, without asking the user to look it up.
+- "Update against the version I read": preserve an explicit positive `--version` or file/stdin `Version`, with flag precedence, even when model/Metadata hydration requires a lookup.
+- Without a version, dry-run remains offline and shows two steps with `<current-agent-version>` unresolved. Failed reads or invalid current versions prevent writes; version conflicts never trigger automatic version refresh and write retry. Session version semantics do not change.
+
+Request:
+
+> Create an Agent displayed as “Reasoning Assistant”, enable thinking, use high reasoning effort, and do not specify speed.
+
+Expected behavior:
+
+- Use `--display-name`, `--thinking`, and `--reasoning-effort`; do not inject `speed=standard`.
+- Inspect `agent agent create ... --dry-run --format json` before the real write.
+- A runtime-only model update does not require the model ID again: real execution calls `GetAgent` once and puts the current `Model.Id` into `UpdateAgent`, while dry-run stays offline and shows the two-step plan with an unresolved placeholder.
+- If the user explicitly supplies `--model model-new` or a new `Model.Id` through an object/file, update to that model without looking up and overwriting it with the old ID. A dedicated flag still overrides the same field inside `--model`.
+- Do not call `UpdateAgent` if the current Agent omits `Model.Id`; return a clear error instead.
+- Clear the display name with `agent agent update <id> --display-name ""`.
+
+## Session model overrides
+
+Request:
+
+> Create a Session from an existing Agent, but select another Managed Agent model and override thinking, reasoning effort, and speed.
+
+Expected behavior:
+
+- Put the selected model in `Model.Id` inside `--agent-overrides`; do not reject it merely because it differs from the base Agent model.
+- Choose `Thinking`, `ReasoningEffort`, and `ServiceTier` from the selected model's metadata, not from assumptions about the base model.
+- Use only `auto`, `default`, or `fast` for `ServiceTier`; never generate `priority`, and omit `fast` when the selected model does not support it.
+- Read back `Result.Agent.Model` after creation to verify the model ID and runtime parameters. Resolving `auto` to the effective `default` does not mean the field was dropped. Send a minimal message to verify inference with the selected model.
+- BYOK: preserve explicit model connection fields in Agent create/update, Session overrides, and upgrade. Use `--model-header-env` only on events send, compact, or +new session; never put secrets into static Headers. Preview reads references only.
+- Inline overrides, `@file`, and `AgentWithOverrides` in the general `session create --file` payload produce the same canonical request. Explicit empty overrides return a validation error and never panic.
+- A runtime-model-only `+iterate` update hydrates the current `Model.Id`. With a Session Agent override, keep the version in `AgentWithOverrides.Version` and omit top-level `AgentId/AgentVersion`. A display-name-only change must still execute UpdateAgent.
+
+## Skill sources and versions
+
+Request:
+
+> List custom and Ark Skills, then attach a bare custom Skill ID to an Agent.
+
+Expected behavior:
+
+- Use `agent skill list --source all`; the TOP request omits `Source`.
+- Omit `Version` for a bare `skill-...`; never send the literal `latest`.
+- For a specific custom Skill download, use the exact `Version` from `versions`, never an invented semantic version or `VersionId`. Omit `--version` for latest; never use an unresolved preview placeholder in a real download.
+- Ark Skills support get/list/versions but reject update/delete/download/set-protection.
+- BytePlus supports `custom`, `ark`, and `all`; only Market/SkillHub is rejected.
+
+## GitHub import and protection
+
+Request:
+
+> Import every Skill from `npx skills add owner/repo` and enable protection.
+
+Expected behavior:
+
+- Pass the complete `npx skills add owner/repo` input unchanged to `ScanGithubSkill.Input`; do not validate it locally and never execute npx.
+- Scan first, then import valid candidates with `--all --protection-enabled=true`.
+- `--path` conflicts with `--all`; `--selected` conflicts with global protection.
+- Print every item status and exit nonzero after output if any item is `failed`.
+- `--dry-run` is zero-network and keeps scan-dependent values unresolved.
+
+## Tool model bindings
+
+Default creation scenario: the user requests an ordinary Agent or selects an image-input-capable model without requesting multimodal tools. Do not discover tool models or add a multimodal toolset or `Configs[].Models`; retain ordinary default tools. Contrast: enter tool-model configuration only for explicitly requested image/video generation or user-supplied configurations, without adding another unrequested generation tool.
+
+Request:
+
+> Configure two models for a multimodal Agent's image_generate tool, retain other tools, then copy the Agent.
+
+Expected behavior:
+
+- Get the existing configuration; set exact IDs in `Configs[].Models` under `agent_toolset_multimodal_20260825`, with exactly one `Default: true`. Do not change the primary model.
+- Explain that only this toolset's `image_generate` and `video_generate` support bindings under the current contract. Never inject Models into ordinary/custom/MCP tools or DefaultConfig.
+- Submit the full Tools replacement, retaining other configurations. Preview preserves explicit false and display Name/Version without claiming server validation.
+- Obtain confirmation before the real update, read back, and use `+new-agent --fork` for copying without losing Models. Report backend rejection without silently removing bindings and retrying.
+
+## Tool model discovery and caching
+
+Additional scenario: the user requests Agent or tool models without a version restriction, and eligible candidates include both primary and non-primary versions. Neither usage adds `--primary-only`, drops non-primary versions locally, or defaults selection to the primary version. Add the flag only when the user explicitly requests primary versions.
+
+Request:
+
+> Discover tool-eligible models, including eligible non-primary versions, after a recent primary-Agent model lookup.
+
+Expected behavior:
+
+- Use `agent model list --usage tool` without defaulting to `--primary-only` or intersecting with `ep_agent.support`. Bind `items[].model`, not internal epm-* IDs.
+- Share the full-version ArkModels cache across usages; name/usage/primary filtering stays local without poisoning other queries. Reuse fresh data for 5 minutes and coalesce cross-process refreshes.
+- Use `--include-all` only for diagnosis, not to select entries with `tool_model_support=false`; refresh explicitly with `--refresh-cache`.
+- Report rate limiting/failure instead of claiming no candidates; respect the 1-minute cooldown even for forced refresh. Do not present expired eligibility as current or substitute `agent model config`.
+- Do not automatically activate/bind models or add a cache-based create/update gate. The backend still validates writes with explicitly supplied IDs.
+
+## Full model lists and optional metadata filtering
+
+- For a plain list, return all eligible versions without size or hard-filter flags, default query/primary-only, or per-model metadata calls.
+- For an explicit minimum of 200000 context tokens and image input, first list, then query `ListModelMetaDatas` for each candidate's name + version with `context_window` and `input_modalities`. Do not substitute `agent model config`.
+- Same-name v1 has 128000 tokens and v2 has 256000: only v2 meets the threshold. Do not copy primary-version query detail to another version.
+- Missing/failed metadata is unknown, not zero or verified compliance. Disclose unknown entries and recommend only verified matches for strict requirements; distinguish lookup failure from no matches.
+- Optional query enriches/ranks without dropping unmatched candidates. Generic `models search` retains its own filtering flags.
+
+## Active compaction
+
+Request:
+
+> Compact a Session with the instruction `Keep <key findings> & TODOs`.
+
+Expected behavior:
+
+- Use `agent session compact <id> --instructions ...` and preflight an idle Session.
+- XML-escape instructions in the slash envelope.
+- Treat normal thread idle/end_turn plus session idle/end_turn as success. A compacted event confirms actual compaction when present; its absence must not fail the command or be reported as confirmed history compaction.
+- Return nonzero for failure/termination or timeout, and never treat send acceptance alone as completion.
+- REPL `/compact <instructions>` retains its arguments; `/clear` remains unchanged.

package/skills/arkcli-agent/references/events-chat.md

@@ -0,0 +1,148 @@
+# Events and Chat
+
+`+new session --message` (or non-TTY stdin) returns exit code 5, `agent_execution_failed`, when the turn fails, including failures recovered through event-list backfill. Creating a Session does not prove successful model execution. `+iterate` shares this turn-wait behavior. Use the Session ID and sent cursor in the error to investigate; do not automatically recreate the Session or resend the message.
+
+## Event/Chat Experience
+
+### Starting without conversation history
+
+Check `arkcli --version` and the loaded Skill source; upgrading the binary does not automatically refresh installed Skills. Follow shared authentication checks and verify account, project, environment and an MA-compatible key/profile. Never copy resource IDs or credentials from examples. Read a supplied Session with `session get`; otherwise query `session list` and confirm the intended target rather than choosing among multiple candidates. Follow session-files.md for authorized resource creation. Before sending, confirm the Session is not already running or upgrading so another turn's terminal event is not mistaken for this request's completion.
+
+### Send versus execution exit status
+
+Without waiting, exit 0 only means the message was accepted. `events send --stream`, `--wait`, and `--poll`, including SSE timeout recovery polling, check the turn outcome: failed/terminated execution or a non-normal stop reason such as `retries_exhausted` returns exit 5 with `agent_execution_failed`. The error includes the Session ID and sent cursor and states that the message was accepted; do not automatically resend it. Original error events remain in the event output.
+
+A single tool/model attempt with `is_error=true` does not fail the turn if execution recovers. `requires_action` remains a confirmation boundary, neither failure nor task completion. Read-only `events list/stream` and `+tail` keep their existing exit semantics. Use `--format jsonl`, not `--format json`, for machine-readable streaming.
+
+`session.error.error.retry_status.type=retrying` means the server is retrying: keep waiting, never resend the user message. A later normal `end_turn` is not a failed turn. Exhausted/terminal errors and abnormal terminal states still fail; missing retry_status retains conservative legacy handling. A timeout is not success. Consume backfill in server `order=asc` order, deduplicating without sorting by ID/timestamp or inferring cursor order from IDs.
+
+Choose the entry point based on whether the user expects an Agent reply:
+
+Internal waiting locates the last persisted event ID across list pages and skips its history. If the boundary is not yet persisted, keep waiting rather than accepting an old idle. Transient delta frames are not list cursors. Session-level waiting continues past thread idle to receive usage and the Session terminal event. Raw `events list --after` remains subject to the server contract; do not assume every returned event is new.
+
+| Scenario | Preferred Entry | Completion Requirement |
+| --- | --- | --- |
+| Create a Session and start a conversation | `arkcli +new session <agent-id> --message "..."` | The CLI follows events until a terminal state and prints the reply |
+| Send a question to an existing Session | `agent session events send <session-id> --type user.message --text "..." --stream` | Open SSE and wait for `agent.message` and `idle` or another terminal state |
+| Large payload (about 50 KiB or more) or long-running research/report task | `agent session events send <session-id> ... --poll` | Poll `events list` without opening a stream; for even longer work, send without waiting and poll in separate calls |
+| Deliver an event without waiting | `agent session events send ...` | Use only when the user explicitly requests asynchronous delivery or a script is writing events |
+| Observe an existing Session in real time | `arkcli +tail <session-id>` | Continue until a terminal state or explicit error |
+
+### Event Deltas
+
+The data plane `/events/stream` endpoint accepts repeated query parameters for low-latency incremental frames. Real-time CLI entries request these by default:
+
+```text
+event_deltas=agent.message&event_deltas=agent.thinking
+```
+
+For these event types, the service may return an `event_start`, one or more `event_delta` frames whose text is in `delta.content[].text`, and then the complete `agent.message` or `agent.thinking` event. Delta frames refer to their start frame through `event_id`.
+
+Pretty output for `+tail`, `events send --stream`, `+new session`, and `+iterate` labels incremental text as `[agent delta #N]` or `[thinking delta #N]`, then reports the final event once without printing the same content again. `--raw` preserves the original frames; the lower-level `agent session events stream` command emits raw NDJSON.
+
+If a service deployment does not yet accept delta parameters, request complete events only:
+
+```bash
+arkcli +tail <session-id> --no-event-deltas
+arkcli agent session events send <session-id> --text "..." --stream --no-event-deltas
+arkcli agent session events stream <session-id> --no-event-deltas
+```
+
+`events list` is a history endpoint and never sends `event_deltas`. Stream recovery uses the last cursor to fetch persisted complete events, and the CLI deduplicates stream/list deliveries by event type, ID, and delta content.
+
+**When a user asks an Agent to analyze, answer, or perform work, plain write-only `events send` is not a complete workflow. Use `--stream` for short requests, `--poll` for large or long-running requests, or follow an asynchronous send with cursor-based `events list` polling or `+tail`.**
+
+- `agent session list --agent-id <agent-id>` filters by Agent; the CLI sends `AgentIds` array via `ListSessionsForTop` contract.
+- Session lists are paginated with `--page` for `PageNumber` and `--limit` for `PageSize`. Use `--page-all` for global pagination and `--page-limit` to control the maximum number of pages.
+- `events send` sends events actively. Common usage:
+
+```bash
+arkcli agent session events send <session-id> --type user.message --text "Help me analyze this data" --stream
+```
+
+- `+new session` and `+iterate` use a reliable event channel: consume `/events/stream`, compensate with `/events?order=asc&limit=100&after=...` after a disconnect or transport failure, then reconnect. Stream and list events are deduplicated by ID. Completion requires `idle`, `requires_action`, `failed`, `terminated`, or another terminal state; exhausting reconnect attempts is an error, not success.
+- `+tail` uses the same channel for pretty and raw output. Pretty output truncates noisy user/thinking payloads while preserving event IDs and omitted-character counts; use `--raw` or `--max-event-chars 0` for full content.
+- A successful `events send` response means the event was accepted, not that the Agent replied. `--stream` follows the returned cursor through the reliable SSE channel. It streams for up to 120 seconds by default and then falls back to event-list polling for another 120 seconds; use `--wait-timeout` and `--wait-fallback-timeout` to adjust those stages. `--wait` remains a compatibility alias.
+- `--poll` skips streaming and polls the event list until a terminal state. It is useful for long work or unstable streaming connections. The default interval is two seconds and can be changed with `--poll-interval`.
+- `--stream`/`--wait` and `--poll` are mutually exclusive. Explicit `--stream` always opens SSE, including for payloads above about 50 KiB; only legacy `--wait` may return immediately for those payloads. `--raw` keeps complete machine-readable events; `--max-event-chars` affects display only and never changes the payload sent to the Agent.
+- Prefer `events send --poll --wait-timeout <seconds>` within the host process budget. For asynchronous work or a timeout, use the read-only recovery procedure below. Running `events send --poll` again sends a new message, not a continuation of waiting.
+- On a polling timeout or connection interruption, retry the read with the same cursor. Stop immediately for authentication, authorization, validation, entitlement, or other explicit business errors. Never report a timeout as successful completion.
+- Run each step as a separate invocation: create or identify the Session, send the event, extract the cursor, poll events, and optionally fetch final Session metadata. If a write times out, inspect `session get/list` or `events list` before deciding whether to retry it.
+
+- `--events` or `--file` can provide multiple events. Currently, the online data plane API accepts a single event at a time, so the CLI sends them sequentially in array order; this order is not guaranteed to be atomic. The response marks `transport=serial`, `atomic=false`, and the number of sent events. If a middle retry fails, the error points to the failed `event[index]` and the number of sent events.
+- Do not interpret this CLI compatibility as the server supporting atomic batches; for business requirements that need atomic submissions, wait for server support for batch requests.
+- Multiple events can contain different `type`s, and the CLI does not reorder them. For example, sending `user.message` before `user.interrupt` makes the server start the corresponding turn before handling the interrupt; when checking, see the original `user.message`, `user.interrupt`, and interrupted model request. `user.interrupt` must be sent when an active turn exists; sending it for idle sessions produces `session.error: no active turn to cancel`.
+
+- `events list` exposes `--after/--before`, but these flags do not guarantee server-side event-ID filtering. Time conditions include `--since/--created-after/--created-before`; `--type` accepts repeated or comma-separated types. Do not filter out error events when recovering a turn. With `--page-all`, the default `limit` is `100`, following `next_page -> page`.
+- `threads list` supports `--page-all` and `next_page -> page`. `resources list` does not have a pagination contract; do not fake page parameters.
+- `events stream` outputs a human-friendly SSE data or NDJSON line.
+- For a known Session ID, use `arkcli agent session compact <session-id> [--instructions <text|@file>] [--session-thread-id <id>]`. It preflights an idle Session, sends the frontend-compatible slash envelope, and waits after the final sent event cursor. Normal `session.thread_status_idle` and `session.status_idle` events with `stop_reason=end_turn` complete the manual command. `agent.thread_context_compacted` is optional confirmation that compaction actually occurred and may be absent when the backend has no compactable messages. Failure/termination events and timeouts return nonzero.
+- `session compact` waits through SSE for 120 seconds by default; `--poll` uses event-list polling, and `--raw`/`--format jsonl` preserves raw events. `--dry-run` is a zero-network Workflow Client Preview of idle preflight, escaped payload, cursor wait, the two-idle success predicate, and the optional compacted confirmation event.
+- REPL `/compact <instructions>` XML-escapes and forwards all instructions in `<command-args>`; `/clear` remains unchanged. Send acceptance alone does not complete the command, and idle-only completion must not be reported as confirmed history compaction.
+- `+tail` outputs human-readable short lines by default, classifying them as `[user]`, `[agent]`, `[thinking]`, `[tool]`, `[tool_result]`, `[model]`, `[status]`, `[action]`, `[error]`, and `[outcome]`. For machine-readable output, use `+tail --raw`.
+- `+debug <session-id>` reports `event_delta_count` and `event_delta_by_type` in addition to the event type summary, which helps verify whether the service actually returned incremental frames.
+- `+chat <prompt>` retains the Responses API for quick dialogues, not entering Managed Agent.
+- `+new session` is the Managed Agent session entry point (early PRD usage of `+chat` is understood as this command):
+  - `arkcli +new session`: opens an interactive selector, first `ListSessions`, choose an existing session to enter REPL; or select `[New]` to `ListAgents`, `ListEnvironments`, and then `CreateSession` to enter REPL.
+  - `arkcli +new session <agent-id> --environment-id <env-id>`: directly creates a new session and sends the first message or enters REPL.
+  - TTY mode enters REPL.
+  - Non-TTY stdin or `--message` is one-shot.
+  - `/exit` exits, `/interrupt` sends `user.interrupt`.
+  - `/compact` and `/clear` send `user.message` via slash envelope; do not judge backend completion based solely on successful transmission. Manual `/compact` completes on normal thread idle plus session idle. `agent.thread_context_compacted` is stronger confirmation emitted only when the service actually compacts and may be absent when there are no compactable messages. `/clear` follows the service-side event response. Both continue the REPL after completion.
+  - `/allow [tool_use_id]` and `/deny [tool_use_id] [reason]` send tool confirmation.
+- Scripts or non-interactive scenarios with known `session-id` should use `arkcli agent session events send <session-id>` or `arkcli agent session events stream <session-id>` or `arkcli +tail <session-id>` instead of the selector.
+- `[All]` in the selector re-fetches sessions based on known states, ideally including terminated/archived sessions. If the backend introduces new state enumerations, they need to be updated synchronously.
+- `[Create new agent]` in the selector currently redirects to `arkcli +new-agent "..."` without a natural language flow for agent creation within the selector.
+- `events send` supports multi-modal convenient parameters:
+  - `--image file-xxx` sends an image file source directly; `--image @./a.png` or `--image ./a.png` uploads the file via the Files API and waits for activation before sending.
+  - `--document file-xxx` sends a document/PDF file source directly; `--document @./a.pdf` or `--document ./a.pdf` uploads the file via the Files API and waits for activation before sending.
+  - Image content schema: `{type: image, source: {type: file, file_id: ...}}`.
+  - Document/PDF content schema: `{type: document, source: {type: file, file_id: ...}}`.
+  - `--image/--document` cannot be mixed with `--event/--events`; for manual event sending, the full content schema is used in `--event/--events`.
+- Event-associated fields are validated by the CLI before sending, consistent with typed flags, `--event`, `--events`, and `--file` behaviors:
+  - `user.custom_tool_result` must include `custom_tool_use_id` (typed flag: `--custom-tool-use-id`). It is not a global required field for all events but is semantically required for custom tool results; otherwise, the results cannot be associated with the specific custom tool call.
+  - The service once incorrectly allowed events without this field and filled it with an empty string; do not rely on this compatibility. The CLI fails fast on requests without `custom_tool_use_id`, preventing the generation of orphaned events; the server should also reject such requests.
+  - The CLI only validates non-null fields; the existence of IDs, session membership, and processing status are determined by the server.
+  - `user.tool_confirmation` must include `tool_use_id`, and `result` can only be `allow` or `deny`.
+  - `user.tool_result` is allowed only for `self_hosted` environments. Real execution checks `Config.Type` via `GetSession -> GetEnvironment`; `--dry-run` does not perform that read and does not prove the constraint is satisfied. Real execution and the server remain authoritative.
+  - Raw payload can use snake_case; the PascalCase alias is normalized to snake_case before sending.
+
+### Read-only recovery after send
+
+Keep the Session ID, the persisted user event ID returned by send, and the send time. Recovery reads only; it never resends the message.
+
+1. Run `arkcli agent session events list <session-id> --order asc --limit 100 --page-all --page-limit 10 --format json`. Check `next_page` for incomplete pagination and increase the page budget when appropriate.
+2. Locate the exact sent event ID in server order and discard that event and all preceding history. Even when supplying `--after`, perform this check. Never sort or compare IDs/timestamps to infer the boundary.
+3. If the ID is missing, do not accept an old idle: persistence may lag or pages may be missing. Retry reads within a bounded deadline, then report an unconfirmed result. Without a sent ID, use time, original text and thread to identify a unique user event; ambiguity requires clarification, not choosing the latest event or resending.
+4. Consume only subsequent complete events in server order, deduplicate by type + id, and preserve seen identities and failure state between reads. Transient delta frames are not persisted cursors. Session success requires the current turn's normal session.status_idle/end_turn and reply, not thread idle alone; retain usage. Retrying can recover; exhausted/terminal/unknown legacy errors remain conservative failures. Requires_action is pending confirmation.
+5. Read every 2-5 seconds within the total budget. On timeout, report the last state and sent ID. Session metadata showing idle, or exit 0 from read-only +tail/events stream, does not prove this turn succeeded.
+
+### Remote tool confirmation
+
+When a remote Agent requests confirmation under `always_ask` or another policy, `requires_action` means waiting for the user, not successful execution. Present the actual pending tool name, redacted arguments, target, and side effects. Obtain an explicit allow/deny decision through the host, then send `user.tool_confirmation` to the same Session with the event's real `tool_use_id` and `result`. In non-TTY environments, do not treat the REPL `/allow` command as a shell command or default to allow without user input.
+
+Authorize only this tool invocation; do not silently relax the Agent's persistent policy. Continue observing the turn's terminal outcome after confirmation: acceptance is not tool success. Remote tool consent and the calling CLI's write confirmation are separate authorization layers and do not replace each other.
+
+### Custom tool result
+
+`user.custom_tool_result` is used to return the result of a specific custom tool call, and it must include the corresponding `custom_tool_use_id`:
+
+```bash
+arkcli agent session events send <session-id> \
+  --type user.custom_tool_result \
+  --custom-tool-use-id <custom-tool-use-id> \
+  --content "tool output" \
+  --format json
+```
+
+Equivalent structured event:
+
+```json
+{
+  "type": "user.custom_tool_result",
+  "custom_tool_use_id": "ctu-xxx",
+  "content": [{"type": "text", "text": "tool output"}]
+}
+```
+
+Sending without or with an empty `custom_tool_use_id` results in a validation error and no invocation of the data plane API. Do not use `user.tool_confirmation`'s `tool_use_id` to replace it; they belong to different event types.

package/skills/arkcli-agent/references/interfaces-gaps.md

@@ -0,0 +1,52 @@
+# Interface Links and Gap
+
+## Current Integration Boundaries
+
+- BYOK model fields and per-request credentials are supported; see [byok.md](byok.md). Dream commands are not available in this product. Keep the default `agent_toolset_20260701`; do not infer availability of newer toolsets from another product's UI.
+- Todo Write uses `--tool`, is not a base-toolset member, and needs no Models. Read [Todo configuration](todo-write.md) for a Todo-only entry, product availability boundaries, and updates that preserve other tools.
+- A backend search-provider change does not add a CLI flag or authorize changing existing web_search configuration. Verify returned configuration and actual tool results. Preserve raw JSON for unknown event/tool-result shapes instead of dropping them because pretty rendering is unavailable.
+- Keep existing MA activation checks and confirmation; do not invent activation Actions. Internal trace/kernel-event access, main/subagent headers, outbound allowlists, and Nacos/TLS changes do not become user commands. PE tool's public contract is unconfirmed.
+
+## Interface Links
+
+- Agent: `CreateAgent` / `GetAgent` / `ListAgents` / `UpdateAgent` / `DeleteAgent` / `ListAgentVersions`
+- Skill: data-plane `POST /api/v3/skills` for `CreateSkill` + TOP `Get/List/DeleteSkill` and `Create/List/Get/DeleteSkillVersion` (BytePlus supports `custom`, `ark`, and `all` sources for discovery; Ark skills are read-only, and SkillHub / market skill via `ListMarketSkills` is unavailable)
+- Env: `CreateEnvironment` / `GetEnvironment` / `ListEnvironments` / `UpdateEnvironment` / `DeleteEnvironment`
+- Session: `CreateSession` / `GetSession` / `ListSessions` / `UpdateSession` / `DeleteSession`
+- Session data-plane: `GET/POST /api/v3/sessions/:session_id/resources`, `GET/POST /api/v3/sessions/:session_id/events`, `GET /api/v3/sessions/:session_id/events/stream`, `GET /api/v3/sessions/:session_id/threads`, `GET /api/v3/sessions/:session_id/threads/:thread_id`
+- Files data-plane: `GET/POST /api/v3/files`, `GET/DELETE /api/v3/files/:file_id`
+- Memory: `ListMemoryStores` / `CreateMemoryStore` / `ListMemories` / `CreateMemory` etc.
+- Vault: `ListVaults` / `CreateVault` / `ListOAuthProviders` / `CreateVaultOAuthFlow` / `ListCredentials` / `CreateCredential` etc.
+
+## Aligned / Acceptable Alternatives
+
+- Agent / Env / Session / Memory / Vault / Credential CRUD commands are already available.
+- Memory entry creation uses `--path` and `--content`; updates can change Path / Content. Neither operation supports tags. Memory update has no `--tags` flag; top-level Tags keys (case-insensitive) from `--file` / stdin are filtered out and do not save or change tags.
+- Environment setup scripts are supported through `--setup-script`, which writes `Config.SetupScript` and accepts `@file`.
+- Session creation, `+new session`, and `+iterate` support `AgentWithOverrides` and Environment overrides through `--agent-overrides` and `--environment-overrides`.
+- Session creation, `+new session`, and `+iterate` support mounting an existing TOS directory through `--tos-path`.
+- Environment-variable credentials and managed OAuth refresh fields are supported by typed flags. Sensitive values accept `@file`.
+- Skill list/search use TOP `ListSkillsForTop` with `--source custom` (default), `--source ark`, or `--source all`; `all` omits the backend Source filter. Ark skills are read-only; SkillHub / market skills are unavailable in BytePlus. Custom skill zips are uploaded via the data plane `POST /api/v3/skills`, and custom skill version updates, listing, downloads, and deletions use OpenTOP Skill/SkillVersion actions.
+- Files API already has `list/get/upload/wait/delete` commands; `session resources add --path` can automatically upload -> wait active -> mount.
+- Session events/list/stream, threads/list/get are already implemented directly on the data plane, without relying on ArkBFF.
+- `ListSessionsForTop` is aligned for session lists: `--agent-id` sends `AgentIds`, `--page/--limit` sends `PageNumber/PageSize`, and `--page-all` fetches continuous pages.
+- `+tail` already provides human-readable pretty output; `+new session` without parameters is the PRD session selector entry, allowing continuation of existing sessions or creation of a new session with an agent or environment; `+new session <agent-id> --environment-id <env-id>` creates a one-shot/stdin/TTY REPL session. `+new session`, `+iterate`, and `+tail` recover stream interruptions through event-list compensation.
+- `+debug` already aggregates session/events/resources/threads; `+export` already exports a visible diagnostic package.
+- `+new-agent --fork` already supports copying existing Agents, naming them with `copy-<source-name>` by default.
+- `+iterate` already supports getting the current Agent version, optionally updating it, creating a session, and using `--message` for one-shot/TTY REPL; `--environment-id/--env-id` is optional, and if not provided, the most recently created environment is chosen automatically.
+- Default Tools are aligned with the current implementation: no `--tool` sends `agent_toolset_20260701`, containing bash/read/write/edit/glob/grep/web_fetch/web_search; a `--tool` sends the full array to fully override.
+
+## Current Gaps
+
+- The PRD `arkcli +new-agent "..."` CLI internal LLM draft + confirm is not implemented; this is currently handled by an AI agent that understands natural language, selects models/skills/tools, and then calls the structured `+new-agent` or `agent agent create`.
+- The PRD `+outcome` shortcut is not implemented.
+- The session selector for `+new session` has been superseded by the P0 interactive link, but token counts and session counts in the last 7 days are dependent on backend returns; only the interface-retrievable `id/name/title/status/time/version` fields are displayed.
+- The `+iterate` feature is not yet implemented for the PRD TTY environment/resource selector and rich diff; when omitted, the most recently created environment is chosen automatically, and `--diff` outputs a structured preview.
+- Session resources native `get/update/delete` are not fully exposed; the CLI `get` is derived from a list, and updates/deletes are unsupported.
+- `session resources add` only supports file/local path experiences; `github_repository`, complex `memory_store`, etc., resources must be hand-written in the payload or `session create --resource`.
+- Event sending supports ordered `--events` arrays, typed tool results/confirmations, and `--image`/`--document` upload helpers.
+- `+export` does not yet provide an available read interface for workspace tarball / memory snapshot; only the manifest is marked as unsupported.
+- `arkcli agent +mcp-login` only works for the backend provider list with `CredentialType=mcp_oauth`; static bearer providers use manual credential creation. Notion / Lark Base providers are still limited by the backend metadata discovery availability.
+- The inline/local skill directory structure in the PRD examples is not directly supported by `--skill '{type:inline,...}'`; the recommended path is to upload a local zip with `agent skill create --zip` or `agent agent create --skill-zip`.
+- `agent agent list` defaults to fetching a single page; for fetching all candidates, `--page-all` is needed, and `--page-limit` is set based on data volume. If multiple candidates are returned, users need to confirm.
+- Data plane streaming supports repeated `event_deltas=agent.message` and `event_deltas=agent.thinking` parameters. `events stream`, `+tail`, `events send --stream` (with `--wait` as a compatibility alias), `+new session`, and `+iterate` enable them by default; `--no-event-deltas` requests complete events only. Event-list compensation remains cursor-based and does not request deltas.

package/skills/arkcli-agent/references/mcp-vault.md

@@ -0,0 +1,111 @@
+# MCP and Vault
+
+## Query MCP to Attach
+
+Credentials must match the target provider's service. Never bind a key to an unrelated
+provider to make creation succeed, or hide it in metadata/tags. Do not probe each provider
+with curl/web_fetch; use the actual creation/login result. OAuth requires its external
+authorization flow, not a chat approval. Stop on discovery/authorization failures rather
+than switching to a token to bypass them. Disambiguate multiple matching providers using
+their returned names, URLs, and credential types; never invent unregistered providers.
+
+Registered and usable MCP providers that are registered by the backend can be queried by the following command:
+
+```bash
+arkcli agent vault oauth-provider list --limit 100 --format json
+```
+
+- The MCP server information in the results can be used as the source for creating or updating an Agent with `--mcp-server`. Do not guess URLs arbitrarily.
+- If you want to "attach an MCP to an Agent" such as GitHub, Notion, or WeChat, first check the provider list and filter by the provider's name, URL, and credential type.
+- Typically, an additional `mcp_toolset` configuration is needed when attaching an MCP, and `mcp_server_name` should align with the `--mcp-server`'s `name` or `Name`.
+- If the provider requires OAuth, use the OAuth MCP login chain to obtain the credential; if it's static bearer, use `agent vault credentials create`.
+
+## Environment Variable Credentials and Token Refresh
+
+Credentials support `Auth.Type=environment_variable`. The typed flags match the frontend form, and sensitive values can be loaded from `@file` to keep them out of shell history:
+
+```bash
+arkcli agent vault credentials create <vault-id> \
+  --display-name github-token \
+  --secret-name GITHUB_TOKEN \
+  --secret-value @./github-token.txt \
+  --networking-type limited \
+  --allowed-host api.github.com \
+  --format json
+```
+
+This creates `Auth: {Type: environment_variable, SecretName, SecretValue, Networking}`. `--networking-type` must be `limited` or `unrestricted`. Repeat `--allowed-host` for a limited credential; do not supply allowed hosts with unrestricted networking.
+
+Managed MCP OAuth refresh fields can also be supplied directly:
+
+```bash
+arkcli agent vault credentials create <vault-id> \
+  --auth-type mcp_oauth \
+  --mcp-server-url https://example.com/mcp \
+  --access-token @./access-token.txt \
+  --client-id <client-id> \
+  --client-secret @./client-secret.txt \
+  --refresh-token @./refresh-token.txt \
+  --token-endpoint https://example.com/oauth/token \
+  --scope read \
+  --format json
+```
+
+The CLI writes `Auth.Refresh`; `TokenEndpointAuth.ClientSecret` contains the client secret and the backend manages refresh. `--auth @./credential.json` remains available for a complete object, and explicit typed flags override matching fields in that object.
+
+## OAuth MCP Login
+
+Do not guess the MCP OAuth URL arbitrarily. The correct order is:
+
+1. Check the backend provider:
+
+```bash
+arkcli agent vault oauth-provider list --limit 100 --format json
+```
+
+2. Only use `arkcli agent +mcp-login` for providers with `CredentialType=mcp_oauth`. Current examples that work include GitHub MCP:
+
+```bash
+arkcli agent +mcp-login \
+  --vault-id vlt-xxx \
+  --name arkcli-github-mcp-oauth-<timestamp> \
+  --mcp-server-url https://api.githubcopilot.com/mcp/ \
+  --format json
+```
+
+3. `arkcli agent +mcp-login` will start a callback server locally, call `CreateVaultOAuthFlow`, print and open the authorization URL, and wait for the backend callback to create the credential. Once successful, it outputs `credential_id`.
+4. Use `--no-open` to avoid automatically opening the browser. Manually copy the authorization URL.
+5. Afterward, use `agent vault credentials list <vault-id>` to view the created credential. Use `agent vault credentials get` to view non-sensitive fields only if explicitly requested for troubleshooting.
+
+Notes:
+
+- Providers with `CredentialType=static_bearer` are not suitable for `arkcli agent +mcp-login`, and should use `agent vault credentials create` for bearer authentication.
+- Do not write user tokens into agent metadata or tags.
+- `agent vault credentials get` may display sensitive authentication fields. Unless explicitly requested for troubleshooting, use `agent vault credentials list` instead.
+- In the current backend metadata discovery, examples like `https://mcp.notion.so/v1` and `https://mcp.larksuite.com/base` fail. Do not use these as default examples.
+
+## Attach MCP to an Agent
+
+- Only attach an MCP when explicitly provided by the user or contextually required. Otherwise, use `agent vault oauth-provider list` to check available providers.
+- Typically, both `McpServers` and `mcp_toolset` need to be configured when attaching an MCP.
+- Note: `--tool` replaces the entire `Tools` array. If you need to preserve default `agent_toolset_20260701` and `mcp_toolset`, include the complete default `Configs` array in the same array. Do not use only `mcp_toolset` or `{type: agent_toolset_20260701}`.
+- If unsure about the default tool structure, refer to `references/agent.md#default-agent-tools`. First run the same `agent agent create ... --dry-run` command and inspect the complete default `Configs` plus the added `mcp_toolset` in `preview.v1`; create the Agent only after explicit confirmation.
+- The example `tools-with-default-agent-toolset-and-github-mcp.json` is not an internal file; it represents a custom `Tools` array file prepared by the caller.
+
+```bash
+arkcli agent agent create \
+  --name arkcli-mcp-agent \
+  --model <items[].model from agent model list> \
+  --mcp-server '{type: url, name: github, url: https://api.githubcopilot.com/mcp/}' \
+  --tool @tools-with-default-agent-toolset-and-github-mcp.json
+```
+
+- `MCPConnectionFailed` usually indicates issues with the URL, protocol, authentication, or `tools/list` initialization, not necessarily an Agent creation failure.
+
+## Example
+
+```bash
+arkcli agent vault oauth-provider list --limit 100 --format json
+arkcli agent vault create --display-name arkcli-mcp-login-vault-20260706 --format json
+arkcli agent +mcp-login --vault-id vlt-xxx --name arkcli-github-mcp-oauth-20260706 --mcp-server-url https://api.githubcopilot.com/mcp/ --format json
+```

package/skills/arkcli-agent/references/model-config.md

@@ -0,0 +1,46 @@
+# Model Runtime Parameter Metadata
+
+Before configuring runtime parameters when creating/updating an Agent or overriding/upgrading a Session, query the target model's metadata. `agent model list` selects models; it does not provide these parameters' complete supported values.
+
+## Query
+
+This API does not provide `epa_tool_model.support`. Use `agent model list --usage tool` to filter version-level metadata from the complete ArkModels catalog; see [tool model discovery](agent.md#discover-tool-models-and-cache-behavior) for parameters and caching. An empty key lookup here does not establish tool-model ineligibility.
+
+```bash
+arkcli agent model config <foundation-model-name> --provider ark --format json
+arkcli agent model config <foundation-model-name> --key thinking.support_value,thinking.default --key service_tier.support_value,service_tier.default --format json
+```
+
+| Input | Meaning |
+| --- | --- |
+| `<foundation-model-name>` | Required. Use the selected `agent model list` item's `name`, not its versioned `model`, model ID, or `ep-*`. Never derive a name by stripping a version suffix. |
+| `--provider` | Defaults to `ark`, matching the frontend. This does not switch accounts or products. Use another provider only when the target model identity is established. |
+| `--key` | Repeatable and comma-separated; omitted means all metadata. Keys are passed to the server without a client allowlist. |
+
+This read-only control-plane command uses the current profile and calls `ListManagedAgentModelMetaDatas`. There are no model-version, pagination, or `--dry-run` flags. Output preserves `ResponseMetadata` and the `Result` array; each item contains `FoundationModelName/Provider/Key/Data`. `Data` is a string array; the public API does not return the internal Schema.
+
+If given only a versioned model identifier, match its `model` in `agent model list` and read that item's `name`. Do not use an Endpoint ID as the name. Report server errors without silently switching account, product, or provider.
+
+## Parameter Reference
+
+| Parameter | Meaning | Metadata keys |
+| --- | --- | --- |
+| `speed` | A model-defined speed mode, available only when supported; not a universal acceleration switch. | `speed.support_value`; the current contract defines no `speed.default`. |
+| `thinking` | Thinking mode; some models support values such as `enabled`, `disabled`, or `auto`. | `thinking.support_value`, `thinking.default` |
+| `reasoning_effort` | Reasoning effort; some models support values such as `low`, `medium`, or `high`. | `reasoning_effort.support_value`, `reasoning_effort.default` |
+| `service_tier` | Model serving tier; some models support values such as `default`, `fast`, or `auto`. This is not CLI plan selection. | `service_tier.support_value`, `service_tier.default` |
+
+These values are illustrative, not universal enums. Read the selected model's metadata rather than guessing. Third-party Protocol and connection settings follow the explicit [BYOK contract](byok.md); Ark metadata does not establish a third-party model's capabilities.
+
+For example, `Key: "thinking.support_value", Data: ["enabled", "disabled"]` and `Key: "thinking.default", Data: ["enabled"]` declare those supported values and that default for the queried model only.
+
+## Use the Response
+
+- Match `Result[].Key` and read its `Data`. Defaults are usually singleton arrays; the first supported value is not necessarily the default.
+- Report missing keys, empty arrays, or inconsistent defaults as returned. Do not invent enums or defaults.
+- An unknown model or provider may still return known keys with empty `Data`; an unknown key may return `Result: []`. This query is not a model-existence check.
+- Metadata guides configuration; it does not add client-side business validation. Explicit user parameters still follow the create/override/upgrade contract and server validation. Successful persistence does not prove a value is declared supported by metadata.
+- Do not inject unrequested parameters or defaults. Omitted upgrade fields retain the documented upgrade baseline semantics; metadata defaults must not overwrite them.
+- Query again when changing models. Old model capabilities must not be carried over. A successful metadata query proves neither model activation nor inference availability.
+
+See [Agent](agent.md), [Session overrides](session-files.md), and [Session upgrade](session-upgrade.md) for write locations and merge semantics.

package/skills/arkcli-agent/references/self-hosted.md

@@ -0,0 +1,47 @@
+# Self-hosted environments and work queues
+
+Use the implemented API contract, not proposed Worker Credential, lease_id, complete, or Worker-list APIs from the PRD.
+
+## Create and bind
+
+```bash
+arkcli agent env create \
+  --name enterprise-worker-env \
+  --runtime-type self_hosted \
+  --dry-run --format json
+```
+
+The create-only `--runtime-type` flag sets `Config.Type` and overrides the same field from `--config`/`--file`. The existing `--config '{Type: self_hosted}'` remains valid. Do not include cloud-only Networking, Packages, Env, or SetupScript. Explicit fields are not silently removed: compatibility is validated by the server. Do not treat `env update` as a cloud/self_hosted type-switch workflow.
+
+Confirm the final create parameters, then capture the returned Environment ID and read it back with `env get`. Bind a Session using `agent session create --agent-id <agent-id> --environment-id <env-id>`. Creating an environment does not start a Worker, and creating a Session does not prove execution: an enterprise Worker must consume work and return tool results.
+
+## Observe
+
+```bash
+arkcli agent env work stats <env-id> --format json
+arkcli agent env work list <env-id> --limit 100 --page-all --format json
+arkcli agent env work get <env-id> <work-id> --format json
+```
+
+- Calls use the `/api/v3/environments/{environment_id}/work` data plane with the current product/profile API Key and scope, not ArkBFF. Pair an explicit base URL with an explicit API Key. Keep credentials out of logs, source files, and reports.
+- List returns `data` and optional `next_page`. Pass the opaque cursor via `--page`; it is not a numeric page. `--page-all` defaults to 100 items per page and at most 10 pages; use `--page-limit` and `--page-delay` as needed. A remaining `next_page` means the result is incomplete.
+- No state/session_id/worker_id filter flags are implemented. Match a Session using each work item's `data.id`. In the current backend, Work ID equals Session ID; prefer actual returned IDs.
+- States are `queued -> starting -> active -> stopping -> stopped`. Work `stopped` is not Session success; inspect Session/events or `+debug` for the business outcome.
+- `depth` counts unclaimed queued work; `pending` counts polled but unacknowledged queued work, not running work. `workers_polling` counts named Workers polling during the last 30 seconds, not all Workers processing active tasks. Zero alone does not prove all Workers are offline. `oldest_queued_at` covers depth and pending.
+- Get/list/stats are read-only and do not support `--dry-run`. Report API errors without switching accounts or products.
+
+## Stop
+
+Read the work item first. Preview without mutating:
+
+```bash
+arkcli agent env work stop <env-id> <work-id> --dry-run --format json
+```
+
+After the user confirms the target and impact, execute `agent env work stop <env-id> <work-id> --yes`. The default is graceful (`force=false`); add `--force` only if explicitly requested. Without `--yes`, real execution returns `requires_confirmation` without a request. Preview is zero-network, does not require `--yes`, and never substitutes for execution authorization or server validation.
+
+The current stop contract accepts only `force`, not `mode/reason`. The command returns the server Work state without waiting for remote processes: graceful stop normally enters stopping; force marks stopped immediately but does not prove the enterprise Sandbox has exited or that late tool results are rejected. Read work again and inspect Worker logs to confirm cleanup. Do not automatically escalate to force.
+
+## Boundary
+
+ArkCLI manages environments/Sessions and observes/stops work; it does not run a resident Worker or execute remote bash/file tool calls locally. Use the official SDK Worker integration supplied by the console, with product-appropriate endpoints. Current integration uses API Keys; do not invent Environment Key commands or substitute Vault credentials. Worker deployment requires a user-selected isolated environment and explicit credential, permission, and working-directory boundaries.