@spicyapi/skill 0.1.0 → 0.2.1

package/README.md

@@ -20,3 +20,8 @@ npx --yes --package=@spicyapi/skill spicyapi-skill path
 Use `--target <absolute-directory>` for Codex, Claude Code, Cursor, or another Agent
 Skills-compatible client when it uses a different skills directory. Use `--force` only when you
 intend to replace that exact destination.
+
+The default workflow reads the selected model's schema once, lets CLI/MCP creation obtain and
+confirm its quote, then uses waiting or a verified webhook and reads ready result URLs directly.
+Health/balance checks, separate price comparisons, and download-link renewal remain available when
+needed. Task creation and retry retain their billable confirmation and idempotency requirements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spicyapi/skill",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Official installable Agent Skill for SpicyAPI",
   "type": "module",
   "license": "MIT",

package/skills/spicyapi/SKILL.md

@@ -21,22 +21,28 @@ integration tests, webhook handling, credential work, or cleanup.
 
 ## Required behavior
 
-- Query the live catalog and fetch the selected model with its input schema before creating a task.
-  Never invent a model ID, price, provider capability, or input field.
+- Obtain the selected model's live input schema once: get a known model, or discover it in the
+  catalog. Reuse a complete record already returned with `includeSchema`; refresh when it is missing
+  or stale. Never invent a model ID, price, provider capability, or input field.
 - Pass the model-specific `input` object through unchanged. The SpicyAPI server owns schema, price,
   balance, operational API-key scope, and routing decisions.
-- Treat `mature` as caller-declared execution metadata. Pass the requested boolean unchanged; the
-  platform does not inspect or gate it by account, API key, model, channel, age, consent, or a
-  content classifier. A selected model service may still refuse under its own behavior, and the
-  customer remains responsible for applicable law, age, consent, and end-user controls.
-- Treat task creation and retry as billable. Obtain explicit confirmation and preserve one
-  idempotency key for the entire logical attempt, including recovery from an uncertain response.
+- Choose model capabilities from the live catalog. No content-mode request flag or platform content
+  review is required.
+- Treat task creation and retry as billable. CLI and MCP creation obtain and confirm the exact quote
+  internally; do not call the separate quote command/tool first unless comparing prices. In SDK
+  code, quote the exact request once, show its USD estimate and maximum charge, confirm it, and pass
+  that quote into creation. Preserve one idempotency key for the entire logical attempt, including
+  recovery from an uncertain response.
+- Health/readiness and balance checks are optional diagnostics, not a per-task checklist. The server
+  validates availability and funds when accepting a task.
+- Use ready `output.assets[].url` directly. A complete verified v2 webhook needs no extra task
+  lookup or download ticket. Query again for pending assets or expired links.
 - Use environment variables for API keys and webhook secrets. Never put them in arguments, source
   code, prompts, logs, support messages, or committed configuration.
 - Preserve `request_id`, task IDs, upload keys, and idempotency keys in operational results. They
   are necessary for reconciliation and support.
-- Do not invent task listing, cancellation, deletion, estimate, or webhook-redelivery calls. They
-  are absent from the public developer contract.
+- Do not invent task listing, cancellation, deletion or webhook-redelivery calls. They are absent
+  from the public developer contract.
 - Keep browser-session identity, payment, privacy, account closure, and admin operations in the
   SpicyAPI Console. Do not emulate cookie/CSRF Console routes in this server-side skill.
 - Provider/model onboarding and production enablement are outside this skill unless the user
@@ -47,7 +53,7 @@ integration tests, webhook handling, credential work, or cleanup.
 When the user asks for a real test, make a real request against the selected environment; do not
 substitute a mock and call it verified. Record every created identifier before continuing. Use the
 smallest user-approved billable scenario that the live catalog actually offers, then verify it
-through task retrieval or waiting.
+through task retrieval, waiting, or a verified terminal webhook containing the result.
 
 Clean up only exact artifacts that the environment exposes a supported deletion mechanism for. The
 public developer API has no task or uploaded-object delete operation, so report those retained

