Use Jev after a tool failure

curl -sS https://router.flatkey.ai/api/alpha/decisions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "typesafe/jev-1.13",
  "state": "Failed step (attempt 1 of 2):\n  tool: http_fetch\n  args: GET https://api.vendor.example/v2/invoices?since=2026-10-01\n  error: 401 Unauthorized — \"API token expired. Generate a new token in Settings → API.\"\n\nAlternative tools: browser_open (no saved login), read_cache (last sync 9 days ago)\nGoal: list October invoices for the monthly close report.\n\nTask: recovery (retry_once / switch_tool / ask_user), transient, needs_user.",
  "questions": {
    "recovery": {
      "type": "choice",
      "instructions": "An agent step just failed. Given the tool, its arguments, the error, the attempt count, and the alternative tools listed, what should the harness do next? Prefer retry_once only for errors that look transient; switch_tool when a listed alternative can reach the same goal; ask_user when the failure needs information, permission, or a decision only the user has.",
      "criteria": {
        "retry_once": "The error looks transient (timeout, rate limit, flaky network, lock contention) and the same call with the same arguments is likely to succeed",
        "switch_tool": "The same call will keep failing, but one of the alternative tools listed can reach the same goal",
        "ask_user": "The failure needs credentials, permission, a missing input, or a judgment call from the user, or every remaining option is risky"
      }
    },
    "transient": {
      "type": "score",
      "instructions": "How likely is it that this exact error clears if the identical call is repeated, based only on the error text and context provided.",
      "criteria": [
        "low",
        "medium",
        "high"
      ]
    },
    "needs_user": {
      "type": "noul",
      "instructions": "The failure can only be resolved with something the user has to provide or approve—credentials, a missing value, a scope decision, or consent to a destructive fallback."
    }
  }
}'

// Node.js 18+ (built-in fetch). Run: FLATKEY_API_KEY=... node jev.mjs
const body = {
  "model": "typesafe/jev-1.13",
  "state": "Failed step (attempt 1 of 2):\n  tool: http_fetch\n  args: GET https://api.vendor.example/v2/invoices?since=2026-10-01\n  error: 401 Unauthorized — \"API token expired. Generate a new token in Settings → API.\"\n\nAlternative tools: browser_open (no saved login), read_cache (last sync 9 days ago)\nGoal: list October invoices for the monthly close report.\n\nTask: recovery (retry_once / switch_tool / ask_user), transient, needs_user.",
  "questions": {
    "recovery": {
      "type": "choice",
      "instructions": "An agent step just failed. Given the tool, its arguments, the error, the attempt count, and the alternative tools listed, what should the harness do next? Prefer retry_once only for errors that look transient; switch_tool when a listed alternative can reach the same goal; ask_user when the failure needs information, permission, or a decision only the user has.",
      "criteria": {
        "retry_once": "The error looks transient (timeout, rate limit, flaky network, lock contention) and the same call with the same arguments is likely to succeed",
        "switch_tool": "The same call will keep failing, but one of the alternative tools listed can reach the same goal",
        "ask_user": "The failure needs credentials, permission, a missing input, or a judgment call from the user, or every remaining option is risky"
      }
    },
    "transient": {
      "type": "score",
      "instructions": "How likely is it that this exact error clears if the identical call is repeated, based only on the error text and context provided.",
      "criteria": [
        "low",
        "medium",
        "high"
      ]
    },
    "needs_user": {
      "type": "noul",
      "instructions": "The failure can only be resolved with something the user has to provide or approve—credentials, a missing value, a scope decision, or consent to a destructive fallback."
    }
  }
};

const res = await fetch("https://router.flatkey.ai/api/alpha/decisions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`Jev request failed: ${res.status} ${await res.text()}`);
const { answers, usage } = await res.json();
console.log(JSON.stringify(answers, null, 2), usage);

# Python 3.8+ (pip install requests). Run: FLATKEY_API_KEY=... python jev.py
import json, os, requests

body = json.loads(r"""{
  "model": "typesafe/jev-1.13",
  "state": "Failed step (attempt 1 of 2):\n  tool: http_fetch\n  args: GET https://api.vendor.example/v2/invoices?since=2026-10-01\n  error: 401 Unauthorized — \"API token expired. Generate a new token in Settings → API.\"\n\nAlternative tools: browser_open (no saved login), read_cache (last sync 9 days ago)\nGoal: list October invoices for the monthly close report.\n\nTask: recovery (retry_once / switch_tool / ask_user), transient, needs_user.",
  "questions": {
    "recovery": {
      "type": "choice",
      "instructions": "An agent step just failed. Given the tool, its arguments, the error, the attempt count, and the alternative tools listed, what should the harness do next? Prefer retry_once only for errors that look transient; switch_tool when a listed alternative can reach the same goal; ask_user when the failure needs information, permission, or a decision only the user has.",
      "criteria": {
        "retry_once": "The error looks transient (timeout, rate limit, flaky network, lock contention) and the same call with the same arguments is likely to succeed",
        "switch_tool": "The same call will keep failing, but one of the alternative tools listed can reach the same goal",
        "ask_user": "The failure needs credentials, permission, a missing input, or a judgment call from the user, or every remaining option is risky"
      }
    },
    "transient": {
      "type": "score",
      "instructions": "How likely is it that this exact error clears if the identical call is repeated, based only on the error text and context provided.",
      "criteria": [
        "low",
        "medium",
        "high"
      ]
    },
    "needs_user": {
      "type": "noul",
      "instructions": "The failure can only be resolved with something the user has to provide or approve—credentials, a missing value, a scope decision, or consent to a destructive fallback."
    }
  }
}""")

res = requests.post(
    "https://router.flatkey.ai/api/alpha/decisions",
    headers={"Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}"},
    json=body,
    timeout=60,
)
res.raise_for_status()
data = res.json()
print(json.dumps(data["answers"], indent=2), data.get("usage"))

No Flatkey key yet? Get one for Jev 1.13 →