@adelie/agent-development 0.0.0-stage → 0.5.0

package/skills/penguin-sdk/reference/agent-api.md

@@ -0,0 +1,159 @@
+# The API path: a program that calls an Adelie Agent
+
+Read this before you write a program that calls an Adelie Agent over the Agent API. The rules in SKILL.md, *The API path*, hold throughout. The user documentation has every detail: the [Agent API guide](https://lmliheng.github.io/Adelie/docs/agent-api) and the [AMSP protocol](https://lmliheng.github.io/Adelie/docs/amsp).
+
+## 1. Hand the opening to the user
+
+Check first. This command only reads:
+
+```bash
+penguin agent api status --agent-id <agentId> --json
+```
+
+It prints one line of JSON: `agent` (the Agent ID), `baseUrl`, `api` (`enabled`, `open`, `approvalMode`, `keys`) and `serverEnabled`. A key's secret is never in it.
+
+When `api.enabled` is false, or `api.keys` is empty and `api.open` is false, the program cannot run yet. Give the user these steps with the Agent's id filled in. Only the Project's owner can take them.
+
+1. Open the Agent's settings and select the **API** tab (`/agents/<agentId>?tab=api`).
+2. Turn on **Enable API access**.
+3. Choose the **Approval mode for API conversations** (see the table below).
+4. Under **Keys**, select **New key**, name it after the program, and copy the key. It is shown once.
+5. Give the key to the program as the environment variable `ADELIE_AGENT_KEY`.
+
+The same steps in the user's own terminal, never in yours:
+
+```bash
+penguin auth login
+penguin agent api enable --agent-id <agentId> --approve <mode>
+export ADELIE_AGENT_KEY="$(penguin agent api keys create --agent-id <agentId> --name <program>)"
+```
+
+`keys create` prints the key alone on stdout, so the variable takes it without showing it. These commands change the Agent's exposure, so they take the user's sign-in: `penguin auth login` once, or `penguin auth token` on the server's machine. From your shell the server refuses them with `403 human_required`. Never sign in or mint a session to get past that.
+
+When `serverEnabled` is false, the server's administrator has turned the Agent API off, and every request is refused with `403`. Only an administrator turns it back on, in **Settings › Server › Agent API**.
+
+Suggest the approval mode that fits the program, and say why in one line:
+
+| The program | Mode | What happens |
+| --- | --- | --- |
+| Has no one to ask: a batch job, a backend | `allow-all` (the default) | Every tool call runs, inside the sandbox |
+| May let the agent read but nothing more | `read-only` | Read-only tools run; every other call waits for the program's answer |
+| Shows every tool call to its own user | `always-ask` | Every call waits for the program's answer |
+| Must never run a tool | `deny-all` | Every call is denied; the agent answers without tools |
+
+A call that waits reaches the program as an `approval.requested` event, and the run waits, with no time limit, for an answer, an abort or a disconnect. The `@adelie/amsp` client answers it with `onApproval`, or with `deny` when there is none. The mode is read when an API conversation is created; a change on the tab applies to conversations created after it.
+
+Leave **Allow keyless access** off unless the user asks for it. With it on, anything that can reach the server can run the Agent on the Project's models.
+
+To run the program yourself, you need the key in your environment. Ask the user to add it to your key vault as `ADELIE_AGENT_KEY`: the gear icon on your card on the Agents page, then the key vault tab. Vault values reach your shell on the next task. Until then, the program is unverified.
+
+## 2. The connection values
+
+| Value | Where it comes from | In the program |
+| --- | --- | --- |
+| Base URL | **Connection** on the API tab, or `baseUrl` from `status` | A constant, which `ADELIE_AGENT_URL` can override |
+| Agent ID | **Connection** on the API tab, or `agent` from `status`: `<projectId>/<agentId>` | A constant |
+| Key | Created by the owner, shown once | `process.env.ADELIE_AGENT_KEY`, and nowhere else |
+
+- A local server's Base URL is `http://localhost:7364/api/amsp/v1`; `status` prints the server's real port. Use `localhost`, never `127.0.0.1`: a local server serves previews on `127.0.0.1` and answers every API request there with `401`.
+- Do not give the program's settings the names the harness sets inside a session: `ADELIE_API_URL`, `ADELIE_API_TOKEN`, `ADELIE_PROJECT_ID`, `ADELIE_AGENT_ID`, `ADELIE_SESSION_ID`. They name the session's own server and Agent, and they override a vault entry of the same name.
+
+## 3. TypeScript: `@adelie/amsp`
+
+```bash
+npm install @adelie/amsp
+```
+
+The client has no dependencies and runs in Node 24 and in current browsers. If your registry does not have the package, call the API over HTTP as in section 4.
+
+```ts
+import { AgentClient, parseArguments } from "@adelie/amsp";
+
+const apiKey = process.env.ADELIE_AGENT_KEY;
+if (!apiKey) throw new Error("Set ADELIE_AGENT_KEY to the key from the agent's API tab.");
+
+const client = new AgentClient({
+  baseUrl: process.env.ADELIE_AGENT_URL ?? "http://localhost:7364/api/amsp/v1",
+  agent: "demo/coder", // <projectId>/<agentId>
+  apiKey, // the client reads no environment variable itself
+});
+
+// One question, the whole answer.
+const first = await client.ask({ input: "Summarize README.md" });
+if (first.status !== "completed") throw new Error(`${first.status}: ${first.error?.message ?? ""}`);
+console.log(first.text);
+
+// The same conversation, streamed: pass its Session id back.
+const run = client.run({
+  sessionId: first.sessionId,
+  input: "Now list its headings",
+  onApproval: (request) => {
+    const args = parseArguments(request.tool_call);
+    return request.tool_call.name === "exec_command" && args?.command === "ls" ? "allow" : "deny";
+  },
+});
+for await (const event of run) {
+  // An event without `origin` is the main conversation's; a subagent's events carry one.
+  if (event.type === "text.delta" && !event.origin) process.stdout.write(event.text);
+}
+const second = await run.result();
+```
+
+- `ask()` runs to the end and resolves with the result: `status`, `error`, `sessionId`, `text` (the main conversation's answer), `items`, `usage`, `sessionUsage` and `requests`. `run()` starts the run and returns it at once: iterate it once for the events, await `run.session` for the Session id, and `run.result()` for the end.
+- **Conversations.** Keep one `sessionId` per conversation of the program, such as one per end user or chat thread, and pass it back to continue. Omit it to start a new conversation. Only the Agent's own API conversations can be continued.
+- **Approvals.** `onApproval` is called only when the approval mode makes a call wait. Without it, or when it throws, the client answers `deny`. A person can answer the same request in the Web App; the first answer counts.
+- **Aborting.** Abort the `signal` passed to `run()` or `ask()` to drop the connection: the server aborts the run. `run.abort()` asks the server to abort and still delivers the final `run.done`, with `status: "aborted"`.
+- **Failures.** A refusal before the stream starts rejects with `AmspHttpError` (`status`, `code`, `message`; see section 5). After that, `result()` resolves for every run: check `status` (`completed`, `aborted`, `retryable` or `fatal`) and `error`. A stream that breaks before `run.done` rejects with `AmspStreamError`.
+- **Unknown events** are passed through. Switch on `event.type` with a default branch.
+- **A web app** keeps the key on its own server. The page posts to the app's server, which runs the Agent and relays the `text.delta` events to the page over SSE, aborting through `signal` when the page disconnects: the shape of the RAG recipe's `server.ts`. A key inside a page is readable by everyone who loads the page.
+
+## 4. Any language: HTTP and curl
+
+```bash
+BASE="${ADELIE_AGENT_URL:-http://localhost:7364/api/amsp/v1}"
+
+# Start a conversation. The answer streams back as it is produced.
+curl -N "$BASE/agents/demo/coder/runs" \
+  -H "Authorization: Bearer $ADELIE_AGENT_KEY" -H "Content-Type: application/json" \
+  -d '{"input":"Summarize README.md"}'
+
+# Continue it with the session_id that the first event, run.started, carried.
+curl -N "$BASE/agents/demo/coder/runs" \
+  -H "Authorization: Bearer $ADELIE_AGENT_KEY" -H "Content-Type: application/json" \
+  -d '{"session_id":"<session_id>","input":"Now list its headings"}'
+
+# Answer an approval.requested event while its run is still streaming.
+curl -X POST "$BASE/sessions/<session_id>/approvals/<tool_call_id>" \
+  -H "Authorization: Bearer $ADELIE_AGENT_KEY" -H "Content-Type: application/json" \
+  -d '{"decision":"allow"}'
+```
+
+To read the stream in your own code:
+
+- Each event is one `data: <JSON>` line followed by a blank line. After the last event comes `data: [DONE]`. A line that starts with `:` is a keep-alive comment, sent after 15 seconds of silence: skip it.
+- The first event is `run.started`, with the `session_id`. The last is `run.done`, with `status`, `error` and `usage`. The answer is the assistant `text.done` events without an `origin`, or their `text.delta` fragments as they arrive.
+- Skip every event `type` you do not know.
+- `POST <Base URL>/sessions/<session_id>/abort` aborts a run and keeps its stream open until `run.done`.
+
+## 5. Errors
+
+A request refused before the stream gets an HTTP status and `{"error": {"code": "…", "message": "…"}}`. Once the stream has started, `run.done` carries the error instead.
+
+| Status | `code` | Usually | What to do |
+| --- | --- | --- | --- |
+| 400 | `bad_request` | A malformed body | The message names the field |
+| 401 | `unauthorized` | No key, a wrong or deleted key, or `127.0.0.1` in the Base URL | Check `ADELIE_AGENT_KEY` and that the Base URL uses `localhost` |
+| 403 | `agent_api_disabled` | The administrator turned the Agent API off | Ask the user to have an administrator turn it on |
+| 404 | `agent_not_found` | API access is off, the Agent ID is wrong, or the key belongs to another Agent | Check with `penguin agent api status`, then ask the owner |
+| 404 | `session_not_found` | The `session_id` is not one of this Agent's API conversations | Start a new conversation |
+| 409 | `task_in_progress`, `compacting` | The conversation is still busy | Wait for its `run.done`: one run per conversation at a time |
+| 429 | `too_many_runs` | The Agent already has 4 API runs going | Retry after `Retry-After` seconds |
+
+## 6. Verify before you hand over
+
+1. `penguin agent api status --agent-id <agentId> --json` shows `api.enabled` true and at least one key.
+2. The key is in your environment: `test -n "$ADELIE_AGENT_KEY" && echo set`. Never print the value.
+3. Run the program once with a real input. The run ends with `status` `completed`, and the answer appears.
+4. Tell the user where to find the conversation: the Agent's **Background** folder in the sidebar, marked with the API icon.
+
+When step 1 or 2 is not done, finish the program anyway, report it as **unverified**, and end your reply with the owner's steps from section 1. Report the files with relative paths, how to run the program, the Agent ID it calls, the approval mode it expects, and your assumptions.

package/skills/unified-llm-api/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: unified-llm-api
+description: Call model APIs through @prismshadow/agenthub — streaming text generation, image generation, speech synthesis, embeddings and the supported-model registry with one client.
+---
+
+# Unified LLM API (AgentHub)
+
+`@prismshadow/agenthub` is a unified TypeScript client for model APIs: streaming text, image generation, speech synthesis and embeddings behind one entry point.
+
+```bash
+npm install @prismshadow/agenthub
+```
+
+The main entry point is `AutoLLMClient`:
+
+```ts
+import { AutoLLMClient } from "@prismshadow/agenthub";
+
+const client = new AutoLLMClient({ model: "<model_id>", apiKey: "<key>", baseUrl: "<url>", clientType: "<type>" });
+```
+
+`apiKey`, `baseUrl` and `clientType` are optional (see routing below). The package also exports `listSupportedModels` (the model registry) and the error classes `AgentHubError`, `UnsupportedParameterError`, `EmptyResponseError` and `ToolCallArgumentParseError`.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use agenthub-models skill") without a concrete task, ask the user what they want to build. Do not write code until the requirement is clear.
+
+**Important prerequisite — set the key up first, then develop.** When the script is an AI app you are building for the user, have them add the model API key in **this agent's key vault** (gear icon on its card, Agents page → settings → key vault tab) *before* you start, so the credential is in your shell environment. If the app stores its own model config, keep its Penguin data root **inside the CWD workspace** (`--root ./penguin_data`), never `~/.adelie`. Model ids can come from the penguin CLI catalog and the id table below.
+
+Check for a usable API key before writing code — the client needs one for whichever provider you target:
+
+```bash
+env | grep -oE "(DEEPSEEK|OPENAI|ANTHROPIC|GEMINI|ZAI|MOONSHOT|MINIMAX)_API_KEY" || echo none
+```
+
+Vault keys also appear in your Vault Keys section. **Only two sources count as a usable key**: a vault-injected environment variable (the check above), or — when the app stores its own model config — a key already configured in the app's own data root (`penguin config model list --root <data_dir>`). Keys living in the global `~/.adelie` or any other `.adelie` directory do **not** count — a bare `penguin config model list` (no `--root`) reads the global store, because the CLI defaults to the global root unless `--root` is given, so a key showing up there proves nothing for your script and must never be used or copied.
+
+If neither counted source yields a usable key, **stop immediately and ask the user to configure one — do not write code, and do not keep calling tools to retry**: ask them to add one in the agent's **key vault** (gear icon on the agent's card, Agents page → settings → key vault tab); vault values reach your shell environment on the next task. Re-checking the environment or the vault in a loop just wastes turns — one clear check, then hand back to the user.
+
+Keep model API keys **project-local**: for an app that stores its own model config, write the key into the project under the working directory with the penguin CLI, **always passing `--root <data_dir>` for a directory inside the current working directory** (`penguin config model add --root ./penguin_data --provider <group> --model-id <id> --api-key <key>`) — without `--root` it writes to the global `~/.adelie/data` instead. `--provider` is required alongside `--model-id`: a model entry is the `(provider, model_id)` pair and the group is never inferred (use `custom` for an endpoint outside the built-in groups). Otherwise rely on vault-injected environment variables. Never read, copy or fall back to model keys stored in the user's global `~/.adelie` directory — that config belongs to the person running Penguin, not to your script.
+
+## Model IDs
+
+Use exact model ids. If an id is not in the table below and the user has not given one, ask the user to confirm the exact id before writing code.
+
+| Family           | Official IDs                                                          | Gateway variants                                                                                                                                |
+| ---------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Gemini 3.8       | `gemini-3.8-flash`                                                    | OpenRouter `google/gemini-3.8-flash`                                                                                                            |
+| Gemini 3.7       | `gemini-3.7-flash`                                                    | OpenRouter `google/gemini-3.7-flash`                                                                                                            |
+| Gemini 3.6       | `gemini-3.6-flash`, `gemini-3.5-flash-lite`                           | —                                                                                                                                               |
+| Gemini 3         | `gemini-3.1-pro-preview`, `gemini-3.5-flash`, `gemini-3.1-flash-lite` | —                                                                                                                                               |
+| Gemini 3 image   | `gemini-3.1-flash-image`, `gemini-3-pro-image-preview`                | —                                                                                                                                               |
+| Gemini 3 TTS     | `gemini-3.1-flash-tts-preview`                                        | —                                                                                                                                               |
+| Gemini embedding | `gemini-embedding-2`                                                  | —                                                                                                                                               |
+| Claude 5         | `claude-fable-5`, `claude-opus-5`, `claude-sonnet-5`                  | OpenRouter `anthropic/claude-fable-5`, `anthropic/claude-opus-5`, `anthropic/claude-sonnet-5`                                                   |
+| Claude 4         | `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-opus-4-8`             | OpenRouter `anthropic/claude-opus-4.8`, `anthropic/claude-opus-4.7`                                                                             |
+| GPT-6            | `gpt-6-astra`                                                         | OpenRouter `openai/gpt-6-astra`                                                                                                                 |
+| GPT-5.6          | `gpt-5.6` (routes to sol), `gpt-5.6-terra`, `gpt-5.6-luna`            | OpenRouter `openai/gpt-5.6-sol`, `openai/gpt-5.6-terra`, `openai/gpt-5.6-luna`                                                                  |
+| GPT-5.5 / 5.4    | `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`                  | OpenRouter `openai/gpt-5.5`, `openai/gpt-5.5-pro`, `openai/gpt-5.4`, `openai/gpt-5.4-mini`, `openai/gpt-5.4-nano`, `openai/gpt-5.4-pro`         |
+| OpenAI embedding | `text-embedding-3-small`, `text-embedding-3-large`                    | —                                                                                                                                               |
+| MiniMax M3       | `MiniMax-M3`                                                          | OpenRouter `minimax/minimax-m3`                                                                                                                 |
+| Kimi K3          | `kimi-k3`                                                             | OpenRouter `moonshotai/kimi-k3`                                                                                                                 |
+| Kimi K2.7 Code   | —                                                                     | SiliconFlow `moonshotai/Kimi-K2.7-Code`; Fireworks AI `accounts/fireworks/models/kimi-k2p7-code`                                                |
+| Kimi K2.6        | `kimi-k2.6`                                                           | OpenRouter `moonshotai/kimi-k2.6`; SiliconFlow `Pro/moonshotai/Kimi-K2.6`                                                                       |
+| DeepSeek V4      | `deepseek-flash`, `deepseek-v4-pro`                                   | OpenRouter `deepseek/deepseek-v4.1-flash`, `deepseek/deepseek-v4-pro-0813`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `deepseek/deepseek-v4-flash-0731`, `deepseek/deepseek-v4-flash-vision-exp`; Fireworks AI `accounts/fireworks/models/deepseek-v4p1-flash`, `accounts/fireworks/models/deepseek-v4-pro-0813`, `accounts/fireworks/models/deepseek-v4-flash-0731`; SiliconFlow `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` |
+| GLM 5.3          | `glm-5.3`, `glm-5.3-flash`                                            | OpenRouter `z-ai/glm-5.3`, `z-ai/glm-5.3-flash`                                                                                                 |
+| GLM 5.2          | `glm-5.2`                                                             | OpenRouter `z-ai/glm-5.2`; SiliconFlow `zai-org/GLM-5.2`                                                                                        |
+| GLM 5.1          | `glm-5.1`                                                             | —                                                                                                                                               |
+| Qwen 3.8 Max     | —                                                                     | OpenRouter `qwen/qwen3.8-max`                                                                                                                   |
+| Qwen 3.8 Flash   | —                                                                     | Qwen DashScope `qwen3.8-flash`                                                                                                                  |
+| Qwen 3.6         | —                                                                     | OpenRouter `qwen/qwen3.6-35b-a3b`; SiliconFlow `Qwen/Qwen3.6-35B-A3B`                                                                           |
+| Inkling          | —                                                                     | OpenRouter `thinkingmachines/inkling`; Fireworks AI `accounts/fireworks/models/inkling`                                                         |
+
+The image endpoint dropped its preview suffix: `gemini-3.1-flash-image-preview` is deprecated, use `gemini-3.1-flash-image`.
+
+`glm-5.3-flash` is the one GLM model that reads images (`@prismshadow/agenthub` >= 0.4.8). The GLM client sends an `image_url` item as an `image_url` part, in a prompt and in a tool result alike, and both an HTTP(S) URL and a base64 data URL pass through unchanged. The version match is case-insensitive, so the gateway spellings `z-ai/glm-5.3-flash` and `zai-org/GLM-5.3-Flash` are recognised too. Every other GLM id refuses an image rather than dropping it — `GLM <id> does not support image inputs.` in a prompt, `GLM <id> does not support images in tool results.` in a tool result — and that includes `glm-5v-turbo`.
+
+Gateway model lists can be queried online:
+
+```bash
+curl https://openrouter.ai/api/v1/models
+curl --request GET --url https://api.siliconflow.cn/v1/models --header 'Authorization: Bearer <token>'
+```
+
+## Supported-model registry
+
+`listSupportedModels(currency?)` returns the models AgentHub itself knows how to route, so ids, endpoints, modalities, context windows and prices can be read from the package instead of being hardcoded:
+
+```ts
+import { listSupportedModels } from "@prismshadow/agenthub";
+
+for (const m of listSupportedModels()) {
+  console.log(m.model, m.base_url, m.client, m.context_window, m.pricing?.prompt_tokens);
+}
+```
+
+- Each `SupportedModel` is `{ model, base_url, client, input_modalities, output_modalities, context_window?, pricing? }`. The `(model, base_url, client)` triple maps straight onto the constructor: `new AutoLLMClient({ model, baseUrl: base_url, clientType: client })`.
+- Modalities are `"Text" | "Image" | "Video" | "Audio" | "Embed"`. Coverage includes the official vendor endpoints plus the OpenRouter and SiliconFlow gateways; `context_window` and `pricing` are omitted where the platform publishes no authoritative value (image and TTS models, for instance).
+- `pricing` is per million tokens, keyed by the same usage buckets as `usage_metadata`: `prompt_tokens` (non-cached input), `thoughts_tokens` / `response_tokens` (both the output price) and optional `cached_tokens` (cache-hit price). Values are stored in USD; pass `listSupportedModels("CNY")` to convert at 7 CNY/USD.
+
+The registry is the curated current line-up, so prefer it when picking a model or estimating cost. It is not the routing table, and it lags in both directions: older ids in the table above (`gpt-5.4`, `claude-opus-4-7`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite`) still route fine without appearing in it, and a newly launched id can route before the registry carries it. For an id the registry omits, take the context window and price from the vendor's own page.
+
+## Routing and credentials
+
+- Without `clientType`, the client auto-routes by model id substring, in this order: `minimax-m3` (exact), `gemini-3*` / `gemini-embedding`, `claude` 4-6/4-7/4-8/-5, `gpt-5.4`/`gpt-5.5`/`gpt-5.6`/`gpt-6`, `glm-5` (whole series, 5.3 included), `kimi-k3`/`kimi-k2.5`/`kimi-k2.6`, `deepseek-v4`, `ant-messages`, `openai-responses`, `openai`+`embedding` (embeddings), `openai` (chat). Ids matching none of these throw. Most gateway variants in the table above hit the same substrings, so they route to the right family — just set `baseUrl` to the gateway endpoint.
+- Three generic protocol clients cover everything else (all take `baseUrl` + `apiKey`):
+  - `clientType: "openai-chat"` — any OpenAI Chat Completions compatible endpoint (gateway models, Qwen via OpenRouter/SiliconFlow or DashScope `https://dashscope.aliyuncs.com/compatible-mode/v1`, local vLLM, …). Renamed from `openai` in AgentHub 0.4.2; the bare `openai` string still routes as a deprecated alias.
+  - `clientType: "openai-responses"` — OpenAI Responses-compatible endpoints (OpenAI, OpenRouter, DeepSeek, Z.AI, MiniMax all serve one).
+  - `clientType: "ant-messages"` — Anthropic Messages-compatible endpoints (Anthropic, OpenRouter `https://openrouter.ai/api`, DeepSeek `https://api.deepseek.com/anthropic`, Z.AI, MiniMax).
+- Exception: an id served by an OpenAI-compatible gateway that still matches a first-party substring (e.g. OpenRouter's `google/gemini-3.7-flash`, `anthropic/claude-sonnet-5` or `openai/gpt-5.6-sol` on the `/api/v1` endpoint) would auto-route to the vendor protocol client — and a dotted id like `anthropic/claude-opus-4.8` matches nothing and throws. Always pass an explicit `clientType` for gateway ids; never rely on the id. Routing reads `clientType` (or the model id) as a plain lowercased string and never looks at `baseUrl`, so the vendor prefix gives no protection.
+- OpenRouter serves both protocols at `https://openrouter.ai/api/v1`, for every upstream it resells and not just its `openai/*` ids, so any id it serves works with `clientType: "openai-responses"` as well as `"openai-chat"`; use Responses when you want reasoning items round-tripped.
+- The first-party `deepseek-v4` client posts to `{baseUrl}/responses` (AgentHub 0.4.6 moved it off Chat Completions). A self-hosted endpoint serving a `deepseek-v4*` id over Chat Completions must therefore pass `clientType: "openai-chat"` explicitly rather than rely on id routing.
+- API key: constructor parameter first, then the provider environment variable — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY` (also for `ant-messages`), `OPENAI_API_KEY` (also for `openai-chat`/`openai-responses`), `GEMINI_API_KEY`, `ZAI_API_KEY`, `MOONSHOT_API_KEY`, `MINIMAX_API_KEY`. Base URLs read the same names with `_BASE_URL`.
+
+## Streaming text
+
+```ts
+for await (const event of client.streamingResponseStateful({
+  message: { role: "user", content_items: [{ type: "text", text: "Hello" }] },
+  config: {},
+})) {
+  for (const item of event.content_items) {
+    if (item.type === "text") process.stdout.write(item.text);
+  }
+}
+```
+
+- Each `event` is a `UniEvent`: `event_type` is `start` | `delta` | `stop`, and `content_items` carry the increments.
+- `config` accepts `max_tokens`, `temperature`, `system_prompt`, `thinking_level` (the `ThinkingLevel` enum, `NONE` to `MAX`), `tool_choice`, `prompt_caching`, `fast_mode` and `tools`.
+- `streamingResponseStateful` keeps conversation history inside the client; manage it with `getHistory()` / `setHistory(history)` / `clearHistory()`. The stateless variant is `streamingResponse({ messages, config })`.
+
+## Config parameters the model may reject
+
+A config value the target client cannot honour throws `UnsupportedParameterError` (an `AgentHubError` carrying `client` and `parameter`) while building the request, before anything reaches the network:
+
+```ts
+import { UnsupportedParameterError } from "@prismshadow/agenthub";
+
+try {
+  // ...
+} catch (err) {
+  if (err instanceof UnsupportedParameterError) console.error(err.parameter, err.message);
+}
+```
+
+- `thinking_level` never throws: every client maps each level onto the closest one the model supports, and `MAX` (the tier above `XHIGH`, added in AgentHub 0.4.4) degrades silently wherever the vendor has no such tier — Gemini and MiniMax M3 stop at `high`. Kimi K3 reasons unconditionally, so `NONE` degrades to its lowest effort rather than disabling thinking; GLM-5.2 sends `reasoning_effort` alongside its `thinking` block and only `NONE` disables it. GLM-5.3 thinks unconditionally (`NONE` degrades to the light `low` effort) and clamps `reasoning_effort` to `low`/`high`/`max`; `gemini-3.7-*` clamps to `low`/`medium`/`high` (`NONE` degrades to `low`). DeepSeek V4 accepts `low`/`high`/`max` and maps `medium` and `xhigh` onto `high` server-side, so since 0.4.4 `LOW` sends `low` (it sent `high`) and `XHIGH` sends `high` (it sent `max`).
+- `temperature` is rejected outright by Gemini 3.6/3.7 — those generations deprecated the sampling parameters, so the client refuses them instead of sending a value the API ignores. GPT-5.5/5.6, the whole Claude 4.6+ family (4.6 included since AgentHub 0.4.2), DeepSeek V4, Kimi K2.6 and Kimi K3 accept only the protocol default `1.0` and reject any other value. Gemini 3, GLM and the generic protocol clients (`openai-chat` / `openai-responses` / `ant-messages`) pass it through.
+- `tool_choice`: `"auto"` is safe everywhere. Claude accepts a single forced tool name; DeepSeek V4 and Kimi K2.6 allow `"auto"` / `"none"`; Kimi K3 adds `"required"` but refuses a specific tool (K2.x also rejects `"required"`); GLM only accepts `"auto"`.
+- `prompt_caching`: every client accepts `PromptCaching.ENABLE` and rejects the other values — caching is on by default and Kimi K3 caches context automatically.
+- `fast_mode` (`UniConfig`, AgentHub 0.4.2): fast processing at premium pricing. OpenAI-protocol clients (`openai-chat`, `openai-responses`, `gpt-6`, `minimax-m3`) map it to `service_tier: "priority"`; Anthropic-protocol clients (`ant-messages`, `claude-5`) map it to `speed: "fast"` with a beta header (an Anthropic research preview limited to Claude Opus 5 / Opus 4.8 — organizations without access get a 429). Clients without a fast tier (Gemini, GLM, Kimi, DeepSeek, embeddings, Claude 4.6 models) raise `UnsupportedParameterError`; DeepSeek and Z.AI's OpenAI-compatible endpoints simply ignore the tier.
+
+Leave a parameter unset and the protocol default applies, which is the portable choice when a script must run against several families.
+
+## Image generation
+
+Use a Gemini image model (see Model IDs) and set `config.image_config` (optional `aspect_ratio`, and `image_size` of `"1K"` | `"2K"`):
+
+```ts
+import fs from "node:fs";
+
+const client = new AutoLLMClient({ model: "gemini-3.1-flash-image" });
+for await (const event of client.streamingResponseStateful({
+  message: { role: "user", content_items: [{ type: "text", text: "A penguin on a glacier" }] },
+  config: { image_config: { aspect_ratio: "16:9", image_size: "2K" } },
+})) {
+  for (const item of event.content_items) {
+    if (item.type === "inline_data") fs.writeFileSync("image.png", item.data);
+  }
+}
+```
+
+Images arrive as `inline_data` content items (`data` is a Buffer, with `mime_type`).
+
+## Speech synthesis
+
+Use a Gemini TTS model (`gemini-3.1-flash-tts-preview`) and set `config.tts_config`:
+
+```ts
+config: { tts_config: [{ voice: "Kore" }] }
+```
+
+- One entry → single voice; two entries → multi-speaker, and each entry must also set `speaker`.
+- The `inline_data` output is raw PCM (24kHz 16-bit mono) — wrap it in a WAV header yourself before saving as `.wav`.
+
+## Embeddings
+
+Two routes:
+
+- Gemini: a model whose id contains `gemini-embedding` auto-routes (`gemini-embedding-2`).
+- Any OpenAI-compatible embeddings endpoint: pass `clientType: "openai-embedding"` (plus `baseUrl` and `apiKey` as needed) — ids like `text-embedding-3-small` / `text-embedding-3-large` match no auto-route substring and would throw without it.
+
+Optional `config.embedding_config`:
+
+```ts
+config: { embedding_config: { dimensions: 768 } }
+```
+
+The output arrives as `embedding` content items (`embedding` is a number array).

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.