package/skills/spicyapi/references/api-workflows.md

@@ -11,63 +11,113 @@ Set credentials through the process environment or a secret manager:
 
 Plain HTTP base URLs are accepted only for loopback development hosts.
 
+## API key setup and maintenance
+
+Create and manage keys in the SpicyAPI Console, then inject `SPICY_API_KEY` into the SDK, CLI, or
+MCP process. The developer Bearer API does not create, reveal, rotate, or revoke API keys. A new
+plaintext key is shown once; store it in the application's secret manager. Model restrictions, IP
+restrictions, spend caps, expiry, and workspace selection belong in the Console.
+
+For planned rotation, configure and verify a replacement key before revoking the old one. If a key
+has leaked, revoke it promptly in the Console and replace it. Revocation does not cancel tasks
+already accepted. For authentication failures, check the configured environment and the key's
+Console status; for access failures, check its model, IP, and workspace restrictions. Never include
+the credential in a diagnostic message.
+
 ## Verified public surface
 
-| Purpose        | CLI                                     | MCP tool                       | Public route                         |
-| -------------- | --------------------------------------- | ------------------------------ | ------------------------------------ |
-| Service status | `spicyapi status`                       | `spicyapi_service_status`      | `/healthz`, `/readyz`                |
-| Search docs    | `spicyapi docs search [query]`          | `spicyapi_docs_search`         | Bundled first-party index            |
-| List models    | `spicyapi models list --include-schema` | `spicyapi_models_list`         | `GET /models`                        |
-| Get model      | `spicyapi models get <model>`           | `spicyapi_model_get`           | `GET /models/{model}`                |
-| Balance        | `spicyapi balance`                      | `spicyapi_balance_get`         | `GET /chat/credit`                   |
-| Create task    | `spicyapi tasks create ...`             | `spicyapi_task_create`         | `POST /jobs/createTask`              |
-| Get task       | `spicyapi tasks get <task-id>`          | `spicyapi_task_get`            | `GET /jobs/recordInfo`               |
-| Wait for task  | `spicyapi tasks wait <task-id>`         | `spicyapi_task_wait`           | Composes task retrieval              |
-| Retry task     | `spicyapi tasks retry <task-id>`        | `spicyapi_task_retry`          | `POST /jobs/retry`                   |
-| Prepare upload | SDK                                     | `spicyapi_upload_prepare`      | `POST /common/upload-url`            |
-| Upload file    | `spicyapi files upload <path>`          | Keep bytes outside MCP         | Presigned storage `PUT`, then commit |
-| Commit upload  | SDK                                     | `spicyapi_upload_commit`       | `POST /files/{fileId}/commit`        |
-| Output URL     | `spicyapi files download-url <task-id>` | `spicyapi_download_url_create` | `POST /common/download-url`          |
-| Verify webhook | `spicyapi webhooks verify ...`          | Local library/CLI              | No network call                      |
-
-These are the complete public developer operations in the bundled contract. Model listing is not
-paginated.
+| Purpose           | CLI                                                | MCP tool                       | Public route                         |
+| ----------------- | -------------------------------------------------- | ------------------------------ | ------------------------------------ |
+| Service status    | `spicyapi status`                                  | `spicyapi_service_status`      | `/healthz`, `/readyz`                |
+| Search docs       | `spicyapi docs search [query]`                     | `spicyapi_docs_search`         | Bundled first-party index            |
+| List models       | `spicyapi models list --include-schema`            | `spicyapi_models_list`         | `GET /models`                        |
+| Get model         | `spicyapi models get <model>`                      | `spicyapi_model_get`           | `GET /models/{model}`                |
+| Balance           | `spicyapi balance`                                 | `spicyapi_balance_get`         | `GET /chat/credit`                   |
+| Current key usage | `spicyapi usage --from YYYY-MM-DD --to YYYY-MM-DD` | `spicyapi_usage_get`           | `GET /usage`                         |
+| Quote request     | `spicyapi tasks quote ...`                         | `spicyapi_task_quote`          | `POST /jobs/quote`                   |
+| Create task       | `spicyapi tasks create ...`                        | `spicyapi_task_create`         | `POST /jobs/createTask`              |
+| Get task          | `spicyapi tasks get <task-id>`                     | `spicyapi_task_get`            | `GET /jobs/recordInfo`               |
+| Wait for task     | `spicyapi tasks wait <task-id>`                    | `spicyapi_task_wait`           | Composes task retrieval              |
+| Retry task        | `spicyapi tasks retry <task-id>`                   | `spicyapi_task_retry`          | `POST /jobs/retry`                   |
+| Prepare upload    | SDK                                                | `spicyapi_upload_prepare`      | `POST /common/upload-url`            |
+| Upload file       | `spicyapi files upload <path>`                     | Keep bytes outside MCP         | Presigned storage `PUT`, then commit |
+| Commit upload     | SDK                                                | `spicyapi_upload_commit`       | `POST /files/{fileId}/commit`        |
+| Renew output URL  | `spicyapi files download-url <task-id>`            | `spicyapi_download_url_create` | `POST /common/download-url`          |
+| Verify webhook    | `spicyapi webhooks verify ...`                     | Local library/CLI              | No network call                      |
+
+These are the focused media-task SDK, CLI and MCP operations. The bundled OpenAPI also documents
+`/v1` text/video compatibility and `/jobs/stream`. Model listing is not paginated.
+
+## Current API key usage
+
+Use `spicyapi_usage_get` (or CLI `usage`) when asked for task usage and settled spending. Only
+optional `from` and `to` dates are accepted; do not add user, key, or workspace selectors. The
+configured API key determines scope. Dates use UTC `[from,to)`, including the start and excluding
+the end, for at most 92 days. The default `to` is tomorrow UTC and `from` is seven days before it.
+Counts are attributed to task creation day. `totalSpend` and each `spend` are exact decimal USD
+strings for settled actual charges, excluding pending holds; late settlement can revise earlier
+days. This is not remaining balance or API-key budget. It is not a generation precheck. Respect
+`Retry-After` if reporting is rate limited; do not query each day separately when one range
+suffices.
 
 ## Generation sequence
 
