@spicyapi/skill 0.1.0 → 0.2.0

package/package.json

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

package/skills/spicyapi/SKILL.md

@@ -25,18 +25,17 @@ integration tests, webhook handling, credential work, or cleanup.
   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. Obtain a quote for the exact request, show its USD
+  estimate and maximum charge, obtain explicit confirmation, and preserve one idempotency key for
+  the entire logical attempt, including recovery from an uncertain response.
 - 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

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

@@ -20,6 +20,7 @@ Plain HTTP base URLs are accepted only for loopback development hosts.
 | 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`                   |
+| 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              |
@@ -30,8 +31,8 @@ Plain HTTP base URLs are accepted only for loopback development hosts.
 | 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.
+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.
 
 ## Generation sequence
 
@@ -39,14 +40,14 @@ paginated.
 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.
+4. Choose the model itself for the required capability; no content-mode flag is needed.
 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.
+7. Quote the identical request with `quoteTask`, `tasks quote`, or `spicyapi_task_quote`; show
+   `estimatedCost`, `maxCharge` and `expiresAt`. Confirm that quote and create with `quoteId` and
+   `expectedCost`. 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
@@ -55,19 +56,19 @@ paginated.
 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. A model ID
+is shaped `<family>/<version>/<task>`, so `family/version/task` shows the shape and nothing more.
+Replace it only with a value returned by the live catalog; never assemble one from a family name, a
+version, or a task you guessed.
 
 ## Uncertain responses and retries
 
@@ -86,10 +87,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);
 ```

package/skills/spicyapi/references/safety.md

@@ -16,24 +16,19 @@
 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.
+2. Quote the exact request and explain its model ID, USD estimate, maximum charge and expiry.
 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