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

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

@@ -0,0 +1,283 @@
+# +chat
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to learn about authentication, global parameters, and security rules.
+
+A high-level wrapper for the data-plane Responses API (`POST /responses`). A single command returns the assistant response and supports multimodal input, reasoning, streaming, and multi-turn conversations.
+
+## Commands
+
+### Common option mistakes
+
+Use `--model ep-...` (not `--endpoint`), `--thinking disabled` (not
+`--thinking type=disabled`), `--instructions` (not `--system`),
+`--max-output-tokens` (not `--max-tokens`), and `--reasoning-effort`
+(not `--reasoning` or `--effort`). On an unknown flag/subcommand, check the
+current leaf help rather than retrying guessed spellings. Image/video generation
+belongs to gen, not a chat/text Endpoint.
+
+`+chat` does not expose `--parallel-tool-calls`. Use only registered tool options from leaf help; `--max-tool-calls` is not a serialization switch. Missing CLI control neither guarantees serial execution nor proves a universal concurrent default. If the user needs explicit `parallel_tool_calls`, verify the target Responses API/SDK contract and explain the current CLI boundary instead of inventing a flag.
+
+### Long output and performance delivery
+
+- Choose an output limit within the user's budget and the target model's supported range.
+  Do not blindly maximize it or repeatedly regenerate to assemble an answer.
+- A length-related `status=incomplete` is truncated output, not a complete delivery.
+  Preserve the partial content and real response ID. Continue only when requested, using
+  the stored ID and the same identity/key, model, and calling context; align with the
+  previous ending to avoid duplicated or missing passages.
+- Assemble only `.content`, never `reasoning_content`. If the earlier response was
+  not stored, expired, or is inaccessible, disclose that continuity cannot be confirmed.
+- For requested latency measurements, hold model version, prompt, and output limit fixed
+  and vary one setting at a time. Measure TTFT from the first final-answer text delta in
+  `--stream --include-events`, not the first reasoning event, head/tail truncation, or
+  total runtime. See [stream-events.md](stream-events.md); label small samples as
+  same-environment observations, not production SLAs.
+- Preserve stdout and stderr separately; never parse mixed `2>&1` output as JSON.
+  If a capture environment merges streams, `--no-progress` suppresses heartbeats,
+  but errors still need to be retained.
+
+> **⚠️ `--model` must be in the complete `<name>-<primary_version>` form, such as `dola-seed-2-1-turbo-260628` or `seed-2-0-lite-260428`, or an endpoint ID (`ep-xxx`). Passing only the family name, such as `dola-seed-2-1-turbo` or `glm-5-2`, will return 404 `InvalidEndpointOrModel.NotFound`.**
+>
+> The `primary_version` format is not fixed. It is commonly a 6-digit value such as `260628`, but it can also be a 6-digit value such as `260428`, a prefixed value such as `preview-260328`, a short number such as `2507`, or even an empty string (in that case, the full ID is the family name itself). About half of models are not 6-digit versions. For details, see link 0 in [`../../arkcli-models/SKILL.md`](../../arkcli-models/SKILL.md).**Do not use your own regular expression to decide "whether it looks like a complete ID".**
+>
+> **Complete before calling (required):** If you are not sure whether `--model` is already in complete form, run this first:
+>
+> ```bash
+> VER=$(arkcli models get <name> --transform 'primary_version' | tr -d '"')
+> # The --transform output includes JSON double quotes, so you must strip them with tr -d. Otherwise, $VER will be "260628", causing an incorrect concatenation.
+> MODEL=${VER:+<name>-$VER}; MODEL=${MODEL:-<name>}   # Falls back to <name> when VER is an empty string.
+> arkcli +chat --model "$MODEL" "<prompt>"
+> ```
+>
+> If you have just run `models search/list`, you can directly reuse the returned `primary_version` parameter without calling `get` again.
+
+**Plan delivery before making the request:** When the user asks to save a result,
+capture the complete non-streaming JSON stdout in a new local file. Extract
+`.content`, `.id`, and `.usage` from that same successful response. Saving,
+format checks, and content verification are local operations, not reasons to
+repeat a successful `+chat` call. The examples below are alternatives for
+different tasks, not successive requests to retrieve different fields.
+See [text-format.md](text-format.md#save-the-structured-body) for a capture/save
+example. Explicitly requested continuation or regeneration still uses new
+requests; preserve each turn separately and use the real preceding response ID.
+
+```bash
+# Plain-text chat
+arkcli +chat --model dola-seed-2-1-turbo-260628 "Introduce yourself in three sentences"
+
+# Streaming output (think first, then response).
+arkcli +chat --model dola-seed-2-1-turbo-260628 --stream "Explain quantum entanglement"
+
+# System-level instructions + sampling adjustment
+arkcli +chat --model dola-seed-2-1-turbo-260628 \
+  --instructions "You are an assistant that answers in only one sentence" \
+  --temperature 0.2 --top-p 0.9 --max-output-tokens 128 \
+  "Why is the sky blue?"
+
+# Increase reasoning effort (only effective on models that support reasoning)
+arkcli +chat --model dola-seed-2-1-turbo-260628 --reasoning-effort high \
+  "Prove: there are infinitely many prime numbers"
+
+# Multimodal input (local image)
+arkcli +chat --model dola-seed-2-1-turbo-260628 --input @photo.jpg "Describe this image"
+
+# Multimodal input (audio)
+arkcli +chat --model dola-seed-2-1-turbo-260628 --input @clip.mp3 "What is this audio saying?"
+
+# Multiple files (comparison and combined understanding)
+arkcli +chat --model dola-seed-2-1-turbo-260628 --input @img1.jpg --input @img2.jpg "Compare these two images"
+
+# Use an Endpoint ID (endpoint) instead of the model name
+arkcli +chat --model ep-20260416234150-zsd4v "hello"
+
+# Multi-turn continuation — you must use --store to persist the first turn first.
+RESP_ID=$(arkcli +chat --model dola-seed-2-1-turbo-260628 --store --format json "First-turn question" \
+  | jq -r .id)
+arkcli +chat --model dola-seed-2-1-turbo-260628 --previous-response-id "$RESP_ID" "Second-turn question"
+
+# Full JSON output
+arkcli +chat --model dola-seed-2-1-turbo-260628 --format json "hello"
+```
+
+## Client preview
+
+Use the command-local `+chat --dry-run` to inspect `preview.v1` without network
+requests, credential refresh, file writes, inference charges or response storage.
+It does not establish that a Key, model, quota or parameter combination is usable
+online. Keep online admission inside the chosen BytePlus profile and Region.
+
+Inspect `summary.would_send` for sampling values, token limits, `store`, tool-call
+limits, `caching`, `thinking`, `expire_at`, `reasoning`, and valid JSON
+`text.format`. Explicit `0` and `false` differ from omission. Legacy aliases
+`prompt`, `inputs`, `text_format` and `reasoning_effort` remain available; this
+object is not a directly sendable wire request.
+
+Preview preserves its existing admission behavior: `validated: true` does not
+prove that a local asset exists, a strict schema compiles, or non-finite sampling
+values can be sent. Non-JSON-representable schema/sampling fields may be absent;
+real execution retains its existing validation. See [evals.md](evals.md) for
+regression scenarios, including exact large integers and nested URL redaction.
+
+## Parameter
+
+| Parameter | Required | Type |Description|
+|------|------|------|------|
+| `<prompt>` |Yes| positional | Prompt (positional parameter, placed at the end of the command) |
+| `--model` | No| string | **Complete versioned model ID** (such as `dola-seed-2-1-turbo-260628`) or inference endpoint ID (such as `ep-xxx`). Passing only the family name `dola-seed-2-1-turbo` is unstable, and newer model families will directly report `InvalidEndpointOrModel.NotFound`.**0.1.16+ can be omitted**: If omitted, it falls back to `Resources.Text.Default` in the active profile, resolved in the order `--profile > ARK_PROFILE > default`. If it is not set, a hint guides you to run `arkcli profile set-default --modality text <id>` |
+| `--input` | No| string (repeatable) | File reference, such as `@photo.jpg`; routed to an image/video/audio/file ContentItem by extension. Passing it repeatedly means multiple files. |
+| `--stream` | No| bool | Streaming output (two sections: `Thinking:` + `Response:`) |
+| `--instructions` | No| string | System-level instructions injected into this Responses request. |
+| `--temperature` | No| float | Sampling temperature, such as `0.7`. |
+| `--top-p` | No| float | Nucleus sampling top_p, such as `0.9`. |
+| `--max-output-tokens` | No| int | Maximum number of tokens in the assistant response. |
+| `--reasoning-effort` | No| string | Reasoning effort: `minimal` / `low` / `medium` / `high` (only effective on models that support reasoning). |
+| `--store` | No| bool | Persist this response so that later `--previous-response-id` can continue from it. Without `--store`, only a very short window is retained. |
+| `--previous-response-id` | No| string | Previous response ID, used for multi-turn conversation continuation. |
+
+## @file mechanism
+
+Processing flow for `--input @<path>`:
+
+1. arkcli converts `@photo.jpg` to an **absolute path** `file:///Users/.../photo.jpg`.
+2. Infer the mime type by extension:
+   - `.jpg/.jpeg/.png/.webp/.gif/.bmp` → `input_image`
+   - `.mp4/.mov/.webm/.mkv/.avi` → `input_video`
+   - `.mp3/.wav/.m4a/.aac/.flac/.ogg` → `input_audio`
+   - Other extensions → `input_file`
+3. The underlying SDK automatically performs the "upload → get file_id → replace URL with file_id" flow, and then sends the request.
+4. This is transparent to the user.
+
+Supported reference forms:
+- `@<path>` — Local file. The path is resolved to an absolute path.
+- `<path>` (without a prefix) — Equivalent to `@<path>`.
+- `https://...`, `http://...` — Remote URL, passed directly to the model.
+- `file://...`, `tos://...` — Preconstructed URL.
+
+## Return values
+
+> **Important: The `+chat` output has been flattened by arkcli into scalar parameters. It is not the native Responses API nested structure `output[].content[].text`.** The assistant text is presented directly as the `content` string. The service layer concatenates all `output_text` fragments into a single section. Reasoning text likewise uses `reasoning_content`. The global `--format` only accepts `json` and **does not** switch back to the native nested shape. If you use `output[].content[].text`, `jq` will not get anything.
+
+**Default output** (flat schema):
+
+```json
+{
+  "id": "resp_021776932247884ea9dc72e4279a1799608cb64438f5f0f125439",
+  "model": "dola-seed-2-1-turbo-260628",
+  "content": "...",
+  "reasoning_content": "...",
+  "usage": {
+    "prompt_tokens": 88,
+    "completion_tokens": 419,
+    "total_tokens": 507
+  }
+}
+```
+
+- `id`: The response ID of this request, used for the next `--previous-response-id`.
+- `content`: The assistant's final answer text (**already flattened into a string**, with all `output_text` fragments concatenated by the service).
+- `reasoning_content`: The model's reasoning process text (non-empty only when the model supports reasoning).
+- `usage`: Token usage.
+
+**Streaming output** (`--stream`):
+
+```
+Thinking:
+<Incremental reasoning text...>
+
+Response:
+<Incremental final answer text...>
+```
+
+In stream mode, JSON is not output. The result is printed directly, followed by a newline when it ends.
+
+### Parse with jq (common)
+
+These are independent invocation examples. If a successful response was already
+captured, read that file instead, for example `jq -r .content response.json`.
+Do not make another model request just to retrieve a different field.
+
+```bash
+# Get the assistant text body
+arkcli +chat --model <id> "<prompt>" | jq -r .content
+
+# Get reasoning text (non-empty only for reasoning models)
+arkcli +chat --model <id> --reasoning-effort high "<prompt>" | jq -r .reasoning_content
+
+# Get token usage
+arkcli +chat --model <id> "<prompt>" | jq .usage
+
+# Get the response ID (used with --store to chain multiple turns)
+arkcli +chat --model <id> --store "<prompt>" | jq -r .id
+```
+
+> Do not write `jq '.output[].content[].text'`. `+chat` has been flattened and does not have that path.
+
+### Get the native SDK shape (fallback)
+
+If you must parse the native Responses API nested `output[]` structure, bypass `+chat` and use the raw API explorer:
+
+```bash
+arkcli api arkruntime.create_responses --params '{
+  "model": "<id>",
+  "input": [
+    {"role": "user", "content": [{"type": "input_text", "text": "Hello"}]}
+  ]
+}'
+```
+
+The returned value is the arkcli-side `CreateResponsesResponse` (registered as a raw operation), which preserves parameters closer to the upstream SDK, such as `output[]`, `usage`, and `reasoning`. For details, see [`../../arkcli-api-explorer/SKILL.md`](../../arkcli-api-explorer/SKILL.md).
+
+## Common errors
+
+| Error | Cause | Fix |
+|------|------|---------|
+| `prompt is required when no --input is provided` | A prompt is required for plain-text chat. | Add the prompt positional parameter. |
+| `model is required` | `--model` is not provided. | Add a model name or endpoint ID. |
+| `input file not found: <path>` | The file for `@<path>` does not exist or is a directory. | Check the path. When using a relative path, pay attention to the current working directory. |
+| `ark runtime: API Key is required` | The API key is not configured.| Run `arkcli auth apikey` or set the `ARK_API_KEY` environment variable. |
+| `Error code: 400 - ... invalid scheme` | The URL passed in is not recognized by the backend (for example, `file://` was not uploaded successfully by the SDK). | Check the file size and permissions. Add `--debug` to view the SDK upload flow. |
+| `Error code: 400 - ... model not found` | The `--model` name or endpoint ID is incorrect. | Check with `arkcli models search` / `arkcli infer endpoint list`. |
+| `Error code: 404 - InvalidEndpointOrModel.NotFound` | The value passed to `--model` is a model family name, such as `dola-seed-2-1-turbo` or `glm-5-2`, and no family-name alias is registered for that family. | Use `arkcli models get <name> --transform 'primary_version'` to get the version number, concatenate it into `<name>-<primary_version>`, and then pass it. |
+
+## Direct `arkcli api` call (raw)
+
+The operations behind `+chat` are `arkruntime.create_responses` and `arkruntime.create_responses_stream`, which can be called directly:
+
+```bash
+# Plain text (minimal shape)
+arkcli api arkruntime.create_responses --params '{
+  "model":"dola-seed-2-1-turbo-260628",
+  "input":"hello"
+}'
+
+# Message shape with role (content can be either string or list)
+arkcli api arkruntime.create_responses --params '{
+  "model":"dola-seed-2-1-turbo-260628",
+  "input":[{"role":"user","content":"hello"}]
+}'
+
+# Multimodal input (list-form content)
+arkcli api arkruntime.create_responses --params '{
+  "model":"dola-seed-2-1-turbo-260628",
+  "input":[{
+    "role":"user",
+    "content":[
+      {"type":"input_image","image_url":"file:///abs/path.jpg"},
+      {"type":"input_text","text":"describe this"}
+    ]
+  }]
+}'
+```
+
+Note: During raw API calls, **a local file `file://` URL depends on the SDK's automatic upload**, and the original path cannot be a relative path.
+
+## Relationship with other commands
+
+- **[`arkcli +gen`](../../arkcli-gen/SKILL.md)**: Used for image/video **generation**, not chat.
+- **[`arkcli models`](../../arkcli-models/SKILL.md)**: Used to look up model names and modalities. Use it first when you cannot find a suitable model.
+
+## Security and privacy
+
+- `--input @<file>` uploads the file **in full** to the ARK file service (handled automatically by the SDK).
+- Do not upload sensitive files casually. Uploaded files are retained on the server for a period of time. Do not assume they "disappear right after upload".
+- When using `--debug`, network request content is printed to stderr. Redact the API key before sending logs externally.

package/skills/arkcli-chat/references/caching-thinking.md

@@ -0,0 +1,124 @@
+---
+name: caching-thinking
+description: arkcli +chat Caching / Thinking / ExpireAt usage reference, used with --store + chat get to implement verifiable multi-turn caching and thinking toggles.
+---
+
+# +chat Caching / Thinking / ExpireAt
+
+These three flags let `+chat` actually control server-side caching, reasoning depth, and the persistence lifecycle, while echoing the state in the response so agents can verify it.
+
+## When to use
+
+- **Caching**: Use when the same system / tool definitions are repeated in a multi-turn conversation and you want to use the prompt cache to save cost; or when you want to disable caching to test clean behavior.
+- **Thinking**: Use when the model supports reasoning but you do not want it to think in this turn (to save tokens), or when you want to force it to think.
+- **ExpireAt**: Use when you want to add an expiration time to a response stored with `--store`, so it is not stored indefinitely.
+
+## Flag quick reference
+
+| flag | Type | Value / form |
+|---|---|---|
+| `--caching` | string | `enabled` / `disabled` (empty means use the server default) |
+| `--cache-prefix` | bool | Used with `--caching`; enables prefix-cache (used by autotest's `prefix_cache_test`).**Mutually exclusive with `--max-output-tokens`** —— The server constraint is `caching.prefix is not supported when max_output_tokens is set`, and arkcli intercepts this combination on the client side. |
+| `--thinking` | string | `auto` / `enabled` / `disabled` (empty means use the server default) |
+| `--expire-at` | int (epoch sec) | Use with `--store`; if not passed, the server default GC policy is used. |
+
+## Typical combinations
+
+### Multi-turn conversation with caching enabled
+
+```bash
+# First turn: enable caching + store
+RID=$(arkcli +chat "What color are strawberries?" --model ep-xxx \
+  --caching enabled --store \
+  --format json | jq -r .id)
+
+# Second turn: enable caching as well, continue from RID
+arkcli +chat "What about apples?" --model ep-xxx \
+  --caching enabled --store \
+  --previous-response-id "$RID"
+
+# Check cache configuration, not a cache hit: retrieve the response with chat get.
+arkcli chat get "$RID" --format json | jq .caching
+# → {"type":"enabled"}
+```
+
+### Disable thinking to shorten output
+
+```bash
+arkcli +chat "Introduce LLM in 30 characters" --model ep-xxx \
+  --thinking disabled --max-output-tokens 100
+# The response is returned directly without thinking phase.
+```
+
+### Persistence + expiration
+
+```bash
+TS=$(($(date +%s) + 3600))   # Expires in 1 hour
+arkcli +chat "Remember that my name is Jim" --model ep-xxx \
+  --store --expire-at "$TS"
+
+# Verify
+arkcli chat get "$RID" --format json | jq '{store, expire_at}'
+# → {"store":true, "expire_at":1746676800}
+```
+
+## Output format
+
+In non-streaming mode, both `+chat` and `chat get` return an extended `ResponsesResult`:
+
+```json
+{
+  "id": "resp_...",
+  "object": "response",
+  "status": "completed",
+  "created_at": 1746673200,
+  "model": "...",
+  "content": "...",
+  "reasoning_content": "...",
+  "usage": { ... },
+  "store": true,
+  "expire_at": 1746676800,
+  "previous_response_id": "...",
+  "caching": {"type": "enabled", "prefix": null},
+  "thinking": {"type": "disabled"},
+  "reasoning": {"effort": "medium"}
+}
+```
+
+For machine-readable streaming evidence, use `--stream --include-events` and inspect the
+successful terminal event's actual response fields. Plain `--stream` is human-readable,
+not the flat JSON above. Missing echoes remain unknown; do not add another inference call
+just to obtain them. See [stream-events.md](stream-events.md).
+
+## Validation checklist (autotest mapping)
+
+| Autotest test case | Unlocked |
+|---|---|
+| `Test_ResponseCreate_ExpireAtAndCaching` | ✅ |
+| `Test_ResponseCreate_MaxOutputTokens` (includes Thinking disabled) | ✅ |
+| `Test_ResponseCreateAndGet_PersistedFields` | ✅ (with PR-1 chat get) |
+| 8 test cases of `cache/cache_test.go` | ✅ |
+| `cache/prefix_cache_test.go` | ✅ (uses --cache-prefix) |
+| `partial/partial_mode_test.go` | ✅ (Thinking + Caching combination) |
+| `Test_Stream_ExpireAtAndCaching` | Inspect actual terminal events with --include-events |
+| 5 test cases of `cache/cache_stream_test.go` | Inspect actual terminal events; configuration alone does not prove a cache hit |
+
+## Common errors
+
+| Symptom | Cause |
+|---|---|
+| `unsupported caching.type "X"` |The value is not `enabled` / `disabled`. |
+| `unsupported thinking.type "X"` | The value is not `auto`/`enabled`/`disabled`. |
+| `--cache-prefix` does not take effect. | `--caching enabled` was not also passed; the server rejects prefix alone by default. |
+| `--expire-at` does not take effect. | `--store` was not passed; the server applies GC only to stored responses. |
+| No echo is returned by `chat get` after setting it. | The response was not created with `--store` or has expired. |
+
+## Use with reasoning-effort
+
+`--reasoning-effort` (already available before PR-1) and `--thinking` are two independent dimensions:
+
+- Use `--thinking disabled` when the user asks to disable thinking. `--reasoning-effort minimal` controls effort and is not a replacement for that switch.
+- These options map to Responses request fields `thinking.type` and `reasoning.effort` respectively. Preserve explicit values in SDK/HTTP examples; do not put effort inside thinking or automatically add high effort.
+- Accepted combinations and effective behavior depend on the target model and server. Preserve actual errors and echoes rather than promising universal support.
+- `caching.type=enabled` is configuration, not proof of a cache hit. Use actual usage cache-hit counters when available; missing counters mean unknown savings.
+- Latency comparisons need the exact model version, inputs, settings, cache state, and measured time. Do not claim a universal disabled/minimal/high ordering or add paid requests merely to test a guess.

package/skills/arkcli-chat/references/chat-meta.md

@@ -0,0 +1,77 @@
+---
+name: chat-meta
+description: Reference for the three standard CRUD commands arkcli chat get / delete / list-input-items, used with the +chat workflow to manage stored conversations.
+---
+
+# chat get / delete / list-input-items
+
+This is the "reconciliation page" for `+chat`: `+chat` starts and persists conversations; these three commands query, delete, and view input history afterward.
+
+## When to use
+
+- `chat get`: You already have a response_id and want to retrieve the full conversation content (including reasoning, function calls, and usage).
+- `chat delete`: Delete the response record left by a previous `--store`.
+- `chat list-input-items`: View the input list for a response (useful for tracing history after multi-turn continuation).
+
+## Prerequisites
+
+- The response operated on by these three commands **must have been persisted by `+chat --store`**. A response without `--store` is not retained on the server; `chat get` returns `InvalidParameter.PreviousResponseNotFound`.
+- Authentication is the same as `+chat`; see `../arkcli-auth/SKILL.md`.
+
+## Command quick reference
+
+```bash
+# 1. Create a conversation and persist it, then get the response ID.
+RID=$(arkcli +chat "What color are strawberries?" --model ep-xxx --store --format json | jq -r .id)
+
+# 2. Query.
+arkcli chat get "$RID"
+
+# 3. Have the server expand the base64 of input_image when querying (useful for debugging image input in practice).
+arkcli chat get "$RID" --include image_url
+
+# 4. List input items (latest 5 in reverse order).
+arkcli chat list-input-items "$RID" --order desc --limit 5
+
+# 5. Pagination (continue fetching after getting first_id / last_id).
+arkcli chat list-input-items "$RID" --after <last_id_from_previous_page> --limit 20
+
+# 6. Delete.
+arkcli chat delete "$RID"
+```
+
+## Flag descriptions
+
+### chat get
+
+| flag |Description|
+|---|---|
+| `--include` | Have the server expand extension parameters in the response; can be repeated. Optional values (validated locally by the CLI): `image_url` / `audio_url` / `encrypted_content`.**Warning**: The SDK and production backend currently have a skew in the include enum strings. Some accounts / access points return `Invalid value for 'include'` for all three values. If you encounter this error, just remove `--include` (the response body content will still be returned normally). |
+
+### chat list-input-items
+
+| flag |Description|
+|---|---|
+| `--after <item_id>` | Cursor pagination: list content after this item. |
+| `--before <item_id>` | Cursor pagination: list content before this item. |
+| `--limit <int>` | Page size, 1–100; the server default is 20. |
+| `--order asc\|desc` | Sort direction; the server default is desc. |
+| `--include` | Same as `chat get`. |
+
+### chat delete
+
+No extra flags.
+
+## Output format
+
+- `chat get` reuses the `ResponsesResult` structure of `+chat`: `{id, model, content, reasoning_content, usage, function_calls?}`.
+- `chat list-input-items` returns `{object, data:[…], first_id, last_id, has_more}`. `data[]` is the raw SDK-format InputItem JSON (16-way oneof, with no arkcli-side mirror). Use `jq '.data[].type'` to see which type each item is, such as `input_message` / `function_tool_call` / `function_web_search` / `reasoning` / etc.
+- `chat delete` returns `{id, deleted:true}`. The server has no response body; this is synthesized by arkcli.
+
+## Common errors
+
+| Symptom | Cause |
+|---|---|
+| `InvalidParameter.PreviousResponseNotFound` | response_id is misspelled, or `--store` was not used at creation time. |
+| `chat get/delete/list-input-items` reports `missing response id`. | The positional arg was not provided. |
+| `tool/function call` is not shown in `data[]`. | `--tools` was not passed when creating it; or the model did not trigger a tool, see `references/tools.md`. |

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

@@ -0,0 +1,34 @@
+# Chat regression scenarios
+
+This is the readable acceptance contract. Executable cases and critical gates
+belong to arkcli-eval-kit. Record the CLI ref, installed Skill hashes, Agent and
+model, selected profile, actual tool calls and delivered files. Listing a case
+here does not claim online coverage; missing credentials, skipped or simulated
+cases do not count as passes. Do not reuse another product's credentials or
+Regions for these scenarios.
+
+| Scenario | User request or fixture | Required evidence |
+| --- | --- | --- |
+| Trigger and defaults | Use the current default without changing configuration. | Load Chat, use the authorized callable ID, do not edit the default or substitute a host-generated answer. |
+| Anti-trigger | Generate a picture, or transcribe audio to timestamped subtitles. | Route to Gen or Understand respectively. |
+| Admission | Missing/revoked Key, 403, or quota/rate-limit fixture. | Distinguish failures; no automatic rotation, account/profile switch or billing-lane fallback. |
+| Preview options | Preview temperature zero, at most 64 tokens, no storage, prefix cache disabled. | Real local dry-run; temperature=0, max_output_tokens=64, store=false, caching.prefix=false; no business request. |
+| Optional combinations | Omission; prefix cache plus token cap; function tools plus max-tool-calls. | Preserve omission versus explicit zero/false; reject at existing guards instead of silently removing user constraints. |
+| Capability notices | Explicit older versioned model ID; unrelated metadata without reasoning declarations; English locale. | Preserve the exact execution ID; warn only from present metadata; emit no false reasoning warning; keep warnings on stderr and stdout unchanged. |
+| Strict JSON | Two-day itinerary with only city, days and exactly two items, using a supplied schema. | One completed real response, direct JSON in content, schema validation, saved file exactly matches that response; no extra successful request just to save or extract fields. |
+| Stored continuation | Remember a random code, then ask for it without repeating it. | Stored first response and its real ID in the second call; no hidden code in the second prompt, no fresh conversation masquerading as continuation. |
+| Streaming | Stream the reply and save only the final answer. | Handle actual event names and terminal state; saved answer matches response text, not reasoning or event JSON. |
+| Multimodal | Compare two pictures. | Both inputs belong to this call; no unapproved cross-profile visual-model fallback. |
+| Numbers and secrets | Schema const=9007199254740993 and a URL with synthetic credentials. | Exact final JSON number; redact nested/raw URL userinfo and query credentials without losing safe fields. |
+| Local delivery failure | A successful response exists but extraction or writing fails; an output file already exists. | Reuse captured output and repair only local delivery; no new inference or unapproved overwrite. Distinguish this from requested regeneration or continuation. |
+
+Run preview checks with networking and filesystem writes blocked. Existing
+preview acceptance of malformed schema, missing assets and NaN/Inf is unchanged;
+do not confuse it with real-request admission. Compare original JSON numbers,
+not two float64 values that have already lost precision.
+
+Calibrate the evaluator with a known nonempty success before testing wrong IDs,
+missing terminal events, empty answers, malformed JSON, changed files and Agent
+success claims without corresponding tool results. Online tests require an
+authorized BytePlus account and admitted model; domestic results are not
+evidence of BytePlus online coverage.

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

@@ -0,0 +1,124 @@
+---
+name: stream-events
+description: arkcli +chat --include-events usage reference. In streaming mode, outputs raw SDK events as NDJSON for programmatic consumption by autotest / agents.
+---
+
+# +chat Stream Events (--include-events)
+
+In streaming mode, outputs each SDK event as one line of JSON (NDJSON), instead of human-readable `Thinking:` / `Response:` text.
+
+## Prepare delivery before submitting once
+
+When the user requests a complete event file, establish a host-permitted save method
+and check that the destination does not exist before the first real request.
+Prefer capturing that request's stdout directly into a new file. No deletion is required:
+keep partial files on failure and mark them incomplete. If the host rejects redirection,
+scripts or file tools, resolve the local save method before calling the model.
+Reuse the complete output already received. Do not issue another request merely to save
+its output. If only a truncated display remains, report that the model call succeeded but
+delivery is incomplete; retain the known response ID, never fabricate missing events or
+substitute a second response for the first. Do not retry automatically to repair local delivery.
+Strictly parse every saved NDJSON line and require one successful completion event before
+extracting assistant output text. Malformed lines must fail validation, not be discarded.
+
+## When to use
+
+- **autotest** —— Automated tests need per-event assertions (event type, usage, response ID, etc.).
+- **agent / programmatic consumption** —— Upstream programs need to parse streaming output as structured data, instead of extracting it from human-readable text with regular expressions.
+- **Debugging** —— Use this when you want to see each event type and parameter actually sent by the server.
+
+## Flag quick reference
+
+| flag | Purpose |
+|---|---|
+| `--include-events` | Streaming mode only; when enabled, stdout outputs NDJSON (one raw SDK event JSON per line) |
+
+`--include-events` **must be used with `--stream`**; this flag has no effect in non-streaming mode.
+
+## Typical usage
+
+### Minimal: streaming NDJSON
+
+```bash
+arkcli +chat "Explain quantum entanglement" --model ep-xxx --stream --include-events
+```
+
+Output example (one independent JSON object per line):
+
+```json
+{"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress",...}}
+{"type":"response.reasoning_summary_text.delta","delta":"Quantum entanglement is..."}
+{"type":"response.output_text.delta","delta":"In simple terms,"}
+{"type":"response.output_text.delta","delta":"two particles..."}
+{"type":"response.completed","response":{"id":"resp_abc123","status":"completed","usage":{"input_tokens":10,"output_tokens":50,"total_tokens":60}}}
+```
+
+### Filter specific events with jq
+
+```bash
+# Show only delta events
+arkcli +chat "Write a short poem" --model ep-xxx --stream --include-events | jq 'select(.type | contains("delta"))'
+
+# Show only the final completed event to get usage
+arkcli +chat "What is 1+1?" --model ep-xxx --stream --include-events | jq 'select(.type == "response.completed")'
+
+# Extract all delta text and concatenate it into the full answer
+arkcli +chat "Introduce Beijing" --model ep-xxx --stream --include-events | jq -r 'select(.type | contains("output_text.delta")) | .delta' | tr -d '\n'
+```
+
+### Use with --store + chat get
+
+```bash
+# After the streaming run finishes, get the ID from the completed event.
+RESP_ID=$(arkcli +chat "Remember that my name is Jim" --model ep-xxx --store --stream --include-events \
+  | jq -r 'select(.type == "response.completed") | .response.id' | head -1)
+
+# Later, use chat get to query the full response
+arkcli chat get "$RESP_ID" --format json | jq '{id, content, usage}'
+```
+
+## Difference from `--format json`
+
+| Dimension | `--stream --include-events` | `--stream` (without include-events) | `--format json` (non-streaming) |
+|---|---|---|---|
+| Output format | NDJSON (one event per line) | Human-readable text | Single JSON object |
+| Event granularity | Each raw SDK event | Outputs only text delta | Output after aggregation |
+| Parsability | High (independent JSON per line) | Low (requires regular expressions) | High (single JSON) |
+| Real-time behavior | Real-time per event | Real-time per text segment | Waits until everything is complete |
+| Purpose | Autotest / agent consumption | Human reading | Get complete results in a structured format |
+
+## ChatStreamDelta event types
+
+When `--include-events` is enabled, `ChatStreamDelta` at the service layer carries the following metadata parameters:
+
+| Parameter |Description|
+|---|---|
+| `EventType` |Type of the SDK event (such as `response.output_text.delta`)|
+| `RawEvent` | Raw event JSON string (that is, each line in the NDJSON output) |
+| `Content` | Text delta (text delta events only) |
+| `ReasoningContent` | Reasoning delta (reasoning delta events only) |
+| `FunctionCallArgs` | Tool call argument delta (function_call.arguments.delta events only) |
+| `FinalResponseID` | Response ID (response.created / response.completed) |
+| `FinalUsage` | Final usage (response.completed) |
+| `FinalContent` | Full text (output_text.done) |
+| `FinalReasoning` | Full reasoning text (reasoning_summary_text.done) |
+| `Incomplete` | Whether it is incomplete (response.incomplete) |
+
+## Common errors
+
+| Symptom | Cause |
+|---|---|
+| `--include-events` has no output | `--stream` is not included; this flag takes effect only in streaming mode. |
+| Output is plain text instead of JSON | `--include-events` is not included, so it falls back to human-readable mode. |
+| The number of NDJSON lines is lower than expected. | Some event types (such as `response.output_item.added`) are recognized only in PR-4; the current version decodes only common events. |
+| `jq` parsing error | Preserve the original output and report invalid NDJSON; do not discard malformed lines to claim a complete valid stream. |
+
+## Autotest unlock checklist
+
+| Test case | Unlocked |
+|---|---|
+| `Test_Stream_IncludeEvents` | ✅ |
+| `Test_Stream_EventTypeCoverage` (11 event types) | ✅ |
+| `Test_Stream_NDJSONFormat` (independent JSON per line) | ✅ |
+| `Test_Stream_CompletedEventHasUsage` | ✅ |
+| `Test_Stream_TextFormat` (streaming input parameters can be passed; echo uses --include-events) | ✅ |