Update to Biohub ESM

{
  "description": "Set up and preflight Biohub ESM, Atlas, Modal, and Hugging Face access. Use when installing pinned ESM dependencies, checking credentials, connecting the Biohub MCP for Atlas tools and its Mol* structure viewer, or fixing auth, rate-limit, credits, PATH, SDK, or GPU setup. Never ask for secret values.",
  "included_files": [
    {
      "relative_path": "LICENSE.md",
      "size_in_bytes": 1093
    },
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 234
    },
    {
      "relative_path": "references/setup.md",
      "size_in_bytes": 8775
    }
  ],
  "name": "biohub-esm-setup",
  "skill_md_contents": "---\nname: biohub-esm-setup\ndescription: Set up and preflight Biohub ESM, Atlas, Modal, and Hugging Face access. Use when installing pinned ESM dependencies, checking credentials, connecting the Biohub MCP for Atlas tools and its Mol* structure viewer, or fixing auth, rate-limit, credits, PATH, SDK, or GPU setup. Never ask for secret values.\nlicense: MIT\n---\n\n# Biohub ESM setup and auth\n\nThe user's instructions take precedence over guidelines provided in a skill.\nIf explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.\n\n## No key yet\n\nWhen `biohub_managed.status` is `missing`, inspect `esm_sdk_runtime` before starting credential setup. If the selected managed workflow imports the pinned `esm` SDK and `esm_sdk_runtime.status` is `unsupported`, report both blockers in the same handoff: say that the workflow requires Python 3.12, and quote the reported interpreter and remedy. This applies to managed ESMC mutation scoring, `esmc-landscape`, and ESMFold2 response serialization. Do not wait until after the key is configured to reveal the Python blocker.\n\nWhen `biohub_managed.status` is `unverified`, the key may already be saved: a sandbox blocked the macOS Keychain.\nRerun the status-only preflight outside the sandbox before giving any key instruction, as **Keychain access on macOS** describes.\n\nWhen no verified host credential action is available, give the instruction for the user's platform, alongside the Python blocker when applicable.\nWhen preflight returns `macos_keychain_command` (macOS with the plugin installed), give the user these steps and quote that command exactly:\n\n1. Get a free API key at https://biohub.ai/developer-console/api-keys (existing Forge accounts can sign in), then copy it.\n2. Open Terminal (press Command-Space, type Terminal, and press Return), paste this command, and press Return:\n\n   ```bash\n   security add-generic-password -U -a \"$USER\" -s com.openai.codex.biohub-esm.ESM_API_KEY -w\n   ```\n\n3. At `password data for new item:`, paste the key and press Return.\n   Nothing appears as you paste, so paste only once.\n   At `retype password for new item:`, paste it again and press Return.\n   If you see `passwords don't match`, paste the key at both prompts again.\n4. Come back and send any message.\n   No restart is needed.\n\nThese steps work in the desktop app, which does not inherit variables set in Terminal, and in the CLI.\nRunning the command again replaces the key it saved, and the plugin reads that item before any other.\nNever run the command yourself; the user types the key into it, outside the chat.\nNever suggest creating the item in the Keychain Access app: only this command is verified to create an item the plugin can read without a macOS approval prompt.\nIf the user already created one there, have them delete it in Keychain Access, then run the command.\n\nOtherwise, on Linux, on Windows, or in a standalone skill install without the plugin's preflight, use this instruction:\n\n> Get a free API key at https://biohub.ai/developer-console/api-keys (existing Forge accounts can sign in), set it as `ESM_API_KEY` in the environment that launches Codex, then restart Codex.\n\nAlways write the full URL as plain text, exactly `https://biohub.ai/developer-console/api-keys`.\nNever hide it behind Markdown link text such as \"Biohub's API key page\", because some hosts show only the link text and leave the user with no clickable link and no address.\n\nPreflight returns `obtain_key_url`, `variable`, `esm_sdk_runtime`, and on macOS `macos_keychain_command` alongside the status, so quote those rather than composing your own setup requirements. If a verified credential action is available, follow **Seamless credential recovery** below instead. Apart from current setup blockers, do not describe routes, models, request counts, or costs before the key exists; none of it is actionable yet. Once the key and runtime are configured, resume the original request automatically without asking the user to repeat it.\n\n## Safe preflight\n\nThe agent runs the base status-only check directly for credentials, Atlas, and\nroutes that do not materialize a managed structure:\n\n```bash\npython3 <plugin-root>/scripts/biohub_esm.py preflight\n```\n\nFor a managed fold, run the selected endpoint's capability preflight with the\nsame provisioned Python 3.12 interpreter that will execute the request:\n\n```bash\n<python-3.12-with-pinned-esm> <plugin-root>/scripts/biohub_esm.py preflight --endpoint fold\n<python-3.12-with-pinned-esm> <plugin-root>/scripts/biohub_esm.py preflight --endpoint fold_all_atom\n```\n\nRun only the applicable endpoint command. Its\n`managed_structure_materialization` report verifies the interpreter, the exact\npinned `esm` and `transformers` wheels, endpoint-specific imports, and a tiny offline\nserialization. A blocked report must stop the workflow before credential access,\noutput creation, or provider submission; apply its bounded remediation and rerun\nthat endpoint preflight. Resolve the placeholder to the provisioned interpreter\n(`.venv/bin/python` for the install below) and use that exact interpreter for the\nsubsequent managed command.\n\nCredential entries report only `configured`, `missing`, `unverified`, `optional-missing`, or `not-required`; `esm_sdk_runtime` separately reports `supported` or `unsupported`. On macOS, preflight probes only whether the recognized Keychain item exists; it never requests the value or uses `security ... -w`. Execution-time resolution may retrieve the existing item only when the selected route is authorized to run: tutorial-scale managed Biohub requests, including every ESMFold2 tutorial fold, run without a separate confirmation; Modal, self-hosted, and bulk-transfer routes require the route-specific confirmation first. Run preflight and managed commands yourself when tool execution is available; the Keychain command under **No key yet** and the host command under **Biohub MCP connection** are the only commands the user runs. Never open or display `.modal.toml`; file presence is enough for preflight.\n\n## Keychain access on macOS\n\nWhen `ESM_API_KEY` is not set, the plugin reads the generic-password item that the Terminal command saves, then any other item whose service is `com.openai.codex.biohub-esm.ESM_API_KEY`.\nA command sandbox can block the Keychain; the Codex sandbox does when its network access is off.\nInside such a sandbox, `security` fails with `SecKeychainSearchCreateFromAttributes: One or more parameters passed to a function were not valid.`, so a saved key looks absent.\nPreflight reports that case as `unverified` with source `macos-keychain-unreachable`, and a managed command fails with a message that says the Keychain was unreachable.\nWhen you see either, rerun that command outside the sandbox: request escalated permissions, and say the plugin needs to read the Biohub API key from the macOS Keychain.\nAct on the outside-sandbox result, and never tell the user a key is missing because of a sandboxed result alone.\nIf the host cannot run the command outside its sandbox, give one handoff: the plugin reads the Keychain only when its commands run outside the sandbox, so the user approves that request or switches to a permission mode that allows it, then sends any message.\nIf the user has not saved a key yet, put the Terminal steps under **No key yet** in that same handoff.\nIf a managed command reports that a Keychain item exists but macOS did not release its value, give the Terminal steps again without asking for a new key; the plugin reads the item that command saves first.\n\n## Seamless credential recovery\n\nWhen managed Biohub access reports `missing`, keep the current request intact while setup completes.\n\n1. Use the host's existing secure credential setup action for `ESM_API_KEY`, when one is actually available. Invoke it once and tell the user the verified host surface where its masked prompt will appear, such as a credential sheet in the app. Never claim that a terminal prompt exists unless the invoked action actually opens one.\n2. Let that host action collect and persist the credential. Never ask the user to paste, repeat, or reveal the value in chat, and never clear or overwrite a configured credential.\n3. When the setup action completes, automatically run the status-only preflight once. Resume a waiting tutorial-scale managed Biohub request immediately; it needs no separate confirmation. Resume Modal, self-hosted, or bulk-transfer work only when its exact frozen scope already has a still-current confirmation. Report the status without exposing the value if it is not configured.\n\nDo not ask the user to say \"done\" and do not create a repeated setup loop. If this host exposes no callable secure setup action, do not imply that it does. Give exactly one user-executed fallback for the user's platform. When preflight returned `macos_keychain_command`, give the Terminal steps under **No key yet**. Otherwise: get a free key at https://biohub.ai/developer-console/api-keys, set it as `ESM_API_KEY` in the environment that launches Codex, then restart Codex so it inherits the setting. Stop there; on the user's next message, run preflight automatically instead of asking whether setup was completed.\n\nA configured credential persists in the host's secret, environment store, or recognized macOS Keychain item until the user explicitly asks to replace or remove it. The plugin never mutates or removes the Keychain item, and setup must not unset any credential after a run.\n\n## Credentials\n\n- Biohub managed ESMC/ESMFold2: `ESM_API_KEY`. Create a free key at https://biohub.ai/developer-console/api-keys: name it, click Create, copy it. Existing Forge users sign in with the same credentials and do not need a new account. Use a verified host credential action when one exists; otherwise the user saves it with the Terminal steps under **No key yet** when preflight returns `macos_keychain_command`, or sets it in the environment that launches Codex and restarts Codex. Never ask the user to paste it in chat, and preserve an existing configured value.\n- Atlas API and `s3://esm-protein-atlas/v1/`: no client credential in the current alpha.\n- Modal: `MODAL_TOKEN_ID` plus `MODAL_TOKEN_SECRET`, or an authenticated Modal profile. Environment values override the profile.\n- Hugging Face public weights: no token required. `HF_TOKEN` is optional for authenticated Hub access and rate-limit handling.\n\n## Biohub MCP connection\n\nThe public Biohub MCP at `https://biohub.ai/mcp` gives every Biohub ESM skill the ESM Atlas tools and `ui_show_protein_structure`.\nThat tool shows a protein's 3D structure in the interactive Mol* viewer where the host renders MCP Apps, and as a PNG preview in every other host.\nThe server is anonymous: it needs no key or sign-in, and preflight does not check it.\nThe plugin declares it in `.mcp.json` as the server `biohub`, so a plugin install connects it.\n\nThe MCP is connected when the tool catalog lists `ui_show_protein_structure` and the ESM Atlas tools, with or without a host prefix.\nA `ui_show_protein_structure` that takes only a `structure_id` comes from a different Biohub server; the skills need the public one, whose tool takes `sequence`.\nIf the public tools are missing, give the user the one command for their host, because it changes their host configuration:\n\n- Claude Code: `claude mcp add --transport http biohub https://biohub.ai/mcp`, then check it with `claude mcp list`.\n- Codex: `codex mcp add biohub --url https://biohub.ai/mcp`, then check it with `codex mcp list`.\n- Any other host: add a streamable HTTP server at `https://biohub.ai/mcp` with no authentication.\n\nThe host loads the new tools only after it restarts or reloads its MCP servers, so tell the user to do that, then resume the original request on their next message.\nResume only the steps that did not run: when an analysis finished and only its Biohub MCP view failed, make only that view call, and never repeat its provider requests.\nSome hosts ask the user to approve a Biohub MCP tool before it runs; a denied approval is a tool failure, not a missing connection.\n\n## Source/model-pinned install\n\nUse an isolated environment and the pins in [`source-pins.md`](../../references/source-pins.md):\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install \"esm==3.4.1.post1\" \"transformers==4.57.6\"\n.venv/bin/python <plugin-root>/scripts/biohub_esm.py verify-install\n```\n\nBoth pins are exact PyPI wheels.\n`transformers==4.57.6` is the only release inside the range `esm==3.4.1.post1` declares, so the two resolve together in one install.\n`verify-install` checks that each installed distribution is an index or wheel-file install whose version and payload digest match the pins, that every RECORD-listed file is present and unmodified, that no unlisted file sits in the package tree, and that the import location is the verified install.\nBytecode caches for recorded sources are trusted rather than re-verified.\nIt then prints the upstream source commits recorded in provenance.\nOn Linux without a GPU, add `--extra-index-url https://download.pytorch.org/whl/cpu` to the install to take the smaller CPU PyTorch build.\nThese commands pin first-party code and model selection, but they are not a complete environment lock: the ESM package retains broad transitive dependency ranges, and hardware/runtime details can also affect outputs.\n\nFor Modal, use an already authenticated official CLI and install the validated `modal==1.5.2` SDK in an isolated environment. The generic durable control plane also requires the immutable positive deployment version returned by Modal and passes it to `Function.from_name(..., version=...)`; an app/function name alone is mutable. Do not place tokens on a command line. The [Modal config reference](https://modal.com/docs/sdk/py/latest/modal.config) documents environment and profile resolution, and the [Modal changelog](https://modal.com/docs/sdk/py/changelog) is the authority to review before updating the client pin.\n\n## Diagnose without weakening tests\n\n- `401`: missing, invalid, or expired Biohub key. Report the auth failure without guessing other causes, then replace the key as below.\n- `500` with an empty body on a managed call: most often a rejected key, because the managed API currently returns a bodyless `500` rather than `401` for an invalid bearer token. Say the key looks wrong and point at https://biohub.ai/developer-console/api-keys before treating it as an outage; a configured-but-rejected key is not the same as a missing one.\n- Replacing a rejected key: point at https://biohub.ai/developer-console/api-keys for a new one. If preflight reports source `macos-keychain`, give the Terminal steps under **No key yet** again; the command replaces the key it saved. If it reports source `environment`, the user replaces `ESM_API_KEY` where it is set, because it takes precedence over the Keychain.\n- `402` or credit message: account-specific credits; direct the user to https://biohub.ai/developer-console without inventing a quota.\n- `429`: honor `Retry-After`; reduce concurrency or resume later.\n- timeout/5xx: preserve durable state and partial artifacts. Retry only a proven-idempotent setup or public read with bounded backoff; never retry a managed call whose outcome is indeterminate.\n- Atlas schema error: retain raw response, compare the live alpha schema, and update validation intentionally.\n- OOM/hardware mismatch: for ESMC, select a smaller managed model or pinned weights on a suitable user-owned GPU; use Modal only for supported fold workflows. Do not silently lower scientific parameters.\n\nRead [setup details](references/setup.md), the shared [source pins](../../references/source-pins.md), and [safety/provenance contract](../../references/safety-and-provenance.md).\n"
}