Update to Biological Sequence & Alignment Viewer

{
  "name": "biological-sequence-viewer",
  "description": "Open, inspect, analyze, safely edit copies of, and export local biological sequences and alignments in Codex's interactive workbench. Use for FASTA/FASTQ, GenBank/EMBL, MSA formats, ABIF/SCF chromatograms, SnapGene DNA, annotations, variants, or regional read evidence.",
  "included_files": [],
  "skill_md_contents": "---\nname: biological-sequence-viewer\ndescription: Open, inspect, analyze, safely edit copies of, and export local biological sequences and alignments in Codex's interactive workbench. Use for FASTA/FASTQ, GenBank/EMBL, MSA formats, ABIF/SCF chromatograms, SnapGene DNA, annotations, variants, or regional read evidence.\n---\n\n# Biological Sequence & Alignment Viewer\n\nUse this skill when a user wants to inspect local biological sequences, alignments, annotated constructs or sequencing traces visually inside Codex. For detailed UI-to-agent mappings, binary compatibility or comparisons with specialist viewers, consult the [capability matrix](../../CAPABILITY_MATRIX.md); do not claim exhaustive Jalview, IGV, SnapGene, Benchling or FastQC parity.\n\n## Opening Workflow\n\nThe plugin contributes native file-pane preview and a model-visible inline MCP App for supported sequence and alignment files. The model should not read or copy file bytes into the conversation merely to open the viewer.\n\nFor user-provided local files:\n\n1. Resolve the user's intended local file. Prefer the explicitly named path. If the request is ambiguous, search only the relevant workspace and ask a short clarification question when multiple plausible artifacts remain.\n2. Confirm that the file is a supported biological sequence or alignment artifact.\n3. Call `sequence.open_from_chat` with the exact absolute local path whenever available. Omit `presentation` for the default `\"full\"` viewer; pass `presentation: \"inline\"` only when the user or onboarding flow explicitly requests minimal controls. Hidden controls remain available by moving the pointer to the viewer's top edge or focusing that edge with the keyboard; **Show toolbar** restores their pinned state in both Sequence and Alignment modes. A workspace-relative path works only when the MCP host exposes active roots. The tool opens the rich app inline beneath its tool-call row and returns a `viewerSessionId` in `structuredContent`; use that ID immediately for same-turn `sequence.control_viewer` calls instead of waiting for later model context.\n4. A successful open confirms session creation (`sessionReady: true`), not rendering (`viewerReady: false`). Say that the embedded viewer is opening; only say it is ready after live viewer context or an acknowledged action confirms that it loaded. Make the embedded viewer card the only opening affordance in the reply: `Click or expand the Sequence open from chat tool card above to view it. After it loads, you can use Open in side pane, or ask me to move or control the viewer.` Do not repeat or code-format the file name or path, say that the path was opened, or imply that a path or file citation is clickable; compound alignment suffixes may not become clickable and citation clicks can open raw text instead.\n5. After the app opens, answer follow-up questions from the viewer's model context. Re-read the current viewer context before answering questions about the current mode, selection, focused record, alignment column, or visible metrics.\n\nDo not call the app-only `sequence.open` tool directly from chat. It is reserved for Codex's native file-preview host because it requires an opaque `codex-resource://` URI that only the host can mint. Use `sequence.open_from_chat` for both user-provided local files and public starter files that Codex has fetched into the authorized workspace. The legacy `sequence.acquire_public_example` tool is optional only when the host provides independently authenticated workspace roots; it is never required for a marketplace starter and is not a fallback when roots are unavailable.\n\nIf the user asks to move, send, pin, or open an already-mounted viewer in the right pane, do not call `sequence.open_from_chat` again. Use `sequence.control_viewer` with the `viewerSessionId` from current model context and action `set_display_mode`; use `fullscreen` for the side pane and `inline` for chat. The in-view **Open in side pane** and **Return to chat** buttons provide the same standard MCP App display-mode behavior.\n\nA newly issued chat or starter handle can restore the same viewer session and bounded workbench checkpoint when its card remounts, including after the plugin server restarts, only after the active workspace root, original session, unchanged source identity, and source revision are revalidated. Re-read current viewer context after recovery; do not open a second card or replay an already completed command. Legacy handles without an authenticated session and expired, moved, changed, or unauthorized sources fail closed. If a card reports that its source expired, moved, changed, or left the active workspace, treat **Reopen from chat** as a new request to call `sequence.open_from_chat` with the prior exact path when it is still valid. If the source moved and the current path is not known, ask the user for it; do not guess a replacement or retry the expired resource URI.\n\n### Public starter examples\n\nEvery marketplace starter names an authoritative public record that **Codex fetches before opening the viewer**. Use host-authorized research and workspace tools to retrieve only the documented official HTTPS endpoints, write the requested source and honestly Codex-authored provenance inside the actual authorized workspace, and verify every pinned accession, version, release, checksum, format, size, subset, or derived alignment before opening. Then call `sequence.open_from_chat` exactly once with the exact absolute local path of the validated source. This creates one viewer and one session even when the plugin host does not expose MCP workspace roots. Never fetch an arbitrary URL, assume a workspace file already exists, substitute a bundled/synthetic fixture, infer workspace authority from task metadata or session history, or describe Codex-authored provenance as a plugin-issued or signed receipt.\n\nAn installed and authorized Life Science Research skill may help retrieve or confirm authoritative scientific data; if it is unavailable, Codex uses its ordinary authorized network and workspace tools against the same fixed official endpoints. Neither route requires the plugin to download or publish files. Network, rate-limit, version drift, malformed data, checksum, size, cancellation, disk, or workspace errors are terminal; explain the actionable error and do not open a viewer.\n\nThe official endpoint contracts are `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi` for NCBI Nuccore; the fixed reviewed-protein endpoints `https://rest.uniprot.org/uniprotkb/P01116.fasta`, `https://rest.uniprot.org/uniprotkb/P01111.fasta`, and `https://rest.uniprot.org/uniprotkb/P01112.fasta` for the RAS alignment; the immutable `https://ftp.ebi.ac.uk/pub/databases/Rfam/15.1/Rfam.seed.gz` release archive with exact `RF00360` record selection for the supported Rfam example; and `https://www.ebi.ac.uk/ena/portal/api/filereport` followed only by the catalog-pinned public `https://ftp.sra.ebi.ac.uk/` FASTQ path for ENA. Validate endpoint, accession, filename, and response identity before trusting returned content; never invent a replacement URL.\n\nThe exact final marketplace prompts and expected-results contract are checked in at `starter-examples.json` and documented in `STARTER_EXAMPLES.md`. The historical [LSC-109](https://linear.app/openai/issue/LSC-109/sequence-and-alignment-viewer-qualify-every-refreshed-starter-example) clean-host qualification applies only to Sequence Viewer `0.1.26`; qualification of `0.1.43` is pending. Its `LSC_109_QUALIFICATION.md` and `lsc-109-qualification.json` evidence remains in the canonical source; do not present historical evidence, ordinary developer checks, or deterministic checks as qualification of the current release.\n\n- Exact ENA prompt: `Fetch ENA DRR037765 first 500 reads to active workspace; open and report live length range, GC, Q30, and subset provenance`. Codex retrieves the exact ENA file report and FASTQ archive, requires the pinned 127,526-byte archive MD5 `81735432a6f578b332aae58cdbd95231`, validates all 967 source reads, and writes only the first 500 complete canonical records to the authorized workspace. Verify the 480,372-byte subset SHA-256 `46bd72991d9c9c2bf64751e88e52548d852d5fa021da4815ee6f6517a51b18b9` and write an honest Codex-authored subset receipt before calling `sequence.open_from_chat` once with its exact absolute local path. Coordinated metadata or payload drift fails closed. After the viewer mounts, report the 469–471 bp range, GC, and Q30 only from live viewer context; preserve the verified subset provenance in the answer.\n- Exact Alignment prompt: `Fetch UniProt P01116/P01111/P01112 alignment; map conserved motifs to KRAS, compute distances/tree, publish Newick to workspace`. Codex retrieves the three reviewed 189-aa `SV=1` UniProtKB records from their fixed official FASTA endpoints, verifies sequence identities, digests, and RAS motifs, and uses an authorized deterministic center-star workflow in fixed KRAS/NRAS/HRAS order with match `2`, mismatch `-1`, and gap `-2`. Require the exact 3×191, 786-byte aligned FASTA SHA-256 `cb32dd89ca7855f7666fbdf3f2ff926f935b1dbc9e7f57573f884dda7e59c68f`, record the actual producer and parameters in Codex-authored provenance, and call `sequence.open_from_chat` exactly once with the aligned file's exact absolute local path. Set exact row `P01116` as reference; map KRAS residues 10–17, 30–38, 60–76, and 116–119; compare the conserved GTPase core with the divergent CAAX tails; compute a distance matrix and exploratory neighbor-joining tree. If the user requests workspace Newick, Codex extracts the exact completed `sequence.run_analysis` tree result and creates `RAS-P01116-P01111-P01112-NJ.nwk` plus an accurately Codex-authored provenance sidecar using its authorized workspace tools without overwriting. The receipt records the actual `sequence-viewer-guide-tree-v1` analysis engine, neighbor joining, uncorrected p-distance, row identity, warning, source and output digests, and Codex as publisher. Plugin workspace publication is optional only when an independently authenticated source-bound workspace capability exists. Do not present a three-leaf guide tree as publication-grade phylogeny.\n- Exact NCBI prompt: `Fetch NCBI NC_001416.1 to active workspace; open it, map cI to OR1–OR3, and translate cI with code 11`. Codex retrieves exact RefSeq accession.version `NC_001416.1` from official NCBI EFetch and verifies a complete 48,502-base GenBank record with cI `complement(37227..37940)`, code 11, protein `NP_040628.1`, and OR3/OR2/OR1 annotations. Before writing an honest provenance sidecar, independently reverse-complement the cI bases, recompute code-11 translation, and validate the pinned coding-sequence and 237-aa protein digests against the source qualifier. Call `sequence.open_from_chat` once with the verified GenBank file's exact absolute local path. In Sequence mode select the exact cI CDS, confirm its reverse-strand relationship to the three operators, then call `sequence.run_analysis` for `translate` with start `37227`, end `37940`, frame `-1`, and `geneticCodeId: 11`; compare the result with the annotated translation.\n\nThe release-bound Rfam example remains available outside the default three-prompt portfolio. Codex retrieves only the official versioned Rfam `15.1` seed archive, selects exactly one embedded Stockholm record for `RF00360`, validates its nine-sequence `SEED` alignment, records accurate source provenance, and calls `sequence.open_from_chat` once with the resulting workspace file's exact absolute local path. Treat snoZ107/R87 C/D-box conservation with row-level nuance rather than repeating the former starter claim.\n\nAfter acquisition and validation, preserve the verified database, requested/resolved identifier, derivation or subset rule, safe workspace-relative artifact/provenance paths, byte length, SHA-256, and actual provenance author in the answer. Keep acquisition separate from viewer readiness: the open result means the app is opening, and only live viewer context or an acknowledged action confirms that it loaded. Point to the existing Sequence open from chat card; do not open another card to check readiness or infer scientific results from the accession or these instructions.\n\n## Viewer Control Workflow\n\nUse `sequence.control_viewer` only for the active mounted viewer and only with the `viewerSessionId` published in its current model context. Coordinates are 1-based.\n\nRun mounted-viewer control in the same conversation that contains the viewer. Do not delegate these actions to a subagent, inspect the webview through browser or DevTools automation, or search the source tree for UI state. The app's current model context and `sequence.control_viewer` are the supported control path. When an opening request also includes control actions, open the viewer first, re-read its model context, and then call `sequence.control_viewer` directly for each requested action.\n\n- `set_toolbar_visibility`: pass `{sessionId, action: \"set_toolbar_visibility\", visible: true}` to show and pin the toolbar, or `visible: false` to hide it; this changes the same state as **Show toolbar** and **Hide toolbar** in both Sequence and Alignment modes. A hidden toolbar temporarily reappears on top-edge pointer hover or keyboard focus.\n- `set_display_mode`: move the live viewer between `fullscreen` and `inline`; this controls the host layout, not toolbar visibility or opening `presentation`.\n- `set_mode`: switch between Sequence and Alignment when the artifact supports both.\n- `set_workbench_panel` and `set_workbench_disclosure`: query `workbench-panels` or paginated `workbench-disclosures` first, then use exact returned group/panel/disclosure IDs. `panel: null` closes a tool panel; expanding a registered disclosure reveals its containing panel and ancestors. Respect `applied: false` when a target is unavailable or protected pending approval/manual-copy state prevents hiding it. Never approve a user confirmation through these controls.\n- `dismiss_workbench_feedback`: query `workbench-feedback` for exact registered copy/session-error IDs, then pass `feedbackId` to dismiss that feedback. The query does not return manual-copy sequence content. This action cannot approve, confirm, cancel or overwrite a source write.\n- `set_sequence_record`: switch to an exact record ID, source label, or unambiguous description from the structured `sequenceRecords` context. `set_sequence_record_browser` controls search, sort, zero-based page and expansion; query `sequence-ui-state` for the applied browser state and `records` for metadata pages.\n- `focus_sequence_coordinate`, `select_sequence_range`, or `select_sequence_feature`: focus coordinates, select a range, or pin an annotated feature. Prefer exact feature IDs from structured `features` context, but a unique case-insensitive feature type, label, or qualifier value such as `CDS` or `kinase domain` also works. If a biological selector is ambiguous, use the returned exact candidate ID; include `record` when the file contains multiple records. For a circular origin-spanning range, set `wraparound: true`, pass the biological start after the origin and end before the origin, and preserve the returned two segments.\n- `search_sequence` and `navigate_sequence_search_hit`: search the displayed sequence, including reverse-complement matches for nucleic acid records, and move through the resulting hits.\n- `set_sequence_annotation_index`: control label/type search, zero-based page and expansion of the map's annotation index. Query `features` for exact IDs, qualifiers and compound intervals outside the displayed overview; `navigate_sequence_feature` moves to the next or previous feature.\n- `set_sequence_view_options`: choose a molecule-compatible residue palette, wrap width, feature/translation/quality visibility, linear/circular/split layout, forward or reverse-complement orientation, synchronized overview/detail behavior, an explicit NCBI genetic-code table, or `originRangeExpanded`. Map projections never change source-coordinate semantics.\n- `set_chromatogram_view_options`: set `firstBase` and `basesPerWindow` (1–100). Query `chromatogram` for at most 100 original-orientation called bases and sample pages up to 500 rows. Base coordinates are 1-based inclusive; trace sample indices are explicitly zero-based. Preserve the returned quality encoding.\n- `set_read_pileup_options`, `select_read`, and `clear_read_selection`: use the same MAPQ/flag/strand filters, sort, base/soft-clip visibility and selected-read state as the UI. Query `reads`, `coverage`, `read-pileup-state` or `read-detail`. Use exact `trackId` and `sourceReadIndex` from a current query; that zero-based index belongs to the loaded track array, not the source-file position.\n- `set_quality_view_options`: expand quality distributions, methods or named data tables. Query `quality-report` for the same bounded report shown in the viewer and `sequence-ui-state` for display options; a pending job is not a completed report.\n- `clear_sequence_selection`: clear the active sequence range and pinned feature.\n- `focus_alignment_cell`, `focus_alignment_reference_coordinate`, `select_alignment_columns`, or `select_alignment_rows`: focus an alignment row/column, map an ungapped active-reference coordinate into the alignment, or select columns/rows. Columns are 1-based inclusive; an empty `rows` array clears row selection.\n- `set_alignment_reference`: use `consensus`, `none`, or an exact row ID or label.\n- `search_alignment` and `navigate_alignment_search_hit`: search the alignment motif view and move through the resulting hits.\n- `filter_alignment_rows`, `set_alignment_row_visibility`, or `show_all_alignment_rows`: filter rows by label or description, hide or show exact row IDs or labels, or restore every row.\n- `set_alignment_view_options`: set molecule interpretation, analysis and search scopes, cell width, color mode, residue palette, annotation and metric tracks, row sort key/direction, sequence-logo help, identical-as-dots rendering, and RNA structure overlays. Use modality-compatible colors and palettes.\n- `clear_alignment_selection` or `reset_alignment_view`: clear the current focus/selection or restore default alignment controls.\n- `compute_alignment_guide_tree`: compute the legacy exploratory UPGMA view. Prefer `sequence.run_analysis` with `build-tree` for the graphical NJ/UPGMA workbench and provenance-bearing result.\n\nAfter a successful control action, briefly say what changed. Do not claim that a requested state changed when the tool reports `applied: false`.\n\n## Scientific Workbench Workflow\n\nTreat immediate view controls and scientific operations differently. Controls are synchronous and idempotent. Analyses, alignment, edits, evidence loading, exports, and sessions are typed workbench operations tied to the current `viewerSessionId`.\n\n- Use `sequence.query_viewer` whenever context says a collection is truncated or the requested record, feature, sequence/quality range, alignment row/column, metric, hit, track, tree node, variant, coverage bin, read, job, or artifact is not in the compact context. Follow `nextCursor`; never guess omitted state.\n- Use `sequence.run_analysis` for statistics, genetic-code-aware translation, ORFs, restriction sites/digest, exploratory primer candidates, distance matrices, graphical NJ/UPGMA trees, or document-scoped `quality-report`. The quality report accepts an optional `adapterSequence` of 8–64 A/C/G/T bases; it samples retained reads rather than the current selected range. Select the relevant range/rows for other analyses when appropriate. Report the returned engine, parameters, limitations, truncation, and coordinate system.\n- Use `sequence.align` for a new pairwise or center-star alignment from exact record/row IDs. It produces a derived aligned-FASTA artifact and never overwrites the source. The built-in engine is exploratory; hand off publication or large-production MSA work to an approved MAFFT/Clustal workflow and reopen the returned alignment.\n- Use `sequence.edit_copy` for typed sequence insert/delete/replace/reverse-complement/rotation operations or alignment gap/column/row/group/sort operations. Edits apply only to the in-memory copy and support undo/redo. Export the copy explicitly.\n- Use `sequence.manage_annotations` to add, update, delete, or import features from a loaded annotation track. Preserve qualifier and coordinate provenance. Resolve duplicate IDs explicitly.\n- Use `sequence.load_track` for GFF3/GTF/BED, VCF, SAM, or indexed regional BAM/CRAM evidence on an opened sequence/reference. BAM/CRAM are not primary viewer documents. BAM needs a BAI/CSI index (default: `<path>.bai`). CRAM needs a CRAI index (default: `<path>.crai`) and usually a matching reference FASTA path. Keep indexed windows at or below 100,000 bases. Inspect mapping diagnostics, loaded-source coverage and disclosed downsampling before interpreting evidence; base-level pileup detail requires a window of at most 200 bases. Editing the reference copy invalidates imported evidence placement rather than remapping it; undo the edit or reopen a matching source reference. Display-only reverse-complement projection does not invalidate the source binding.\n- Use `sequence.export_artifact` for sequence/alignment data, annotations, tables, SVG figures, Newick, or JSON. Private artifact persistence remains the default. When an independently authenticated plugin workspace capability exists and the user explicitly asks to publish beside the opened source, pass `destination: {kind: \"workspace\", base: \"opened-source\", relativePath: \"...\"}` with a source-relative path; safe `..` is allowed only when the server confirms the result remains inside the same active workspace root. Never pass an absolute, drive, UNC, URL, or guessed path. In-view **Publish** actions use an explicit, source-bound workspace Save As confirmation. If that capability is unavailable, plugin publication must fail closed. Codex may separately use its own authorized workspace tools to save a small, exact, user-requested result that is already legitimately available in model-visible analysis output, such as the starter's completed Newick tree; identify Codex as publisher and do not claim the plugin published or signed it. Otherwise preserve the private artifact and explain the missing authorization; do not offer browser **Download**, which Codex blocks. If clipboard access is unavailable, in-view Copy actions expose at most 128 KiB of exact, read-only selectable text for manual **Command+C** or **Ctrl+C**; larger selections require authorized workspace publication. Do not call the app-only preflight or chunk tools directly. Use `sequence.save_session` and `sequence.restore_session` for round-trippable view, selection, copy, jobs, tracks, and derived artifacts; sessions are never workspace-published. Use `sequence.cancel_job` with the exact running job ID.\n\nPrefer contextual workflows over listing every capability. Examples: select a CDS then translate; select a target then design primers; load a VCF then query variants in the visible region; select alignment rows then realign/build a tree/export Newick. The viewer keeps its CSP closed: use approved Codex research or science tools for BLAST, structure linkage, RNA folding, CRISPR/cloning, genome-wide primer specificity, publication-grade phylogenetics, or other external engines, then load or open their traceable artifacts in the viewer.\n\n## Supported Artifacts\n\n- Sequence-first files: FASTA, FASTQ, GenBank, EMBL, and common plain biological sequence suffixes.\n- Bounded binary imports: original-orientation processed ABIF 1.01 (`.ab1`, `.abi`), SCF 2.00/3.00 (`.scf`), and verified-revision SnapGene DNA (`.dna`). Unsupported versions/revisions fail closed; these are not full native application document imports.\n- Alignment-first files: aligned FASTA, AFA, CLUSTAL, Stockholm, A2M, A3M, MSF, PHYLIP, NEXUS, and PIR.\n- Ambiguous rectangular FASTA files open in the combined viewer with an in-view Sequence / Alignment mode choice.\n\n## Boundaries\n\n- Do not read, inline, truncate, or summarize file contents merely to open the viewer.\n- Do not pass a workspace path, `file://` URI, or fabricated `codex-resource://` URI to `sequence.open`.\n- When the MCP host exposes active local roots, `sequence.open_from_chat` confines both relative and absolute paths to those roots. When roots are unavailable, it requires an exact absolute local path.\n- `sequence.open_from_chat` accepts only supported files.\n- Do not infer the user's current selection from the source file after the app is open. Use the viewer context because the user may have changed modes, rows, columns, or selections interactively.\n- Treat FASTQ quality as Phred+33 unless the source explicitly establishes another encoding. Detailed quality reports use the first eligible retained reads, at most 1,000 reads and 100,000 bases; report their actual scope separately from streaming summaries. They are descriptive reports, not FastQC runs, automatic contamination/pass/fail assessments or whole-file QC.\n- Binary inputs are capped at 8 MiB and saved sessions at 512 KiB. Do not drop trace signals silently to fit a session or claim native ABIF/SCF/SnapGene export. Preserve originals for data not represented by the import. SCF confidence bytes are source confidence, not assumed calibrated Phred scores; trace views/queries retain original read orientation.\n- Treat built-in NJ/UPGMA trees, pairwise/center-star alignment, and primer scoring as exploratory, not publication-grade or experimentally validated inference.\n- Never silently choose genetic code 1 when source features declare a different `transl_table` or multiple tables. Use the source-derived code when unique; otherwise specify or ask for `geneticCodeId`.\n- Treat `activeTarget` as authoritative. Mention `transientFocus` separately only when both are populated and refer to different coordinates/rows; pointer movement must not replace the user's selected target.\n- Preserve compound GenBank and EMBL feature segments; do not describe the gaps between joined segments as part of the feature.\n\n## Follow-Up Questions\n\nWhen answering from the mounted viewer context, prioritize the literal current state before adding biological interpretation. Useful context includes `activeTarget`, distinct `transientFocus`, coordinate semantics, source identity, current mode, record/feature inventories, selected sequence segments, genetic code, FASTQ QC, exact compound features, selected alignment rows/columns, reference mappings, conservation, tree provenance, loaded evidence/downsampling, jobs, and derived artifacts. Query omitted pages instead of inferring them from source bytes.\n"
}