Update to Omneky

{
  "description": "Recover from Omneky MCP failures: JWT re-OAuth, missing brand_id, empty reporting, timeouts, launch 400s, needs_user_decision, credit_insufficient, billing tools absent from tools/list, approval plain-chat fallback, ambiguous paid-submit recovery, disconnected connectors, and pending scrapes. Intent keywords: unauthorized, reconnect, empty metrics, timeout, 400, credits, billing absent, needs_user_decision, pending scrape, failure playbook.",
  "included_files": [],
  "name": "omneky-failure-modes",
  "skill_md_contents": "---\nname: omneky-failure-modes\ndescription: >-\n  Recover from Omneky MCP failures: JWT re-OAuth, missing brand_id, empty\n  reporting, timeouts, launch 400s, needs_user_decision, credit_insufficient,\n  billing tools absent from tools/list, approval plain-chat fallback,\n  ambiguous paid-submit recovery, disconnected connectors, and pending\n  scrapes. Intent keywords: unauthorized, reconnect, empty metrics, timeout,\n  400, credits, billing absent, needs_user_decision, pending scrape, failure\n  playbook.\n---\n\n# Omneky — failure modes (shared playbook)\n\n## Activation analytics\n\nIf the host exposes a skill-activation / analytics hook, call it once per new user request with this skill name; otherwise skip silently. Never invent a tracking tool. Omneky MCP does **not** expose `track_skill_activation`.\n\n## Purpose\n\nCross-cutting recovery rules other skills point to by section (§). Encode\nrecoveries with **exact** public tools. Do not invent SQL, auto-topup,\ncard-PAN, Nexus debit, Central-only tools, fake widgets, or shared files\noutside skill folders.\n\n## When to use\n\n- A tool returned 401 / unauthorized / invalid token\n- `brand_id` missing or unresolvable from user language\n- Metrics look empty or “zero”\n- `status=timeout` / `status=pending` / `status=needs_user_decision`\n- Launch 400s (locations, LinkedIn start_date, Reddit microcurrency)\n- `credit_insufficient` on creative submit\n- Billing / balance tools missing from this session’s `tools/list`\n- Approval UI needed and no host widget / `request_user_decision` is available\n- Ambiguous paid submit (timeout / transport error after a possible charge)\n- Connector disconnected mid-workflow\n- User asks “what went wrong?” after an Omneky tool error\n\n## When not to use\n\n- Not a substitute for happy-path skills (`omneky-getting-started`,\n  `omneky-analytics`, `omneky-creative`, `omneky-launch-manage`, …)\n- Not a license to invent tools absent from `tools/list`\n\n## OpenAI runtime contract\n\n- Use only tools from the current OpenAI host + Omneky MCP (`https://mcp.omneky.com/mcp`). Never invent tools.\n- Prefer native ChatGPT / host widgets and question UI for decisions. Use MCP `request_user_decision` for missing structured fields (not deprecated `ask_user`) **when that tool is on tools/list**.\n- When intake is incomplete, ask **one** concise chat question. Never invent a question tool.\n- Approval / Generate turns: follow **§ Approval / plain-chat fallback** below — never invent a fake “summary widget” tool; never stall waiting for a widget that did not appear.\n- Never invent tokens; OAuth is host-managed. Never ask the user to paste a JWT or API key into chat.\n\n## Non-negotiable output / safety contract\n\n- Credits / deductions / balance: **cgp-backend path only** via existing MCP\n  tools when present on `tools/list`. Never invent Nexus debit routes or\n  prepaid-purchase tools. When billing tools are absent, follow **§ Billing\n  tools absent**.\n- Never dump raw `clarification_needed` JSON into chat — present plain\n  questions / host UI.\n- Never identical tight-loop retries in one turn for timeout / pending.\n- Prefer pause over delete when a mutate failed mid-flight and the user\n  only wanted to stop spend.\n- Point siblings back here by name + section from other skills’ failure tables.\n\n---\n\n## § Billing tools absent / tools/list gating\n\nBilling tools (`get_account_credit_balance`, `get_billing_summary`,\n`list_available_plans`, `start_plan_upgrade`, `create_billing_portal_session`,\n`get_credit_history`, …) may be present on some connectors and **absent** on\nsome ChatGPT / host sessions (smaller tool snapshots).\n\n1. **Before calling**: check whether the tool appears on the host’s\n   `tools/list` / available tools.\n2. **If present**: call balance before paid gen when unknown; on low balance\n   offer upgrade / portal tools **only if those are also present**.\n3. **If absent**:\n   - Do **not** call balance / billing tools.\n   - Do **not** invent a balance number or a billing tool name.\n   - State operational cost (~**5** credits per image job / ~**30** credits\n     per multi-scene video job when submitted).\n   - Proceed to generate after the user confirms intent (Generate / Cancel\n     via host UI or plain chat).\n   - Rely on the generate tool’s `credit_insufficient` (or equivalent) as\n     the hard gate.\n4. Same gating for plan / portal tools: if absent, tell the user to manage\n   plan / credits in the Omneky app / settings — never invent Checkout tools.\n\nCreative skills should say: “follow `omneky-failure-modes` § Billing tools\nabsent” rather than duplicating divergent copy.\n\n## § Approval / plain-chat fallback\n\nDo **not** require an unimplemented custom “summary widget” binary. Contract:\n\n1. Prefer host-native decision UI when available: OpenAI/ChatGPT confirmation\n   cards, MCP Apps UI, or MCP `request_user_decision` when that tool is on\n   `tools/list`.\n2. If **none** of those exist: **plain-chat fallback** — send a one-card\n   summary in chat (`Brand · Channel · Objective · Budget · Paused|Live ·\n   Creative`) with explicit options **Approve / Deny / Edit**, then **end\n   the turn** and wait for the user’s reply text; mutate only after an\n   affirmative Approve (or clear yes).\n3. Never invent a fake widget tool. Never stall waiting for a widget that\n   did not appear.\n4. Same pattern for Generate / Cancel credit callouts when no host widget\n   is available: plain-chat Generate / Cancel, end turn, wait.\n\nLaunch / pause / budget skills should say: “follow `omneky-failure-modes`\n§ Approval / plain-chat fallback”.\n\n## § Ambiguous paid submit recovery\n\nPaid submits (`generate_image_ad` with `gpt_ad_gen_id`, optional video\n`job_id` you supplied) can fail clearly **or** leave the outcome unknown.\n\n**Clear failure** before accept (`credit_insufficient`, validation error,\nexplicit reject): a **new** key / new attempt is OK.\n\n**Ambiguous** (timeout / transport error / unknown **after** you may have\nalready submitted):\n\n1. Do **not** immediately resubmit with a new `gpt_ad_gen_id` (duplicate\n   spend risk — commit lag can still mean charged). Remember the intended\n   key.\n2. On the next turn call `get_generation_status(job_id=<that gpt_ad_gen_id>,\n   kind=\"image\")` **once**. For images, the status `job_id` arg accepts the\n   same `gpt_ad_gen_id` used at submit.\n3. If status shows running / complete → continue that job (do not re-mint).\n4. If `not_found` **or** `queued` with `source=not_found`: **WAIT ~30–60s\n   and/or ask the user** before any new paid submit. Do **not** auto-mint a\n   new key and resubmit — a missing status row often means commit lag, not\n   a safe never-started.\n5. New key / resubmit only after:\n   - a **clear pre-accept failure**, or\n   - **explicit user OK** after the wait still shows never-started /\n     `not_found`.\n6. If still ambiguous after wait → ask the user before a second paid submit.\n\nSame spirit for video when you supplied a client `job_id`: one status peek\nwith `kind=\"video\"`; on `not_found` / queued+source not_found wait/ask —\ndo not auto-resubmit. Widget hosts: leave in-flight polling to the MCP Apps\nwidget; do not loop status in one turn.\n\nCreative / image / video skills should say: “follow `omneky-failure-modes`\n§ Ambiguous paid submit recovery”.\n\n## § Resize / edit charge (follow live tool text)\n\nPublic tool text for `resize_ad` / `resize_image`: **resizes are not\ncharged** — they adapt an already-paid creative. Synchronous; no status\npoll. Do **not** invent “premium resize tiers” or require balance-before-\nresize.\n\n- `edit_image` may still be a separate paid path — check live tool text on\n  `tools/list` for that tool only.\n- If a future `tools/list` description changes charge language, **follow the\n  live tool text** over any skill copy.\n\nEdit-resize / creative skills should say: “follow `omneky-failure-modes`\n§ Resize / edit charge”.\n\n---\n\n## Staged workflow (other recoveries)\n\n### Stage A — Auth / JWT\n\n1. Send the user through **host OAuth** for Omneky again.\n2. Optionally `health_check` after reconnect.\n3. Re-run `get_current_user` before brand-scoped calls.\n4. Never ask them to paste a Nexus JWT or API key into chat.\n\n### Stage B — brand_id\n\n1. `list_brands` + confirm (host UI / plain chat / one question).\n2. Prefer numeric `brand_id` when thumbnails matter.\n3. Do not guess.\n\n### Stage C — Empty reporting\n\n1. Call `check_reporting_data_available` (not deprecated `data_available`)\n   for brand + date range + channels **before** treating empty as zero.\n2. If coverage is missing, say so; do not invent metrics.\n3. Never sum `selected_conversion_metric_value` across channels.\n\n### Stage D — Timeouts / pending\n\n| Signal | Response |\n| --- | --- |\n| `get_recommendations` → `status=timeout` | Narrow date window; do not identical retry this turn. |\n| Unscoped `get_ad_groups` → timeout | Pass `campaign_id` (and ids when known); retry once narrowed. |\n| `scrape_product_from_url` → `status=pending` | Retry later same `brand_id` + url; no tight poll this turn. |\n| Async gen still running | On widget hosts, let the widget poll; on text hosts call `get_generation_status` **once** next turn — never loop in one turn. |\n\n### Stage E — Launch / targeting 400s\n\n- LinkedIn: `search_ad_targeting` with `types=[\"locations\"]` and a\n  `urn:li:adTargetingFacet:locations` entry; `start_date` required when\n  creating a new campaign group.\n- TikTok: `get_tiktok_location_ids` then pass `location_ids` on the ad group.\n- Google Demand Gen: `search_google_countries` → `targeting_fragments`.\n- X Ads: wire name `twitter`, never `x`.\n- Reddit: `bid_value` is microcurrency (dollars × 1,000,000).\n- Meta leads: `lead_gen_form_id` on ad specs for native forms.\n- Disconnected channel: `omneky-self-connect` /\n  `get_channel_connect_url` → link → re-check.\n\n### Stage F — needs_user_decision\n\n1. If `request_user_decision` is on `tools/list`, call it (not deprecated\n   `ask_user`).\n2. Else use plain-chat questions (§ Approval / plain-chat fallback).\n3. Never dump `clarification_needed` JSON.\n4. Never auto-retry the failed write in the same turn.\n\n### Stage G — Credits / plan\n\n1. `credit_insufficient` means the render **did not start**.\n2. If balance tools are on `tools/list`: `get_account_credit_balance` (and\n   optional `get_credit_history`).\n3. If upgrade / portal tools are present: `list_available_plans` +\n   `start_plan_upgrade`, or `create_billing_portal_session`. Hand Stripe URL;\n   never collect a PAN.\n4. If billing tools are **absent**: follow **§ Billing tools absent**; do not\n   invent balance; point to Omneky app / settings for plan management.\n5. After user finishes Checkout (when those tools exist):\n   `get_checkout_session_status` **once**. Details: `omneky-billing` /\n   `omneky-credit-balance`.\n\n### Stage H — Connector disconnected mid-flow\n\n1. `get_channel_connection_status` / `list_connector_statuses`.\n2. Hand off to `omneky-self-connect` / `omneky-channel-connect`.\n3. Do not invent alternate launch endpoints.\n\n## Failure boundaries\n\n| Failure | Required response |\n| --- | --- |\n| 401 / unauthorized | Host re-OAuth; never pasted JWT. |\n| Unknown brand | `list_brands` + confirm. |\n| Empty metrics | `check_reporting_data_available` first; never invent. |\n| Cross-channel conversion sum temptation | Group by channel or named metric only. |\n| `status=timeout` | Narrow scope; no identical retry this turn. |\n| `status=pending` scrape | Later retry same args; no tight loop. |\n| `needs_user_decision` | `request_user_decision` if listed; else plain chat; no auto-retry. |\n| Launch location 400 | Channel pre-call (LinkedIn / TikTok / Google DG). |\n| `credit_insufficient` | Did not start; upgrade path if tools present; else Omneky app; no retry. |\n| Billing tools missing | § Billing tools absent — operational cost + `credit_insufficient` gate. |\n| No approval widget | § Approval / plain-chat fallback — never invent widget tools. |\n| Ambiguous paid submit | § Ambiguous paid submit recovery — status once; on not_found wait/ask — never auto new key. |\n| Resize charge guess | § Resize / edit charge — follow live tool text (uncharged today). |\n| Missing tool on `tools/list` | Say unavailable; do not invent. |\n| Delete urge after error | Prefer `set_ad_entity_status` pause; deletes need dual confirm. |\n| Widget poll tools called by model | Do not call `poll_image_generation` / `poll_video_generation` / `sync_generation_group` as the agent on widget hosts. |\n\n## Sibling map\n\nOther skills should point here for recovery, then return to:\n\n| Domain | Skill |\n| --- | --- |\n| Session / brand | `omneky-getting-started` |\n| Connectors | `omneky-self-connect` / `omneky-channel-connect` |\n| Analytics empty | `omneky-analytics` |\n| Credits | `omneky-credit-balance` / `omneky-billing` |\n| Creative async | `omneky-creative` |\n| Launch 400s | `omneky-launch-manage` / `omneky-meta-launch` |\n"
}