Update to Biohub ESM

{
  "name": "biohub-esm-setup",
  "description": "Set up and preflight Biohub ESM, Atlas, Modal, and Hugging Face access. Use when installing pinned ESM dependencies, checking credentials, or fixing auth, rate-limit, credits, PATH, SDK, or GPU setup. Never ask for secret values.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 234
    },
    {
      "relative_path": "references/setup.md",
      "size_in_bytes": 6303
    }
  ],
  "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, or fixing auth, rate-limit, credits, PATH, SDK, or GPU setup. Never ask for secret values.\n---\n\n# Biohub ESM setup and auth\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 no verified host credential action is available, use this credential instruction alongside the Python blocker when applicable:\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\nPreflight returns `obtain_key_url`, `variable`, and `esm_sdk_runtime` 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, exact ESM\nand Transformers source revisions, 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`, `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 run without a separate confirmation, while Modal, self-hosted, and bulk-transfer routes require the route-specific confirmation first. Do not hand the command to the user when tool execution is available. Never open or display `.modal.toml`; file presence is enough for preflight.\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: set `ESM_API_KEY` in the environment that launches Codex, then restart Codex so it inherits the setting. On macOS, preflight and managed requests also recognize an existing generic-password item with service `com.openai.codex.biohub-esm.ESM_API_KEY`. 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 set it in the environment that launches Codex and restart 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## Source/model-pinned install\n\nUse an isolated environment and the pin in [`source-pins.md`](../../references/source-pins.md):\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install \\\n  \"esm @ git+https://github.com/Biohub/esm.git@ba4d7124864eed323a93bf3cfefcd958f573b75a\"\n.venv/bin/python -m pip install --force-reinstall --no-deps \\\n  \"transformers @ git+https://github.com/Biohub/transformers.git@ef32577f55da19a4989cd7b22e004dc43a4998cb\"\n.venv/bin/python <plugin-root>/scripts/biohub_esm.py verify-install\n```\n\nESM currently declares the Transformers fork from mutable `main`. The second layer must replace it with the exact direct-VCS revision; a single combined install does not even preserve the intended source pin when `requested_revision` remains `main`. These 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 auth failure only.\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- `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 or binder 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"
}