Update to Helical

{
  "description": "Get a Helical connection working when it is not: the plugin was installed but never connected, a tool call came back with an authorization link, or a connection that worked before is now refused. Use when the helical tools are missing from the session or the host offers only an `authenticate` tool for it; when a Helical call returns \"Authorization required before this tool can run\", \"This request requires more information\" or a link to open; when it fails with invalid_grant, invalid_request, invalid_client, invalid_token, unauthorized_client, a 401, \"OAuth authorization required\", \"Missing Bearer token\" or \"Invalid JWT\"; when a call fails without saying why; or when the user asks how to sign in. For a run refused over credit, use check-credits.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 282
    }
  ],
  "name": "reconnect-helical",
  "skill_md_contents": "---\nname: reconnect-helical\ndescription: >-\n  Get a Helical connection working when it is not: the plugin was installed but never\n  connected, a tool call came back with an authorization link, or a connection that worked\n  before is now refused. Use when the helical tools are missing from the session or the\n  host offers only an `authenticate` tool for it; when a Helical call returns \"Authorization\n  required before this tool can run\", \"This request requires more information\" or a link to\n  open; when it fails with invalid_grant, invalid_request, invalid_client, invalid_token,\n  unauthorized_client, a 401, \"OAuth authorization required\", \"Missing Bearer token\" or\n  \"Invalid JWT\"; when a call fails without saying why; or when the user asks how to sign in.\n  For a run refused over credit, use check-credits.\n---\n\n# Reconnect Helical\n\nHelical asks for two approvals, both in the browser: **connecting the plugin** in the\nclient, and **one authorization the first time a tool runs**. Each failure below is one of\nthem missing. Tell which from what you see, and put the user's next step in the same\nmessage that reports the problem — never leave them to ask \"so what do I do?\".\n\n| What you see | Case |\n|---|---|\n| No `helical` tools at all, or only an `authenticate` tool for it | 1 — not connected |\n| A call returns a link to open, \"Authorization required before this tool can run\", or \"This request requires more information\" | 2 — authorization link |\n| A connection that worked before now fails with a 401 or an OAuth code | 3 — connection refused |\n\nNot these: **`402` / `insufficient_balance`** is credit (`check-credits`), and **`403`** is\na signed-in account without permission — reconnecting returns the same `403`.\n\n## 1. Not connected\n\nInstalling the plugin and connecting it are two separate steps in every client. Skip the\nsecond and the plugin shows as enabled with none of its tools. Confirm it before you fix\nit, where the client lets you:\n\n- **Claude Code**: `claude mcp list`. The plugin's server is\n  `plugin:helical-platform:helical` (`claude.ai Helical` when added from the Claude\n  directory, plain `helical` when added by hand). `! Needs authentication` is this case;\n  `✔ Connected` is not.\n- **Codex**, and the ChatGPT desktop app with a plugin added from GitHub: `codex mcp list`.\n  `Not logged in` under **Auth** is this case; `OAuth` is not.\n- **ChatGPT** from the public directory, **Claude Desktop** and **claude.ai** have no\n  command: ask whether Helical still offers **Connect** where the fix below points.\n\nThen connect it:\n\n- **Claude Code** (CLI, and the Code tab in Claude Desktop). If the host offers a helical\n  `authenticate` tool (e.g. `mcp__plugin_helical-platform_helical__authenticate`), call it\n  and relay the link it returns; the tools load once the user approves, with no new\n  session. If their browser then lands on a `localhost` page that will not load, ask for\n  the address-bar URL and pass it to the matching `complete_authentication` tool.\n  Otherwise the user runs `/mcp` → the Helical server → **Authenticate**, or\n  `claude mcp login plugin:helical-platform:helical` in their own terminal. Do not run that\n  command yourself: it needs an interactive terminal and refuses without one.\n- **Codex**: `codex mcp login helical`. You can run this one: it opens their browser and\n  waits for the approval. `/mcp` inside Codex only lists servers. In the ChatGPT desktop\n  app the same step is **Settings** → **MCP servers** → **Authenticate**.\n- **ChatGPT** from the public directory: **Settings** → **Plugins** → Helical →\n  **Connect**.\n- **Claude Desktop** and **claude.ai**: **Customize** → **Connectors** → Helical →\n  **Connect**.\n\nExcept through the `authenticate` tool, say a new session may be needed: hosts that load\ntheir tools at session start will not add them to this one. The Connect step of the\nwalkthrough at `<who-am-i-tool-console-url>docs?section=walkthrough` has the same steps\nfor every client.\n\n## 2. Authorization link\n\nThe connection is fine; Helical needs one more approval before the tool can run. It is\nexpected on the first tool call after connecting, and again now and then — months apart,\nor after the account was signed out everywhere. Reconnecting the client does not clear\nit, and neither does anything in case 1 or 3.\n\nThe link reaches you in one of two shapes: the host shows its own prompt to open a URL, or\nthe call fails with \"Authorization required before this tool can run\" followed by the\nlink. Relay that link exactly as it came — it belongs to this user and this request —\nalone in a fenced code block, never as a markdown link or a bare URL:\n\n```text\nhttps://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/authorize?request_uri=…\n```\n\nThe link works once, for about ten minutes: whatever opens it first spends it, and the\nuser then gets `{\"message\":\"Invalid request\"}`. Some hosts open a link they render before\nthe user clicks it — the ChatGPT app does — so a rendered link arrives already spent; a\ncode block is not rendered as a link and reaches the user unused. For the same reason,\nnever open, fetch or preview it yourself. Ask the user to copy it into their browser and\napprove (normally one click, since they are already signed in), then retry the same call.\nIf they get \"Invalid request\", the link was already spent or is too old: retry the call\nonce for a fresh link and relay that one the same way, rather than sending them back to\nthe old one.\n\n## 3. Connection refused\n\nA connection that worked before is rejected: a `401`, \"OAuth authorization required\",\n\"Missing Bearer token\", \"Invalid JWT\", or an OAuth code (`invalid_grant`,\n`invalid_request`, `invalid_client`, `invalid_token`, `unauthorized_client`). These come\nfrom the client's sign-in, not from the tool you called, so its arguments are never the\nproblem. Never quote the code at the user; say what broke in plain words, and do not say\n\"expired\" unless you know it expired.\n\nThe client holds that sign-in, so the fix is the client's — clear it and connect again:\n\n- **Claude Code**: `claude mcp logout plugin:helical-platform:helical && claude mcp login\n  plugin:helical-platform:helical`, in the user's own terminal, or `/mcp` → the Helical\n  server → **Re-authenticate**.\n- **Codex**: `codex mcp logout helical && codex mcp login helical`.\n- **ChatGPT**: **Settings** → **Plugins** → Helical → **Reconnect** (or\n  **Disconnect**, then **Connect**).\n- **Claude Desktop** and **claude.ai**: **Customize** → **Connectors** → Helical →\n  **Connect**.\n\nOn any other host, name that client's own reconnect affordance or say you do not know it —\ndo not invent menu items.\n\n**When the error does not say** which case it is, do not end the turn on \"I cannot tell\".\nCheck the status commands in case 1, then give the step that matches.\n\n## Never build a link\n\nAssembling a sign-in or authorization URL, or registering a client with `curl` to get\nsomething clickable, authorizes something the plugin does not use: the user approves it,\nit seems to work, and the next call fails the same way. Relay only a link the host or a\nHelical tool printed.\n\n## Then\n\n`health()` and `whoami()` confirm the connection is back: both take no arguments, spend no\ncredit and start nothing. Prefer `whoami` when the user was mid-workflow, since it also\nreturns the current balance.\n\nRetry the failed call once, and stop rather than loop if it fails the same way again.\n\n**Before re-issuing anything that starts work**, check what the failed attempt left\nbehind — starting over is how one job gets billed twice:\n\n- `listPendingConfirmations()` for a run queued but not yet approved. A `triggerEmbedding`\n  that landed before the failure has already queued a confirmation, and re-triggering\n  returns a 409 without giving the id back — so list it and resolve that one instead.\n- `listDagRuns({ state: \"running\" })` for a run already going, and\n  `getConfirmationStatus({ id })` to settle whether an approval that timed out actually\n  launched.\n\n\"Nothing was charged\" holds only when the failure stopped something before it started. An\napproval spent before the connection dropped has already launched the run, so check before\nsaying it.\n\n## Conventions\n\nThe next step in the first message, always · tell the three cases apart before fixing ·\ncheck status with `claude mcp list` / `codex mcp list` where the client has one · call the\nhost's `authenticate` tool when it offers one · run `codex mcp login` yourself, hand\n`claude mcp login` to the user · relay an authorization link exactly as it came, alone in\na code block and never opened by you, then retry · plain words, never the OAuth code · never build a link · retry once, then stop ·\ncheck for a queued confirmation or a running run before re-issuing anything that spends\ncredit.\n"
}