-1. Check readiness and authenticated balance.
-2. List models with `--include-schema` and get the exact candidate model.
-3. Build only the `input` object described by the returned live schema. Preserve unknown future
-   fields rather than remapping them.
-4. If the caller requests mature execution, send `mature: true` unchanged. It is recorded and
-   forwarded as execution metadata; it is not checked against an account, API key, catalog label,
-   channel, or platform content classifier. The selected model service may still refuse.
-5. Upload local media first when the model input requires a hosted asset. Use the returned committed
-   file reference exactly as the model schema specifies.
-6. Choose one idempotency key for the logical creation attempt.
-7. Confirm the current action and create the task. CLI confirmation is interactive unless `--yes` is
-   explicitly supplied; MCP uses protocol elicitation.
-8. Save the returned task ID, request ID when present, and idempotency key.
-9. Poll with `tasks wait`, or retrieve the task after a signed terminal webhook.
-10. Create a short-lived download URL for a successful task output. Do not persist the presigned URL
-    as a durable asset identifier.
+1. Use the selected model's live input schema. Get a known model directly, or discover models first.
+   If a list response already includes its full schema, reuse it instead of fetching it again.
+2. Build only the `input` described by that schema. Pass supported public HTTPS media URLs directly;
+   upload local files with SDK `uploadFile` or CLI `files upload` and use the committed `spicy://`
+   URI.
+3. Preserve one idempotency key for the logical creation attempt. CLI `tasks create` and MCP
+   `spicyapi_task_create` obtain the exact quote and request confirmation internally. Do not run
+   `tasks quote` or `spicyapi_task_quote` first unless comparing prices independently. SDK code
+   obtains one quote, shows `estimatedCost`, `maxCharge` and `expiresAt`, then sends its `quoteId`
+   and `expectedCost` with the unchanged confirmed request. CLI `--yes` is explicit noninteractive
+   authorization; it does not remove the price confirmation bound into the request. MCP retains
+   protocol elicitation and signed request state.
+4. Save the accepted task ID, request ID when present, and idempotency key. Use a verified webhook
+   for a production receiver, or bounded waiting with `tasks create --wait` / `spicyapi_task_wait`.
+   A complete verified v2 webhook already contains the task result; no extra lookup is required.
+5. Use ready `output.assets[].url` directly, without attaching the SpicyAPI key. Query the same task
+   again when assets are pending or URLs expire. Save a durable copy in storage the user controls; a
+   temporary URL is not a durable asset identifier.
+
+Health/readiness and balance tools are for explicit status requests or diagnostics, not
+prerequisites for generation. The server validates availability and funds at acceptance. The
+separate quote tool is useful for price comparisons; download-url remains available for legacy
+clients and explicit link renewal. A v1 callback or an incomplete payload may require task
+retrieval. Choose webhook or waiting as the normal completion path instead of running both
+routinely.
 
 Example CLI shape, after inspecting the live schema:
 
 ```bash
-spicyapi --json models get provider/model
+spicyapi --json models get family/version/task
 spicyapi --json tasks create \
-  --model provider/model \
+  --model family/version/task \
   --input-file ./input.json \
-  --mature \
   --idempotency-key 7b5a89dd-1ec3-4ec8-8246-6c76cc863665 \
   --yes \
   --wait
 ```
 
