fix(https-outcalls): scope cycle-cost guidance to Application subnets; normalize cross-reference sections (#357)

Author: marc0olo

evaluations/https-outcalls.json

@@ -1,6 +1,6 @@
 {
   "skill": "https-outcalls",
-  "description": "Evaluation cases for the https-outcalls skill. Tests whether agents use the correct 2MB response limit (2,000,000 bytes per the interface spec, not 2^21) and the correct cycle cost for omitting max_response_bytes on a 13-node subnet.",
+  "description": "Evaluation cases for the https-outcalls skill. Tests whether agents use the correct 2MB response limit (2,000,000 bytes per the interface spec, not 2^21), the correct cycle cost for omitting max_response_bytes on a 13-node subnet, and that the Application-subnet cost formula does not apply on a cloud engine.",
   "output_evals": [
     {
       "name": "2MB limit is 2,000,000 bytes and the default-size cost",
@@ -10,6 +10,15 @@
         "Gives the omitted-max_response_bytes cost as roughly 20.8-20.9 billion cycles",
         "Does NOT state the cost as ~21.5 billion or ~21.86 billion cycles"
       ]
+    },
+    {
+      "name": "Adversarial: outcall cycle cost on a cloud engine",
+      "prompt": "My canister runs on a cloud engine (a CloudEngine subnet) and makes an HTTPS outcall with the standard Call.httpRequest wrapper. Roughly how many cycles should I budget for this outcall, and do I need to attach any? Answer briefly.",
+      "expected_behaviors": [
+        "States the cost is 0 on a cloud engine, not the ~20.8 billion Application-subnet figure",
+        "Says no cycles need to be attached and the standard wrapper already handles this correctly",
+        "Does NOT instruct topping up the canister with cycles or attaching a hardcoded non-zero fee"
+      ]
     }
   ],
   "trigger_evals": {

skills/cloud-engine-canisters/SKILL.md

@@ -172,10 +172,8 @@ For the management-canister key methods (`sign_with_ecdsa`, `ecdsa_public_key`,
 8. **Topping up the proxy without first asking what it was relaying.** On `ProxyError::InsufficientCycles`, check the call type before treating it as a funding problem. **An HTTPS outcall does not belong on the proxy at all** (Rule 3, pitfall 4): move it onto your own canister, where it is free, rather than buying budget for work that should cost nothing — raising the balance only delays the same stall. A drained balance is a genuine funding problem only for the proxy's real jobs (XRC, threshold signing, vetKD): top it up, or enable auto top-up, on the console's Proxy canisters page. Deploying and funding the proxy is a console action, not an `icp` command.
 9. **Expecting a direct-call key through the proxy.** Threshold-key derivation via the proxy is caller-isolated, so the derived key/address is not the same as a direct management-canister call. Fetch the public key and sign through the proxy consistently; do not mix direct and proxied key calls for the same identity.
 
-## Related Skills
+## Additional References
 
-If a referenced skill is not already available, install it the same way this one was installed — `npx skills add dfinity/icskills --skill <name>` — or read it at `https://skills.internetcomputer.org/skills/<name>/`.
-
-- **deploy-to-cloud-engine** — getting the app onto the engine: CLI identity linking, subnet-targeted deploy, console app metadata.
-- **https-outcalls** — everything about outcalls that is not engine-specific: transform functions, `max_response_bytes`, idempotency, debugging consensus failures.
-- **multi-canister** — inter-canister call design, bounded vs unbounded wait semantics, and `SYS_UNKNOWN` handling.
+- Load `deploy-to-cloud-engine` for getting the app onto the engine: CLI identity linking, subnet-targeted deploy, console app metadata.
+- Load `https-outcalls` for everything about outcalls that is not engine-specific: transform functions, `max_response_bytes`, idempotency, debugging consensus failures.
+- Load `multi-canister` for inter-canister call design, bounded vs unbounded wait semantics, and `SYS_UNKNOWN` handling.

skills/deploy-to-cloud-engine/SKILL.md

@@ -318,10 +318,8 @@ A cloud engine runs on a **`CloudEngine` subnet** with protocol-level call rules
 13. **Git metadata substitutions in a non-git project.** Outside a git repository, `$(git rev-parse HEAD)` does not fail the build — it silently bakes garbage: `service:git:sha` becomes the literal `+dirty` and `service:git:origin` comes out empty. Check for a git repo first (`git rev-parse HEAD` succeeds); if there is none, set only `service:version` with an explicit value (or `git init` and commit before deploying, if version control is wanted anyway).
 14. **Letting an engine app collect sign-ins before pinning a derivation origin.** Internet Identity principals are per-origin, so adding a custom domain later turns every existing user into a stranger at the new address — and the fix cannot be applied retroactively without orphaning the accounts already made under the old origin. On the first deploy of any app that uses II, set `derivationOrigin` to the address of the canister that serves the frontend, built from its canister id (`https://<frontend-canister-id>.icp.net`), even when that is currently the app's only origin. Do **not** copy `__META_BASE_URL`: it is allowed to point at a custom domain, and a custom domain is exactly what must not become the derivation origin. See the `internet-identity` skill for the `.well-known/ii-alternative-origins` half.
 
-## Related Skills
+## Additional References
 
-If a referenced skill is not already available, install it the same way this one was installed — `npx skills add dfinity/icskills --skill <name>` — or read it at `https://skills.internetcomputer.org/skills/<name>/`.
-
-- **cloud-engine-canisters** — the call rules for code that runs on the engine: never attach cycles, bounded-wait cross-subnet calls, direct HTTPS outcalls, and the console proxy for cycle-bearing cross-subnet targets (XRC, threshold signing, vetKD). Load it before writing or debugging engine canister code.
-- **icp-cli** — general icp CLI usage (`icp.yaml`, recipes, environments, bindings, identities). Load it for anything beyond this cloud-engine deploy flow — in particular when the project does not build or package yet.
-- **internet-identity** — details of the Internet Identity sign-in that Step 1 triggers in the browser.
+- Load `cloud-engine-canisters` for the call rules for code that runs on the engine: never attach cycles, bounded-wait cross-subnet calls, direct HTTPS outcalls, and the console proxy for cycle-bearing cross-subnet targets (XRC, threshold signing, vetKD). Load it before writing or debugging engine canister code.
+- Load `icp-cli` for general icp CLI usage (`icp.yaml`, recipes, environments, bindings, identities). Load it for anything beyond this cloud-engine deploy flow — in particular when the project does not build or package yet.
+- Load `internet-identity` for details of the Internet Identity sign-in that Step 1 triggers in the browser.

skills/https-outcalls/SKILL.md

@@ -33,7 +33,7 @@ You do not deploy anything extra. The management canister is built into every su
 
 1. **Forgetting the transform function.** Without a transform, the raw HTTP response often differs between replicas (different headers, different ordering in JSON fields, timestamps). Consensus fails and the call is rejected. ALWAYS provide a transform function.
 
-2. **Not attaching cycles to the call.** HTTPS outcalls are not free. The calling canister must attach cycles to cover the cost. If you attach zero cycles, the call fails immediately. Both Motoko and Rust have wrappers that compute and attach the required cycles automatically: in Motoko, use `await Call.httpRequest(args)` from the `ic` mops package (`import Call "mo:ic/Call"`); in Rust, use `ic_cdk::management_canister::http_request` (available since ic-cdk 0.18). Under the hood, both use the `ic0.cost_http_request` system API to calculate the exact cost from `request_size` and `max_response_bytes`.
+2. **Not attaching cycles to the call.** On a normal Application subnet, HTTPS outcalls are not free — the calling canister must attach cycles to cover the cost, and attaching zero fails the call. Both Motoko and Rust have wrappers that compute and attach the required cycles automatically: in Motoko, use `await Call.httpRequest(args)` from the `ic` mops package (`import Call "mo:ic/Call"`); in Rust, use `ic_cdk::management_canister::http_request` (available since ic-cdk 0.18). Under the hood, both use the `ic0.cost_http_request` system API to calculate the exact cost from `request_size` and `max_response_bytes` — the API is cost-schedule aware, so the same wrapper attaches the correct amount on any subnet type. On a **cloud engine** (`CloudEngine` subnet), that amount is always 0 by design; do not "fix" a working outcall by attaching a hardcoded non-zero fee there — see the `cloud-engine-canisters` skill.
 
 3. **Using HTTP instead of HTTPS.** The IC only supports HTTPS outcalls. Plain HTTP URLs are rejected. The target server must have a valid TLS certificate.
 
@@ -336,6 +336,8 @@ per-request-byte term.
 
 Unused cycles are refunded to the canister, so it is safe to over-budget.
 
+This formula applies on a normal **Application subnet**. It does not apply on a **cloud engine** (`CloudEngine` subnet): there, `ic0.cost_http_request` returns 0 regardless of `request_size` or `max_response_bytes`, because engines run under a free cost schedule. Load the `cloud-engine-canisters` skill for the engine's call rules before writing or debugging outcall code that will run there.
+
 ## Deploy & Test
 
 ### Local Deployment
@@ -430,3 +432,7 @@ fn transform_normalize(args: TransformArgs) -> HttpRequestResult {
     }
 }
 ```
+
+## Additional References
+
+- Load `cloud-engine-canisters` for canisters running on a cloud engine, including why outcall cost drops to 0 there and why outcalls must never be routed through the engine's console proxy.