-The model and fields above are structural placeholders, not claims that a model exists. Replace them
-only with values returned by the live catalog. Omit `--mature` when the caller did not request that
-execution mode.
+The model and fields above are structural placeholders, not claims that a model exists. Replace the
+placeholder only with a value returned by the live catalog; never assemble a model ID from a
+publisher, family name, version, or task you guessed.
+
+## Discovery and bounded batches
+
+The model list is not paginated: do not invent cursor, page, or next-page calls. Narrow discovery
+with `search`, `modality`, `task`, or the public model creator in `provider`. Fetch schema and
+examples only when needed; an existing complete selected-model record can serve multiple inputs. Use
+enum values, required fields, defaults, ranges, and examples from that record, without changing an
+uploaded reference or guessing an unsupported parameter.
+
+There is no batch-create API. For an authorized batch, reuse the selected schema, bound the number
+of concurrent requests, and assign one persistent idempotency key per item. Each different input
+requires its own exact quote and authorized charge; a schema cache is not a price lock. Record each
+accepted task ID as it arrives, handle each result separately, and respect `Retry-After` on rate
+limits. Do not submit the entire batch again because one item timed out. Keep file bytes outside
+MCP; use the upload helper or CLI for local media.
 
 ## Uncertain responses and retries
 
@@ -77,8 +127,18 @@ execution mode.
   merely because the first response was uncertain.
 - A task retry creates a new task and may reserve funds again. It is valid only for server-accepted
   source states such as `failed` or `expired`; the server remains authoritative.
-- Use `request_id` and `Retry-After` metadata from structured errors. Do not expose the API key
-  while reporting an error.
+- Once a task ID is known, continue waiting or retrieve that task; a local timeout does not cancel
+  it. Do not call task retry merely to resume waiting.
+- Business code `40901` means the price confirmation needs attention: obtain a fresh exact quote and
+  confirm it. Do not silently discard `quoteId` or `expectedCost`. An idempotency conflict is
+  different: keep the original request associated with its key instead of overwriting it.
+- After input-validation errors, correct fields against the selected live schema; after insufficient
+  funds, use the Console or inspect balance. Repeatedly sending the same rejected request is not
+  recovery.
+- Inspect `state` after get/wait; successfully retrieving a task does not mean generation succeeded.
+  Only claim usable media when the asset has a ready URL; pending assets require another lookup.
+- Use `request_id` when available and `Retry-After` metadata from structured errors. Do not expose
+  the API key while reporting an error.
 
 ## SDK outline
 
@@ -86,10 +146,15 @@ execution mode.
 import { SpicyClient } from "@spicyapi/sdk";
 
 const client = new SpicyClient();
-const model = await client.getModel("live/catalog-id");
+const model = await client.getModel("family/version/task");
+const payload = { model: model.model, input: {/* fields from model.inputSchema */} };
+const quote = await client.quoteTask(payload);
+console.log(quote.estimatedCost, quote.maxCharge, quote.expiresAt);
+// 在用户确认这份报价后继续；持久化同一幂等键以恢复响应丢失。
+const idempotencyKey = crypto.randomUUID();
 const accepted = await client.createTask(
-  { model: model.model, input: {/* fields from model.inputSchema */} },
-  { idempotencyKey: crypto.randomUUID() },
+  { ...payload, quoteId: quote.quoteId, expectedCost: quote.estimatedCost },
+  { idempotencyKey },
 );
 const terminal = await client.waitForTask(accepted.taskId);
 ```
@@ -105,4 +170,20 @@ taskId.timestamp.hex(sha256(raw_body))
 
 Payload version 1 reads `task_id`; version 2 reads `data.taskId`. Perform constant-time signature
 comparison before checking timestamp tolerance. For v2, use `request_id` as the stable delivery
-identifier when present.
+identifier when present. Read ready `data.output.assets[].url` directly from a complete verified v2
+payload. Only retrieve the task if the payload is incomplete, assets are pending, or the URL has
+expired. Delivery retries can refresh URLs while retaining the same `request_id`; deduplicate by
+that identifier rather than hashing the whole body. Never send the SpicyAPI key when downloading a
+signed asset URL.
+
+## Recover task history
+
+Use `client.listTasks`, `spicyapi tasks list`, or read-only `spicyapi_tasks_list` to find
+current-key tasks after a restart or missed callback. Results contain metadata only. Pass fixed UTC
+`from`/`to` dates and unchanged state/model filters while following `nextCursor`; use the
+task-detail tool only for a selected result. Defaults are seven days and 20 items; limits are 92
+days and 100 items.
+
+This is a recovery tool, not a mandatory generation preflight. If acceptance of a submitted request
+is uncertain, first retry unchanged input with its original Idempotency-Key. An empty page is not
+proof that no task was accepted and must not trigger a second billable submission with a new key.

package/skills/spicyapi/references/safety.md

@@ -15,25 +15,23 @@
 
 Task creation and retry can reserve funds. Before execution:
 
-1. Fetch the live model record and balance.
-2. Explain the exact model ID and that live price, operational API-key scope, balance, and routing
-   are decided on acceptance.
+1. Use the selected model's live schema; reuse a complete record already read in this workflow.
+   Check balance only when requested or diagnosing funds. The server enforces funds at acceptance.
+2. Explain the exact request's model ID, USD estimate, maximum charge and expiry. CLI and MCP create
+   obtain the quote internally; do not quote separately first. SDK code obtains one quote and passes
+   it unchanged into creation after confirmation.
 3. Obtain explicit user confirmation, unless the user's current request already explicitly
    authorizes that exact billable test.
 4. Mint or preserve one idempotency key and surface it to the user.
 
 Decline, cancellation of confirmation, schema mismatch, or missing confirmation must result in zero
-API calls.
+billable create calls; a read-only quote may already have been fetched.
 
-## Mature request metadata
+## Model capabilities
 
-- `mature` is a caller-declared request value, not an account or API-key entitlement.
-- Forward the boolean unchanged. Do not preflight it against the catalog capability, selected
-  channel, age, consent, or a platform content policy, and do not claim the platform approved it.
-- A model service may still return its own refusal. Report that observed task failure normally;
-  never invent a platform gate or retry under a different mode without user direction.
-- Applicable legal, age, consent, real-person, and end-user access responsibilities remain with the
-  customer and are not established by technical success.
+Select the model that supports the intended use. SpicyAPI does not require a content-mode flag or
+perform per-request content review. A model can still fail according to its own implementation;
+report the observed normalized failure.
 
 ## Real integration tests